Cosmos Chains Upgrade Guide

See issue: https://github.com/cosmos/cosmos-sdk/issues/11504

Status: WIP

Authors:

@fedekunze - Evmos
@marbar3778 - Interchain

Migrations

Genesis Migration

migrate genesis.json to a new file that is compatible with the new version

Automated Genesis Migration

You can use the migrate command to migrate the genesis.json

evmosd migrate

Manual Genesis Migration

Manually change the fields

Store Migrations

The store needs to be migrated (store keys, new parameters)

In-Place Store Migration

Adding a new Module

Editting an existing Module

Adding a new field to Parameters

Migrating records to a new key

Planned Upgrades

Done through a Upgrade governance proposal

Unplanned Upgrades

Cases: security vulnerability

Coordinated upgrades where the validators halt their nodes at a given height
Download new version
Perform genesis
Restart nodes
Needs to have >67% to run the new

Automating Upgrades

An chain upgrade can be done automatically or

Automated Upgrades

Automated upgrades can be executed via upgrade proposals and also by manually setting a fork height that downloads the new binary and performs a migration

Cosmovisor

Cosmovisor is a process manager for Cosmos SDK applications that monitors the governance module for incoming chain upgrade proposals. If it sees a proposal that gets approved, cosmovisor can automatically download the new binary, stop the current binary, switch from the old binary to the new one, and finally restart the node with the new binary.

Cosmovisor allows validators and node operators to:

Ease upgrade progress by automatically downloading new binaries
Apply software upgrades to the application
Back up data before upgrades to ease rollbacks in case the upgrade fails
Execute a pre-upgrade to apply application config changes that are required in the newer version.

Cosmovisor can be used for

NOTE: For additional instructions on how to set up Cosmovisor and its usage, check the original documentation here.

Manual Upgrade

Halt the node by setting a --halt-height when starting your node:
```
evmosd start --halt-height=<height>
```
Export genesis.json
```
evmosd export <moniker> --height=<height>
```
Important: Make sure the new chain height is equal to the value set in halt-height + 1
Migrate the genesis.json file to make it compatible with the new version. You can skip this if there are not breaking API changes.

Create a new node using the init command.

evmosd init <moniker> --chain-id=$CHAIN_ID

Copy the genesis into your evmosd config.

cp genesis.json ~/.evmosd/config/genesis.json

Start the node using start:
```
evmosd start
```

Failed Upgrade

Issues with upgrades can be either because the genesis.json file is not valid (in the case of manual upgrades) or because the store migration failed.

Rollback

Revert node version to the previous version
Use the exported genesis state (i.e not modified through a genesis migration)
Restart the node

Fix Upgrade

Fix the upgrade issues
Release a new patch version with the fixes
Download the new version and perform a manual upgrade

Note: If the IBC client expires, it can be recovered with a governance proposal.

IBC Connections

FAQ

What happens with the previous blockchain data?

The new version will have no data

What do should I do during an upgrade if my node is not running cosmovisor?

Set up a halt-height to gracefully halt your node. Once it does, you will have to manually download the new binary and restart your node.

When is it recommended to bump the chain-id version number?