Columbus 5 Upgrade Instructions

Instructions

The following document describes the necessary steps involved that full-node operators must take in order to upgrade from columbus-4 to columbus-5. The Terra team will post an official updated genesis file, but it is recommended that validators execute the instructions outlined in this document to independently verify the genesis file.

Hardware Recommendation

CPU: Compute Optimized 4x cores
Ram: 32GB
storage: 1.5TB

Export Height

The export height is 4,724,000 and the estimated halt time is

Wed Sep 29 2021 23:00:00 GMT-0800 (PDT)
Thu Sep 30 2021 07:00:00 GMT+0000 (UTC)
Thu Sep 30 2021 16:00:00 GMT+0900 (KST)

estimated using an average block time of 6.7s.

Preliminary

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

[email protected] is what full node operators will upgrade to and run in this next major upgrade.

Major Updates

Bump CosmosSDK to v0.44.0 (Stargate)
Bump CosmWasm to v0.16.0
Change seigniorage distribution logic as follows and set reward_weight to 1
1. reward_weight portion of the seigniorage to be burned
2. 1-reward_weight parameter to go to the community pool
Dividend swap fees to faithful oracles instead of burn
Support IBC v1.1.0

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-4 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.4.6 of the Terra application and restore to their latest snapshot before restarting their nodes.

Upgrade Procedure

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

If you are not a validator, please wait until the genesis link is uploaded on this repo and follow steps 4, 5, 8, and 9.

Verify you are currently running the correct version (v0.4.6 for 'full node' or v0.4.6-oracle for 'validators') of the Core:

$ terrad version --long
name: terra
server_name: terrad
client_name: terracli
version: 0.4.6
commit: c39ed2804dbb625c283d1cd11fac8d3bc79ff328
build_tags: netgo,ledger

name: terra
server_name: terrad
client_name: terracli
version: 0.4.6-oracle.0
commit: 5b8212870250c24fdd0ecc722ed4bd0bf0038688
build_tags: netgo,ledger

Export existing state from the columbus-4:

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-4. See Recovery for details on how to proceed.

Before exporting state via the following command, the terrad binary must be stopped!
```
$ terrad export --height=4724000 > columbus-4-genesis-export.json
```

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

$ jq -S -c -M "" columbus-4-genesis-export.json | shasum -a 256
87f8326c162eca8ba5a264eb02974a70d682d2092b9b7f8750b781417ca1f83f columbus-4-genesis-export.json

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

NOTE: Go 1.16+ is required!
```
$ git clone https://github.com/terra-money/core; cd core; git checkout v0.5.5-oracle; make install
```

Verify you are currently running the correct version (v0.5.5 for 'full node' or v0.5.5-oracle for 'validators' ) of the Core :

$ terrad version --long
name: terra
server_name: terrad
version: 0.5.9
commit: 6235f92a101d203fddd26abc6c64799c546f7716
build_tags: netgo,ledger

$ terrad version --long
name: terra
server_name: terrad
version: 0.5.9-oracle
commit: c46130400740fa9a83cfe3dc5acc591fbd47b332
build_tags: netgo,ledger
go: go version go1.16.5 darwin/amd64

Migrate exported state from columbus-4 to the new columbus-5 version:

$ terrad migrate ./columbus-4-genesis-export.json --chain-id=columbus-5 --initial-height=4724001 --genesis-time=2021-09-30T10:00:41Z > genesis.json

Genesis time should be computed relative to the blocktime of 4,724,000. The genesis time shall be the blocktime of 4,724,000 + 90 minutes with the subseconds truncated.

An example shell commands to compute this value are:

Mac

$ curl http://public-node.terra.dev:26657/block\?height\=4724000 | jq -r '.result["block"]["header"]["time"]'|xargs -0 date -v +90M  -j  -f "%Y-%m-%dT%H:%M:%S" +"%Y-%m-%dT%H:%M:%SZ"

Linux

$ date -d "$(curl http://public-node.terra.dev:26657/block\?height\=4724000 | jq -r '.result["block"]["header"]["time"]') +90 minutes" +"%Y-%m-%dT%H:%M:%SZ"

Verify the SHA256 of the final genesis JSON:

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

Init terra home:

Default terrad home path changed to ~/.terra from ~/.terrad. Also there are a lot of configuration changes, so we recommend reinitiating the terrad home and reconfigure the setting.

$ terrad init
# If you did not follow the steps above to create Genesis.json, you will need to download genesis.json from us
# $ wget https://columbus-genesis.s3.ap-northeast-1.amazonaws.com/columbus-5-genesis.json
$ mv ./genesis.json ~/.terra/config/

# copy old keys and addrbook.json for better genesis connection
$ cp ~/.terrad/config/node_key.json ~/.terrad/config/priv_validator_key.json ~/.terrad/config/addrbook.json ~/.terra/config/

Update the config files:

rest-server moved into terrad from terracli, so you need to activate this service from [api] section of ~/.terra/config/app.toml.

###############################################################################
###                           API Configuration                             ###
###############################################################################

[api]

# Enable defines if the API server should be enabled.
enable = true

# Swagger defines if swagger documentation should automatically be registered.
swagger = true

# Address defines the API server to listen on.
address = "tcp://0.0.0.0:1317"

all wasm.toml configs moved into [wasm] section of app.toml.

[wasm]
# The maximum gas amount can be spent for contract query.
# The contract query will invoke contract execution vm,
# so we need to restrict the max usage to prevent DoS attack
contract-query-gas-limit = "3000000"

# The flag to specify whether print contract logs or not
contract-debug-mode = "false"

# The WASM VM memory cache size in MiB not bytes
contract-memory-cache-size = "500"

tx indexing configs are also moved into app.toml

# IndexEvents defines the set of events in the form {eventType}.{attributeKey},
# which informs Tendermint what to index. If empty, all events will be indexed.
#
# Example:
# ["message.sender", "message.recipient"]
index-events = []

Please update min-gas-prices and pruning setting

# The minimum gas prices a validator is willing to accept for processing a
# transaction. A transaction's fees must meet the minimum of any denomination
# specified in this config (e.g. 0.25token1;0.0001token2).
minimum-gas-prices = "0.01133uluna,0.15uusd,0.104938usdr,169.77ukrw,428.571umnt,0.125ueur,0.98ucny,16.37ujpy,0.11ugbp,10.88uinr,0.19ucad,0.14uchf,0.19uaud,0.2usgd,4.62uthb,1.25usek,1.25unok,0.9udkk,2180.0uidr,7.6uphp,1.17uhkd"

# default: the last 100 states are kept in addition to every 500th state; pruning at 10 block intervals
# nothing: all historic states will be saved, nothing will be deleted (i.e. archiving node)
# everything: all saved states will be deleted, storing only the current state; pruning at 10 block intervals
# custom: allow pruning options to be manually specified through 'pruning-keep-recent', 'pruning-keep-every', and 'pruning-interval'
pruning = "default"

# These are applied if and only if the pruning strategy is custom.
pruning-keep-recent = "0"
pruning-keep-every = "0"
pruning-interval = "0"

Start terrad

$ terrad start

# Automated audits of the genesis state can take 30-120 min using the crisis module. This can be disabled by 
$ terrad start --x-crisis-skip-assert-invariants

Breaking Changes

For JavaScript developers: npm i -S @terra-money/terra.js@^2

CosmosSDK breaking changes: here
Wallet Migration Guide: here
Contract Migration Guide: here

Provide feedback

Saved searches

Use saved searches to filter your results more quickly