Adjust Node.Counter for KES

With Vasil upgrade your node.counter for KES must be just one count higher than the last OpCertC value for your last block. If this value needs to be adjusted, this guide will show you how.

UPDATED: 11/26/24

Credits to Earn Coin Pool for documenting the procedure.

Did you know? "KES" stands for Key Evolving Signature

Welcome!

There are two method you can use to Rollback your node.counter. Please review and choose the method you prefer.

Good to know: This was created on July 2022 and process may change over time

CLI Method

Step 1 - Look up Operational Certificate Numbers

When it's time to update your KES you can run the following command on your block producer to confirm you have the correct Operational Certificate Numbers

Note path to node.cert and adjust if needed. Path in example is based off Coincashew guide for setting up a stake pool.

cardano-cli conway query kes-period-info --mainnet  \
  --op-cert-file $NODE_HOME/node.cert

Results should look similar to the following:

✓ The operational certificate counter agrees with the node protocol state counter
✓ Operational certificate's kes period is within the correct KES period interval
{
    "qKesNodeStateOperationalCertificateNumber": 4,
    "qKesCurrentKesPeriod": 505,
    "qKesOnDiskOperationalCertificateNumber": 5,
    "qKesRemainingSlotsInKesPeriod": 6832926,
    "qKesMaxKESEvolutions": 62,
    "qKesKesKeyExpiry": "2022-09-22T21:44:51Z",
    "qKesEndKesInterval": 558,
    "qKesStartKesInterval": 496,
    "qKesSlotsPerKesPeriod": 129600
}

This line is the Operational Certificate that your pool used to mint its last block "qKesNodeStateOperationalCertificateNumber": 4,

This line is the counter number of your current Operational Certificate: "qKesOnDiskOperationalCertificateNumber": 5,

If these number are NOT the same, as for the example above NodeState=4 and OnDisk=5 then you need to rollback your counter. In this case the node counter would need to be rolled back from 5 to 4 If, for example, NodeState and OnDisk =4, then you are all set and can proceed to renewing your KES following the normal procedure here.

✅Also If you have never minted a block since you started your pool, then you will need to rollback your counter back to 0

Step 2 - Check current value of your node.counter

⚠️ON AIR GAPPED MACHINE:

navigate to where your node.counter file is. 📁In this example it's located in our home directory in a folder called: cold-keys. So we run this command to output node.counter information.

cat $HOME/cold-keys/node.counter

✍️Take note that "Next certificate issue number: x"

node.counter MUST be ONE greater than "qKesNodeStateOperationalCertificateNumber" value.

For example, "qKesNodeStateOperationalCertificateNumber": 4, So our node.counter should read "Next certificate issue number: 5"

If your "Next certificate issue number" is one higher you are all set and can continue to normal renew KES process found here.

⚠️Only if it's not one higher should you proceed to the next step

Step 3 - KES Rollback

If you need to adjust your node.counter navigate to your node.counter file on your Air Gapped Machine.

In this example it is located in our home directory in a folder called: cold-keys. If your file is not located there please adjust file path.

🛑 If you have not backed up your node.counter file now is a good time to do that before you proceed.

⚠️ON AIR GAPPED MACHINE: Since our "qKesNodeStateOperationalCertificateNumber": 4, we want it to be "4+1". Please replace 4 with your "qKesNodeStateOperationalCertificateNumber": value. Edit node.counter using following commands.

cd $HOME/cold-keys/
cardano-cli conway node new-counter \
--cold-verification-key-file node.vkey \
--counter-value $((4 + 1)) \
--operational-certificate-issue-counter-file node.counter

Final Step

Now that your node.counter is adjusted you may proceed to renew your KES following the normal procedure here.

Congratulations you did it!

Manual Method

Step 1 - Look up OpcertC

Navigate to your pool on adapools.org. Once on your pool page click on the blocks tab and look at your last block. Look at the OpCertC column and make note of the number.

If you have never made a block then you will need to set your "Next certificate issue number: 0" and "cborHex" line to 0. cborHex example: xxx0xxxxx.... See Step 3 below for more details

Step 2 - Check current value of your node.counter

⚠️ON AIR GAPPED MACHINE:

navigate to where your node.counter file is. 📁In this example it's located in our home directory in a folder called: cold-keys. So we run this command to output node.counter information.

cat $HOME/cold-keys/node.counter

✍️Take note that "Next certificate issue number: x"

node.counter MUST be ONE greater than the most recently created block's OpCertC value.

For example, if your OpCertC value is 4 for your last block, then your node.counter should read "Next certificate issue number: 5"

If your "Next certificate issue number" is one higher you are all set and can continue to normal renew KES process found here.

⚠️Only if it's not one higher should you proceed to the next step

Step 3 - KES Rollback

If you need to adjust your node.counter navigate to your node.counter file on your Air Gapped Machine. In this example it is located in our home directory in a folder called: cold-keys. If your file is not located there please adjust file path.

🛑 If you have not backed up your node.counter file now is a good time to do that before you proceed.

You can edit node.counter using nano command.

cd $home/cold-keys
nano node.counter

The file should look similar to the following. (We replaced letters and numbers after four digits just as an example to make easier to read.)

{
    "type": "NodeOperationalCertificateIssueCounter",
    "description": "Next certificate issue number: 5",
    "cborHex": "8205xxxxxxxxxxxxxxxxxxxxxxxxxx"
}

Navigate to this line: "description": "Next certificate issue number: x" and change "x" to one number higher than your OpCertC number.

Then navigate to "cborHex" line:

If your desired next certificate issue is 9 or under:

You must change the 4th number to match your next certificate issue number. For example if your "Next certificate issue number: 5" then the 4th digit in the cborHex should match this number. example: xxx5xxxxx.....

If your desired next certificate issue is 15 or under:

You must change the 4th number to the hex of the number to match your next certificate issue number. For example the hex for 13 is "d" so the fourth digit should be "d" xxxdxxxxx..... you can use this converter to find the hex value

If your desired next certificate issue is OVER 15:

You must change the 3rd and 4th number to the hex of the number to match your next certificate issue number. For example the hex for 16 is "10" so the third digit should be"1" and the fourth digit should be "0" xx10xxxxx..... you can use this converter to find the hex value

For our example we wanted our counter to be adjusted so the next certificate issue was 5. So it should look similar to this:

{
    "type": "NodeOperationalCertificateIssueCounter",
    "description": "Next certificate issue number: 5",
    "cborHex": "8205xxxxxxxxxxxxxxxxxxxxxxxxxx"
}

(We replaced letters and numbers after four digits just as an example to make easier to read.)

Step 4

Now that your node.counter is adjusted you may proceed to renew your KES following the normal procedure here.

Congratulations you did it!

Contributors

Thanks to the following pools for helping to put together these guides. Please consider delegating to their pools to support them. Are you a pool? Consider buying them a coffee

Apex Cardano Pool - Ticker: APEX

Earn Coin Pool - Ticker: ECP

Envy Stake Pool - Ticker ENVY

PGWAD

xSPO Alliance