Validator upgrade guide

💡

For non-breaking changes, you can minimize the downtime by keeping your existing validator node running while you download and configure the new version according to the steps below. Once the upgrade is fully configured and ready to run, stop the old node and start the new one.

A fully Zero-downtime upgrade procedure is coming in a future update.

v0.3.x → v0.4 (Breaking Change)

v0.4 switches to a new consensus deployment with staking. For this reason, the validator must be set up from scratch without reusing the old database stored at data/node/genlayer.db. You do not need to keep your existing validator node running while you download and configure the new version.

This release involves a change from a single validator address to owner/operator separation. You will need to follow the setup guide to create your new Validator Wallet.

⚠️

Recommended: Keep your current validator key as the operator key

To maintain continuity, retain your current keystore and use your existing validator address as the operator address when following the setup guide. You can find your current validator address in configs/node/wallet.yaml.

Stop the node if it is running.
Note your current validator address from configs/node/wallet.yaml - you'll use this as your operator address.
Back up the configs/node/config.yaml file so that you can refer to any values you have set in the previous version.
Back up the data/node/keystore folder so that you can maintain your previous operator key.
Download the packaged binary.
Install the new version.
Remove the storage folder data/node/genlayer.db.
Check that configuration is correct by running genlayernode doctor command.
Start the node.

Assuming already have the new tarball downloaded and extracted, copy your old keystore files to the new installation:

mkdir -p <path-to-new-installation>/data/node/keystore/
cp <path-to-old-installation>/data/node/keystore/* <path-to-new-installation>/data/node/keystore/

Configuration Change

v0.3.8 introduces updated consensus contract deployment with new contract addresses. Critical: Some consensus contract addresses have changed, and validators must update their consensus configuration to continue participating in the network.

Stop the node if it is running.
Back up your configs/node/config.yaml file to preserve your current settings.
Download and install the new v0.3.8 packaged binary.

Update the new configuration with any changes you had previously applied (you can check your config.yaml backup) and make sure you have the following consensus contracts in your configs/node/config.yaml:

consensus:
  # Asimov - Phase 3
  contractmanageraddress: "0x0761ff3847294eb3234f37Bf63fd7F1CA1E840bB" # ConsensusManager Smart Contract Address
  contractmainaddress: "0xe30293d600fF9B2C865d91307826F28006A458f4" # ConsensusMain Smart Contract Address
  contractdataaddress: "0x2a50afD9d3E0ACC824aC4850d7B4c5561aB5D27a" # ConsensusData Smart Contract Address
  contractidlenessaddress: "0xD1D09c2743DD26d718367Ba249Ee1629BE88CF33" # Idleness Smart Contract Address
  contractstakingaddress: "0x31Cb4018ccB7d4F30419d367b6C5c7677AAE30E7" # Staking Smart Contract Address
  genesis: 817855 # Genesis block number for this consensus deployment

Verify your configuration by running genlayernode doctor - this will validate all contract addresses and connectivity.
Start the node with the updated configuration.

🚨

Critical: Staking Address Update Required

Failure to update the consensus contract addresses will prevent your validator from:

Participating in consensus rounds
Being selected as an activator, a leader or activator

The doctor command will now specifically validate these addresses - ensure it passes before starting your node.

v0.2 → v0.3 (Breaking Change)

v0.3 switches to a new consensus deployment. For this reason, the validator must be set up from scratch without reusing the old database stored at data/node/genlayer.db. You do not need to keep your existing validator node running while you download and configure the new version.

Stop the node if it is running.
Back up the configs/node/config.yaml file so that you can refer to any values you have set in the previous version.
Download the packaged binary.
Install the new version.
Remove the storage folder data/node/genlayer.db.
Check that configuration is correct by running genlayernode doctor command.
Start the node.

ℹ️

Install the new version in the same directory as the previous installation. This ensures that any paths referenced in the configuration remain the same and helps maintain continuity in your setup. If you want to install the new version in a different directory, copy your data/keystore and configs/node/wallet.yaml to the new directory to keep using the same wallet.

v0.1.0-testnet008 → v0.2.0-testnet001

GenVM configuration has changed, please follow the new instructions in the GenVM configuration section in the validator setup guide.
Back up the configs/node/config.yaml, configs/node/wallet.yaml, and data/node/keystore folders so you can retain your previous configuration and wallet access.

Setup Guide Changelog