Skip to content

Cosmos Hub 2 Upgrade

Jump to bottom
Alexander Bezobchuk edited this page Aug 25, 2019 · 20 revisions

Instructions

The following document describes the necessary steps involved that full-node operators must take in order to upgrade from cosmoshub-2 to cosmoshub-3. The Tendermint team will post an official updated genesis file, but it is recommended that validators execute the following instructions in order to verify the resulting genesis file.

Preliminary

Many changes have occurred to the Cosmos SDK and the Gaia application since the latest major upgrade (cosmoshub-2). These changes notably consist of many new features, protocol changes, and application structural changes that favor developer ergonomics and application development.

First and foremost, the Cosmos SDK and the Gaia application have been split into separate repositories. This allows for both the Cosmos SDK and Gaia to evolve naturally and independently. Thus, any future releases of Gaia going forward, including this one, will be built and tagged from this repository not the Cosmos SDK.

Since the Cosmos SDK and Gaia have now been split into separate repositories, their versioning will also naturally diverge. In an attempt to decrease community confusion and strive for semantic versioning, the Cosmos SDK will continue on its current versioning path (i.e. v0.36.x ) and the Gaia application will become v2.0.0.

Gaia application v2.0.0 is what full node operators will upgrade to and run in this next major upgrade.

Major Updates

There are many notable features and changes in the upcoming release of the SDK. Many of these are discussed at a high level in July's Cosmos development update found here.

Some of the biggest changes to take note on when upgrading as a developer or client are the the following:

  • Tagging/Events: The entire system of what we used to call tags has been replaced by a more robust and flexible system called events. Any client that depended on querying or subscribing to tags should take note on the new format as old queries will not work and must be updated. More in depth docs on the events system can be found here. In addition, each module documents its own events in the specs (e.g. slashing).
  • Height Queries: Both the CLI and REST clients now (re-)enable height queries via the --height and ?height arguments respectively. An important note to keep in mind are that height queries against pruning nodes will return errors when a pruned height is queried against. When no height is provided, the latest height will be used by default keeping current behavior intact. In addition, many REST responses now wrap the query results in a new structure {"height": ..., "result": ...}. That is, the height is now returned to the client for which the resource was queried at.

Risks

As a validator performing the upgrade procedure on your consensus nodes carries a heightened risk of double-signing and being slashed. The most important piece of this procedure is verifying your software version and genesis file hash before starting your validator and signing.

The riskiest thing a validator can do is 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 a Tendermint developer before resetting your validator.

Upgrade Procedure

Note: It is assumed you are currently operating a full-node running v0.34.6+ of the Cosmos SDK.

  • The version/commit hash of Gaia v2.0.0: 3c70fee433956ba32e35705193a5f7a7d5b63277
  • The upgrade height as agreed upon by governance: TBD
  1. Verify you are currently running the correct version (v0.34.6+) of the Cosmos SDK:
$ gaiad version --long
cosmos-sdk: 0.34.6
git commit: 80234baf91a15dd9a7df8dca38677b66b8d148c1
vendor hash: f60176672270c09455c01e9d880079ba36130df4f5cd89df58b6701f50b13aad
build tags: netgo ledger
go version go1.12.2 linux/amd64
  1. Export existing state from cosmoshub-2 
$ gaiad export --for-zero-height --height=TBD > cosmoshub_2_genesis_export.json
  1. Verify the SHA256 of the (sorted) exported genesis file:
$ jq -S -c -M '' cosmoshub_2_genesis_export.json | shasum -a 256
TBD  cosmoshub_2_genesis_export.json
  1. At this point you now have a valid exported genesis state! All further steps now require v2.0.0 of Gaia.
git checkout v2.0.0; make install
  1. Verify you are currently running the correct version (v2.0.0) of the Gaia:
$ gaiad version --long
name: gaia
server_name: gaiad
client_name: gaiacli
version: 2.0.0
commit: 3c70fee433956ba32e35705193a5f7a7d5b63277
build_tags: netgo,ledger
go: go version go1.12.8 darwin/amd64
  1. Migrate exported state from the current v0.34.6+ version to the new v2.0.0 version:
$ gaiad migrate v0.36 cosmoshub_2_genesis_export.json > genesis.json
  1. Now we must update all parameters that have been agreed upon through governance. There is only a single parameter, max_validators, that we're upgrading based on proposal 10 
$ cat genesis.json | jq '.app_state["staking"]["params"]["max_validators"]=125' > tmp_genesis.json && mv tmp_genesis.json genesis.json
  1. Verify the SHA256 of the final genesis JSON:
$ jq -S -c -M '' genesis.json | shasum -a 256
TODO  genesis.json
  1. Reset state
$ gaiad unsafe-reset-all

  1. Move the new genesis.json to your .gaiad/config/ directory

  2. Replace the db_backend on .gaiad/config/config.toml to:

db_backend = "goleveldb"
  1. Note, if you have any application configuration in gaiad.toml, that file has now been renamed to app.toml:
$ mv .gaiad/config/gaiad.toml .gaiad/config/app.toml
Clone this wiki locally