# Upgrade Your Node
This document describes the upgrade procedure of a
gaiad full-node to a new version.
The Cosmos SDK provides a convenient process manager that wraps around the
gaiad binary and can automatically swap in new binaries upon a successful governance upgrade proposal. Cosmovisor is entirely optional but recommended. More information can be found in cosmos.network docs (opens new window) and cosmos-sdk/cosmovisor/readme (opens new window).
To get started with Cosmovisor first download it
Set up the environment variables
Create the appropriate directories
gaiad can start by running
# Preparing an Upgrade
Cosmovisor will continually poll the
$DAEMON_HOME/data/upgrade-info.json for new upgrade instructions. When an upgrade is ready, node operators can download the new binary and place it under
<name> is the URI-encoded name of the upgrade as specified in the upgrade module plan.
It is possible to have Cosmovisor automatically download the new binary. To do this set the following environment variable.
# Manual Software Upgrade
First, stop your instance of
gaiad. Next, upgrade the software:
NOTE: If you have issues at this step, please check that you have the latest stable version of GO installed.
Your full node has been cleanly upgraded! If there are no breaking changes then you can simply restart the node by running:
# Upgrade Genesis File
If the new version you are upgrading to has breaking changes, you will have to restart your chain. If it is not breaking, you can skip to Restart
To upgrade the genesis file, you can either fetch it from a trusted source or export it locally.
# Fetching from a Trusted Source
If you are joining the mainnet, fetch the genesis from the mainnet repo (opens new window). If you are joining a public testnet, fetch the genesis from the appropriate testnet in the testnet repo (opens new window). Otherwise, fetch it from your trusted source.
Save the new genesis as
new_genesis.json. Then replace the old
Then, go to the reset data section.
# Exporting State to a New Genesis Locally
If you were running a node in the previous version of the network and want to build your new genesis locally from a state of this previous network, use the following command:
The command above take a state at a certain height
<export-height> and turns it into a new genesis file that can be used to start a new network.
Then, replace the old
At this point, you might want to run a script to update the exported genesis into a genesis that is compatible with your new version. For example, the attributes of a the
Account type changed, a script should query encoded account from the account store, unmarshall them, update their type, re-marshal and re-store them. You can find an example of such script here (opens new window).
# Reset Data
If the version <new_version> you are upgrading to is not breaking from the previous one, you should not reset the data. If it is not breaking, you can skip to Restart
If you are running a validator node on the mainnet, always be careful when doing
gaiad unsafe-reset-all. You should never use this command if you are not switching
Make sure that every node has a unique
priv_validator.json. Do not copy the
priv_validator.json from an old node to multiple new nodes. Running two nodes with the same
priv_validator.json will cause you to get slashed due to double sign !
First, remove the outdated files and reset the data. If you are running a validator node, make sure you understand what you are doing before resetting.
Your node is now in a pristine state while keeping the original
config.toml. If you had any sentry nodes or full nodes setup before, your node will still try to connect to them, but may fail if they haven't also been upgraded.