# Cosmos Chains Upgrade Guide

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

**Status**: WIP

**Authors**:
- [@fedekunze](https://github.com/fedekunze) - Evmos
- [@marbar3778](https://github.com/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](https://docs.cosmos.network/master/migrations/pre-upgrade.html) 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](https://docs.cosmos.network/master/run-node/cosmovisor.html).

### Manual Upgrade

1. Halt the node by setting a `--halt-height` when starting your node:

    evmosd start --halt-height=<height>

2. 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

3. [Migrate](#genesis-migration) the `genesis.json` file to make it compatible with the new version. You can skip this if there are not breaking API changes.
4. Create a new node using the `init` command.

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

5. Copy the genesis into your `evmosd` config.

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

6. 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](#manual-upgrade)

> Note: If the IBC client expires, it can be recovered with a [governance proposal]( https://ibc.cosmos.network/main/ibc/proposals.html#how-to-recover-an-expired-client-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?

## References

- https://github.com/cosmos/cosmos-sdk/discussions/9740
- https://ibc.cosmos.network/main/ibc/upgrades/quick-guide.html#step-by-step-upgrade-process-for-sdk-chains
- https://ibc.cosmos.network/main/ibc/proposals.html#how-to-recover-an-expired-client-with-a-governance-proposal