# Chain Upgrade Guide to v0.42
This document explains how to perform a chain upgrade from v0.39 to v0.42.
Please note that the three SDK versions v0.40, v0.41 and v0.42 are functionally equivalent, together called the "Stargate" series. The version bumps are consequences of post-release state-breaking bugfixes.
As a validator, performing the upgrade procedure on your consensus nodes carries a heightened risk of double-signing and being slashed: if your validator node votes for a block, and, in the same block time, restarts the upgraded node, this may lead to double-voting on a block.
The riskiest thing a validator can do is to discover that they made a mistake and repeat the upgrade procedure again during the network startup. If you discover a mistake in the process, the best thing to do is wait for the network to start before correcting it. If the network is halted and you have started with a different genesis file than the expected one, seek advice from the validator community.
- Prior to exporting the state, the validators are encouraged to take a full data snapshot at exported height. Exported
height will be determined by a governance proposal. Data backup is usually done by copying daemon home directory,
Note: we use "simd" as our app throughout this doc, be sure to replace with the name of your own binary.
It is critically important to back-up the validator state file, e.g.:
after stopping your daemon process. This file is updated every block as your validator participates in a consensus
rounds. It is a critical file needed to prevent double-signing, in case the upgrade fails, and the previous chain needs
to be restarted.
In the event that the upgrade does not succeed, validators and operators must downgrade back to old version of the software and restore to their latest snapshot before restarting their nodes.
# Upgrade procedure
The procedure is to export the state from the old binary, and import it with the new binary. First, verify your old binary version (which should use
firstname.lastname@example.org.*) before exporting the state.
Export the state from existing chain using the old binary.
Verify the SHA256 of the (sorted) exported genesis file:
Cross check the hash with other peers (other validators) in the chat rooms.
Install the latest binary (which uses
Migrate the exported state to
email@example.com.*compatible genesis state.
Note: The migrate command takes an input genesis state and migrates it to a targeted version. New
genesis-timeis usually mentioned in the governance proposal, and should be passed as flag argument. If the flag is omitted, then the genesis time of the upgraded chain will be the same as the old one, which may cause confusion.
All the necessary state changes are handled in the
simd migrate v0.42migration command. However, Tendermint parameters are not handled in this command. You might need to update these parameters manually.
In the recent versions of Tendermint, the following changes have been made:
consensus_params.evidence.max_numhas been renamed to
consensus_params.evidence.max_agehas been removed, and replaced by
Make sure that your genesis JSON files contains the correct values specific to your chain. If the
simd migrateerrors with a message saying that the genesis file cannot be parsed, these are the fields to check first.
Verify the SHA256 of the migrated genesis file with other validators to make sure there are no manual errors in the process.
Make sure to update the genesis parameters in the new genesis if any. All these details will be generally present in the governance proposal.
If your chain is using IBC, make sure to add IBC initial genesis state to the genesis file. You can use the following command to add IBC initial genesis state to the genesis file.
Note: This would add IBC state with IBC's
receive_enabled: false. Make sure to update them to
truein the above command if are planning to enable IBC transactions with chain upgrade. Otherwise you can do it via a governance proposal.
Reset the old state.
Note: Be sure you have a complete backed up state of your node before proceeding with this step. See Recovery for details on how to proceed.
Move the new genesis.json to your daemon config directory. Ex
~/.simd/config/app.tomlto include latest app configurations. Here is the link (opens new window) to the default template for v0.42's
app.toml. Make sure to update your custom configurations as per your validator design, e.g.
Compared to v0.39, some notable updates to
API server is now configured to run in-process with daemon, previously it was a separate process, invoked by running rest-server command i.e.,
gaiacli rest-server. Now it is in-process with daemon and can be enabled/disabled by API configuration:
swaggersetting refers to enabling/disabling swagger docs API, i.e,
State Sync Configuration
Kill if any external
rest-serverprocess is running.
All set now! You can (re)start your daemon to validate on the upgraded network. Make sure to check your binary version before starting the daemon:
Once your chain is upgraded, make sure to update your clients' REST endpoints.