Skip to content

Columbus 3 Upgrade Instructions

Jump to bottom
yys edited this page Dec 13, 2019 · 15 revisions

Instructions

The following document describes the necessary steps involved that full-node operators must take in order to upgrade from columbus-2 to columbus-3. The Terra 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 Core application since the latest major upgrade (columbus-2). These changes notably consist of many new features, protocol changes, and application structural changes that favor developer ergonomics and application development.

Core application v0.3.1 is what full node operators will upgrade to and run in this next major upgrade.

Major Updates

  • Tax: The stability fees (tax) now can be paid using the specified fees flag. Therefore, the anteHandler would check whether the fees specified would be sufficient to cover both the gas fees and the stability fees. Moreover, the LUNA stability fees disappear and are only charged for TERRA.
  • Governance: The governance module is fully integrated to enable live param, tax-rate, and reward-weight update. It also uses community-pool-spend proposal for grant-program.
  • 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.
  • Codec:
    • auth/Account => core/Account
    • auth/StdTx => core/StdTx
    • pay/MsgSend => bank/MsgSend
    • pay/MsgMultiSend => bank/MsgMultiSend
    • oracle/MsgPricePrevote => oracle/MsgExchangeRatePrevote
    • oracle/MsgPriceVote => oracle/MsgExchangeRateVote
    • oracle/MsgDelegateFeederPermission => oracleMsgDelegateFeedConsent

For the details of changes, please refer Interface Changes document.

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 Terra developer before resetting your validator.

Recovery

Prior to exporting columbus-2 state, validators are encouraged to take a full data snapshot at the export height before proceeding. Snapshotting depends heavily on infrastructure, but generally this can be done by backing up the .terracli and .terrad directories.

In the event that the upgrade does not succeed, validators and operators must downgrade back to v0.2.7 of the Terra application and restore to their latest snapshot before restarting their nodes.

Upgrade Procedure

Note: It is assumed you are currently operation a full-node running v0.2.7 of the Terra application.

  1. Verify you are currently running the correct version (v0.2.7) of the Core:

    $ terrad version --long
core: 0.2.7
git commit: 881558ee16ca95f1adad2129d0cf535fc8dc41c9
go.sum hash: 43b21e3de280399a58478b1397bf52771f79bb74f2f7c8905097ab886705574f
build tags: netgo ledger netgo
go version go1.13.4 darwin/amd64

  2. Export existing state from columbus-2:

    NOTE: It is recommended for validators and operators to take a full data snapshot at the export height before proceeding in case the upgrade does not go as planned or if not enough voting power comes online in a sufficient and agreed upon amount of time. In such a case, the chain will fallback to continue operating columbus-2. See Recovery for details on how to proceed.

    Before exporting state via the following command, the terrad binary must be stopped!

    $ terrad export --for-zero-height --height=2530000 > columbus-2-genesis-export.json

  3. Verify the SHA256 of the (sorted) exported genesis file:

    $ jq -S -c -M "" columbus-2-genesis-export.json | shasum -a 256
7943d6d3cab0b3d2dcfe19f7b755faae921493ccaf2958e894f5a1c7d8f36113 columbus-2-genesis-export.json

  4. At this point you now have a valid exported genesis state! All further steps now require v0.3.1 of Core.

    NOTE: Go 1.13+ is required!

    $ git clone https://github.com/terra-project/core; cd core; git checkout v0.3.1; make install

  5. Verify you are currently running the correct version (v0.3.1) of the Core:

    $ terrad version --long
name: terra
server_name: terrad
client_name: terracli
version: 0.3.1
commit: 4fc37aa2220191317d67f6a9effc18239abd9269
build_tags: netgo,ledger
go: go version go1.13.4 darwin/amd64

  6. Migrate exported state from columbus-2 to the new columbus-3 version:

    Note: The script requires python-dateutil package, so before running this please install the package with $ pip3 install python-dateutil.

    $ python3 ./contrib/updates/columbus-2-to-columbus-3.py ./columbus-2-genesis-export.json --chain-id=columbus-3 --genesis-time=[PLACEHOLDER]  > genesis.json

    Genesis time should be computed relative to the blocktime of 2,530,000. The genesis time shall be the blocktime of 2,530,000 + 60 minutes with the subseconds truncated.

    An example shell command(tested on OS X Mojave) to compute this value is:

    curl https://rpc.terra.dev/block\?height\=2530000 | jq -r '.result["block_meta"]["header"]["time"]'|xargs -0 date -v +60M  -j  -f "%Y-%m-%dT%H:%M:%S" +"%Y-%m-%dT%H:%M:%SZ"

  7. Verify the SHA256 of the final genesis JSON:

    $ jq -S -c -M "" genesis.json | shasum -a 256
276011ba9cfb9b3d27420e47b9c6db6204579b5f79cb3a6103383e65da0b93eb genesis.json

  8. Reset 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.

    $ terrad unsafe-reset-all

  9. Move the new genesis.json to your .terrad/config/ directory

  10. Replace the db_backend on .terrad/config/config.toml to:

db_backend = “goleveldb”
  1. Note if you have any application configuration in terrad.toml, that file has now been renamed to app.toml
$ mv .terrad/config/terrad.toml .terrad/config/app.toml

Notes for Service Providers

  1. The transition from columbus-2 to columbus-3 contains an unusual amount of API breakage. After this upgrade will maintain the Core API stability guarantee to avoid breaking APIs for at least 6 months and hopefully long.
  2. Anyone running signing infrastructure(wallets and exchanges) should be conscious that the type: field on StdTx will have changed from "type":"auth/StdTx","value":... to "type":"core/StdTx","value":...
  3. As mentioned in the notes and Core CHANGELOG, many queries to terracli are wrapped with height fields now.
  4. We highly recommend standing up a testnet with the terra-0.3 release or joining the soju-0012 testnet. More info for joining the testnet can be found in the dircord validator room.
  5. We expect that developers with iOS or Android based apps may have to notify their users of downtime and ship an upgrade for columbus-3 compatibility unless they have some kind of switch they can throw for the new tx formats. Server side applications should experience briefer service interruptions and be able to just spin up new nodes and migrate to the new apis
Clone this wiki locally