Issuing a New Operational Certificate
Your stake pool requires a valid operational certificate to verify that the pool has the authority to run.
A current KES key pair is required to establish an operational certificate for your stake pool. A KES period indicates the time span when an operational certificate is valid. An operational certificate expires 90 days after the KES period defined in the operational certificate. You must generate a new KES key pair and operational certificate every 90 days, or sooner, for your stake pool to mint blocks.
The private KES key is required to start the block producing node for your stake pool. The public KES key is not sensitive.
Issuing an operational certificate also uses a counter that increments by exactly one (1) for each unique operational certificate that a stake pool uses to mint blocks. In a valid operational certificate, the counter value that you use to issue the operational certificate must be consistent with the current counter value for your stake pool registered on the Cardano blockchain by the protocol.
A Companion Script that can help you with rotating KES keys and issuing a new Operational Certificate is available [here](kes-rotate-companion-script.md)
Determining the Counter Value
To retrieve the current counter value for your stake pool registered by the blockchain protocol:
In a terminal window on your block producer node, type:
The cardano-cli query kes-period-info
command returns output similar to:
The value of the qKesNodeStateOperationalCertificateNumber
key indicates the current counter value for your stake pool registered by the blockchain protocol. The value of the qKesOnDiskOperationalCertificateNumber
key indicates the counter value of the current operational certificate that your stake pool uses.
For a new operational certificate, the counter value must be exactly one (1) greater than the current value of the qKesNodeStateOperationalCertificateNumber
key.
If qKesOnDiskOperationalCertificateNumber
is more than one (1) greater than qKesNodeStateOperationalCertificateNumber
then the operational certificate is invalid. Your stake pool cannot mint blocks using an invalid operational certificate.
Minting Your First Block
When your stake pool has minted zero (0) blocks, then no value for qKesNodeStateOperationalCertificateNumber
is registered by the blockchain protocol. Therefore, retrieving the current counter value for your stake pool returns the value null
for the qKesNodeStateOperationalCertificateNumber
key.
After a stake pool mints a block for the first time, then retrieving the current counter value returns the value zero (0) for the qKesNodeStateOperationalCertificateNumber
key.
Therefore, when your stake pool has minted zero (0) blocks, then you MUST set the value zero (0
) for the qKesOnDiskOperationalCertificateNumber
key so that your stake pool creates a block successfully when elected to mint a block for the first time.
Setting the Counter Value
When you issue a new operational certificate, a node.counter
file sets the counter value for the new certificate.
If you follow the Coin Cashew instructions, then you created a node.counter
file when Generating Keys for the Block-producing Node
When you run the cardano-cli query kes-period-info
command on your block producer node, if the value of the qKesOnDiskOperationalCertificateNumber
key equals the value of the qKesNodeStateOperationalCertificateNumber
key, then your stake pool minted at least one block using the current operational certificate and you do not need to set the counter value manually.
If the value of the qKesOnDiskOperationalCertificateNumber
key is greater than the value of the qKesNodeStateOperationalCertificateNumber
key, then prior to issuing a new operational certificate you need to set the counter value using the following procedure.
To set the counter value for issuing a new operational certificate:
To create a new
node.counter
file having the required counter value, type the following command in a terminal window on your air-gapped, offline computer where<NodeCertificateNumber>
is the current value of theqKesNodeStateOperationalCertificateNumber
key for your stake pool:
If the current value of the qKesNodeStateOperationalCertificateNumber
key for your stake pool is null
, then set the --counter-value
option to zero (0
)
To display the contents of the
node.counter
file that you created in step 1, type:
When you generate a new node.counter
file, the value of the description
key is empty until you issue a new operational certificate.
Issuing a New Operational Certificate
To issue a new operational certificate:
In a terminal window on your block producer node, type the following commands to generate a new KES key pair:
Copy the
kes.vkey
file that you generated in step 1 to your air-gapped, offline computer.To issue a new operational certificate, you must set a starting KES period. To calculate the starting KES period for your new operational certificate, type the following commands in a terminal window on your block producer node:
To issue a new operational certificate, type the following command in a terminal window on your air-gapped, offline computer where
<KESvkeyFile>
is the path to thekes.vkey
file that you copied in step 2 and<StartingKESPeriod>
is the starting KES period that you calculated in step 3:
Issuing a new operational certificate increments the value of the node.counter
file by one (1) To display the contents of the node.counter
file, type cat $HOME/cold-keys/node.counter
Copy the
node.cert
file that you created in step 4 to replace the currentnode.cert
file on your block producer node.To restart your block producer node, type:
To verify the operational certificate that you issued in step 4, wait until your block producer node starts, and then type:
In the results of the cardano-cli query kes-period-info
command, prior to your stake pool minting a block using the operational certificate that you issued in step 4, in a valid operational certificate the value of the qKesOnDiskOperationalCertificateNumber
key is greater than the value of the qKesNodeStateOperationalCertificateNumber
key by exactly one (1) The first time your stake pool mints a block using the operational certificate that you issued in step 4, the value of the qKesNodeStateOperationalCertificateNumber
increments by one (1) to equal the value of the qKesOnDiskOperationalCertificateNumber
key.
In a secure location, create backup copies of the KES key files that you generated in step 1; the current
node.counter
file for your stake pool; and, thenode.cert
file that you generated in step 4