Software Upgrade

This document describes the upgrade procedure of a aiozd full-node to a new version.

Cosmovisor

The CosmosSDK provides a convenient process manager that wraps around the aiozd 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 here (opens in a new tab).

Setup

To get started with Cosmovisor, first download it

go get github.com/cosmos/cosmos-sdk/cosmovisor/cmd/cosmovisor

Set up the environment variables

echo "# Setup Cosmovisor" >> ~/.profile
echo "export DAEMON_NAME=aiozd" >> ~/.profile
echo "export DAEMON_HOME=$HOME/.aioz" >> ~/.profile
source ~/.profile

Create the appropriate directories

mkdir -p ~/.aioz/cosmovisor/upgrades
mkdir -p ~/.aioz/cosmovisor/genesis/bin/
cp $(which aiozd) ~/.aioz/cosmovisor/genesis/bin/
 
# verify the setup.
# It should return the same version as aiozd
cosmovisor version

Now aiozd can start by running

cosmovisor start

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 latest binary and place it under $DAEMON_HOME/cosmovisor/upgrades/<name>/bin where <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.

export DAEMON_ALLOW_DOWNLOAD_BINARIES=true

Manual Software Upgrade

First, stop your instance of aiozd. Then, obtain the latest version of aiozd by downloading it from here and replace the existing executable file with the new one.

If there are no breaking changes, then you can simply restart the node by running:

aiozd start

Upgrade Genesis File

:::warning 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 in a new tab). If you are entering a public testnet, fetch the genesis from the appropriate testnet in the testnet repo (opens in a new tab). Otherwise, fetch it from your trusted source.

Save the new genesis as new_genesis.json. Then replace the old genesis.json with new_genesis.json

cd $HOME/.aioz/config
cp -f genesis.json new_genesis.json
mv new_genesis.json genesis.json

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:

cd $HOME/.aioz/config
aiozd export --for-zero-height --height=<export-height> > new_genesis.json

The command above takes 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 genesis.json with new_genesis.json.

cp -f genesis.json new_genesis.json
mv new_genesis.json genesis.json

At this point, you might want to run a script to update the exported genesis into a compatible genesis with your new version. For example, if the attributes of an Account type changed, a script should query encoded account from the account store, unmarshal them, update their type, re-marshal, and re-store them. You can find an example of such script here (opens in a new tab).

Reset Data

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.

aiozd tendermint unsafe-reset-all

Your node is now in a pristine state while keeping the original priv_validator.json and 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.

Restart

If there are no breaking changes then you can simply restart the node by running:

aiozd start