Upgrade a Validator Node¶
Introduction¶
Upgrading a Polkadot validator node is essential for staying current with network updates and maintaining optimal performance. This guide covers routine and extended maintenance scenarios, including software upgrades and major server changes. Following these steps, you can manage session keys and transition smoothly between servers without risking downtime, slashing, or network disruptions. The process requires strategic planning, especially if you need to perform long-lead maintenance, ensuring your validator remains active and compliant.
This guide will allow validators to seamlessly substitute an active validator server to allow for maintenance operations. The process can take several hours, so ensure you understand the instructions first and plan accordingly.
Prerequisites¶
Before beginning the upgrade process for your validator node, ensure the following:
- You have a fully functional validator setup with all required binaries installed. See Set Up a Validator and Validator Requirements for additional guidance
- Your VPS infrastructure has enough capacity to run a secondary validator instance temporarily for the upgrade process
Session Keys¶
Session keys are used to sign validator operations and establish a connection between your validator node and your staking proxy account. These keys are stored in the client, and any change to them requires a waiting period. Specifically, if you modify your session keys, the change will take effect only after the current session is completed and two additional sessions have passed.
Remembering this delayed effect when planning upgrades is crucial to ensure that your validator continues to function correctly and avoids interruptions. To learn more about session keys and their importance, visit the Keys section.
Keystore¶
Your validator server's keystore folder holds the private keys needed for signing network-level transactions. It is important not to duplicate or transfer this folder between validator instances. Doing so could result in multiple validators signing with the duplicate keys, leading to severe consequences such as equivocation slashing. Instead, always generate new session keys for each validator instance.
The default path to the keystore is as follows:
Taking care to manage your keys securely ensures that your validator operates safely and without the risk of slashing penalties.
Upgrade Using Backup Validator¶
The following instructions outline how to temporarily switch between two validator nodes. The original active validator is referred to as Validator A and the backup node used for maintenance purposes as Validator B.
Session N¶
- Start Validator B - launch a secondary node and wait until it is fully synced with the network. Once synced, start it with the
--validatorflag. This node will now act as Validator B - Generate session keys - create new session keys specifically for Validator B
- Submit the
set_keyextrinsic - use your staking proxy account to submit aset_keyextrinsic, linking the session keys for Validator B to your staking setup - Record the session - make a note of the session in which you executed this extrinsic
- Wait for session changes - allow the current session to end and then wait for two additional full sessions for the new keys to take effect
Keep Validator A running
It is crucial to keep Validator A operational during this entire waiting period. Since set_key does not take effect immediately, turning off Validator A too early may result in chilling or even slashing.
Session N+3¶
At this stage, Validator B becomes your active validator. You can now safely perform any maintenance tasks on Validator A.
Complete the following steps when you are ready to bring Validator A back online:
- Start Validator A - launch Validator A, sync the blockchain database, and ensure it is running with the
--validatorflag - Generate new session keys for Validator A - create fresh session keys for Validator A
- Submit the
set_keyextrinsic - using your staking proxy account, submit aset_keyextrinsic with the new Validator A session keys - Record the session - again, make a note of the session in which you executed this extrinsic
Keep Validator B active until the session during which you executed the set-key extrinsic completes plus two additional full sessions have passed. Once Validator A has successfully taken over, you can safely stop Validator B. This process helps ensure a smooth handoff between nodes and minimizes the risk of downtime or penalties. Verify the transition by checking for finalized blocks in the new session. The logs should indicate the successful change, similar to the example below:
| Created: October 16, 2024