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.
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:
cd $NODE_HOME
cardano-cli conway query kes-period-info \
--${NODE_CONFIG} \
--op-cert-file node.cert
The cardano-cli conway query kes-period-info
command returns output similar to:
✓ Operational certificate's KES period is within the correct KES period interval
✓ The operational certificate counter agrees with the node protocol state counter
{
"qKesCurrentKesPeriod": 15,
"qKesEndKesInterval": 18,
"qKesKesKeyExpiry": null,
"qKesMaxKESEvolutions": 6,
"qKesNodeStateOperationalCertificateNumber": 3,
"qKesOnDiskOperationalCertificateNumber": 3,
"qKesRemainingSlotsInKesPeriod": 690,
"qKesSlotsPerKesPeriod": 300,
"qKesStartKesInterval": 12
}
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.
When you run the cardano-cli conway 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, if the current value of theqKesNodeStateOperationalCertificateNumber
key for your stake pool isnull
then type the following command in a terminal window on your air-gapped, offline computer:
cd $HOME/cold-keys
cardano-cli conway node new-counter \
--cold-verification-key-file $HOME/cold-keys/node.vkey \
--counter-value 0 \
--operational-certificate-issue-counter-file node.counter
OR
If the current value of the qKesNodeStateOperationalCertificateNumber
key for your stake pool is NOT null
, then type the following command in a terminal window on your air-gapped, offline computer where <NodeCertificateNumber>
is the current value of the qKesNodeStateOperationalCertificateNumber
key for your stake pool:
cd $HOME/cold-keys
cardano-cli conway node new-counter \
--cold-verification-key-file $HOME/cold-keys/node.vkey \
--counter-value $(( <NodeCertificateNumber> + 1 )) \
--operational-certificate-issue-counter-file node.counter
To display the contents of the
node.counter
file that you created in step 1, type:
cat $HOME/cold-keys/node.counter
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:
cd $NODE_HOME
cardano-cli conway node key-gen-KES \
--verification-key-file kes.vkey \
--signing-key-file kes.skey
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:
cd $NODE_HOME
# Query the current slot height of the blockchain, and then
# retrieve the value of the slot key in the results
slotNo=$(cardano-cli conway query tip --mainnet | jq -r '.slot')
# Retrieve the number of slots per KES period from the key named slotsPerKESPeriod
# in the Shelley Genesis JSON configuration file that your stake pool uses
slotsPerKESPeriod=$(cat $NODE_HOME/shelley-genesis.json | jq -r '.slotsPerKESPeriod')
# To calculate the current KES period, divide the current slot height by
# the number of slots per KES period
kesPeriod=$((${slotNo} / ${slotsPerKESPeriod}))
StartingKESPeriod=${kesPeriod}
echo StartingKESPEriod: ${StartingKESPeriod}
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:
cd $NODE_HOME
chmod u+rwx $HOME/cold-keys
cardano-cli conway node issue-op-cert \
--kes-verification-key-file <KESvkeyFile> \
--cold-signing-key-file $HOME/cold-keys/node.skey \
--operational-certificate-issue-counter $HOME/cold-keys/node.counter \
--kes-period <StartingKESPeriod> \
--out-file node.cert
chmod a-rwx $HOME/cold-keys
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:
sudo systemctl restart cardano-node
To verify the operational certificate that you issued in step 4, wait until your block producer node starts, and then type:
cd $NODE_HOME
cardano-cli conway query kes-period-info \
--${NODE_CONFIG} \
--op-cert-file node.cert
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
If you want to support this free educational Cardano content or found the content helpful, visit cointr.ee to find our donation addresses. Much appreciated in advance. 🙏
📒Technical writing by Change Pool (ticker CHG)
Last updated