Columbus 4 Upgrade Instructions

Instructions

The following document describes the necessary steps involved that full-node operators must take in order to upgrade from columbus-3 to columbus-4. 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.

Hardware Recommendation

CPU: Compute Optimized 4x cores
Ram: 16GB
Storage: 1TB

Export Height

The export height is 3,820,000 and estimated halt time is

Sun Oct 04 2020 01:00:00 GMT+0900 (KST)
Sat Oct 03 2020 16:00:00 GMT+0000 (UTC)
Sat Oct 03 2020 09:00:00 GMT-0700 (PST)

when average block time is 6.65s.

Preliminary

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

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

Major Updates

WASM: The WASM module allows users to extend the capabilities of the Terra blockchain by introducing custom logic that can be composed against the Terra blockchain's financial primitives such as its stablecoin available in any world currency, robust oracle price feed, and on-chain atomic swap. These decentralized applications unlock new avenues of value-transfer through enabling unique transaction flows not provided by Terra's native modules.
MsgAuth: The msg_authorization module provides support for granting arbitrary capabilities from one account (the granter) to another account (the grantee). Capabilities must be granted for a particular type of sdk.Msg one by one using an implementation of Capability. Now only gov/MsgVote, bank/MsgSend, and market/MsgSwap message types are allowed to be grant to other account.
Pruning: The operator can set the pruning options via a pruning config via the CLI or through app.toml. The pruning flag exposes default|everything|nothing|custom as options -- see here for further details. If the operator chooses custom, they may provide granular pruning options pruning-keep-recent, pruning-keep-every, and pruning-interval. The former two options dictate how many recent versions are kept on disk and the offset of what versions are kept after that respectively, and the latter defines the height interval in which versions are deleted in a batch. Note, there are some client-facing API breaking changes with regard to IAVL, stores, and pruning settings.
Oracle Aggregated Prevote/Vote: The oracle module has been improved to reduce voting cost. Each aggregated oracle vote contains multiple swap rates as a single string splitted by a comma instead of multiple DecCoin to reduce unnecessary object keys. Each aggregated oracle prevote contains a single hex string representing hash value of aggregated oracle vote.

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-3 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.3.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.3.7 of the Terra application.

If you are not a validator, please wait util the genesis is uploaded on this repo and follow the steps from 8

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

$ terrad version --long
name: terra
server_name: terrad
client_name: terracli
version: 0.3.7
commit: d191517814000b46897fdf8700269c4caba766ce
build_tags: netgo,ledger
go: go version go1.14.7 darwin/amd64

Export existing state from columbus-3:

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-3. 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=3820000 > columbus-3-genesis-export.json
```

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

$ jq -S -c -M "" columbus-3-genesis-export.json | shasum -a 256
9b5e3b56ab80d8616d088e38fd9ee650f2e01abdc1ea2615f906df724184906d columbus-3-genesis-export.json

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

NOTE: Go 1.14+ is required!
```
$ git clone https://github.com/terra-project/core; cd core; git checkout v0.4.0; make install
```

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

$ terrad version --long
name: terra
server_name: terrad
client_name: terracli
version: 0.4.0
commit: 0ccb97e4427007f940b611fb0b5fb67d6a7d69f5
build_tags: netgo,ledger
go: go version go1.14.7 darwin/amd64

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

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

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

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

curl http://public-node.terra.dev:26657/block\?height\=3820000 | 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"

Verify the SHA256 of the final genesis JSON:

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

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. For validators, you need to keep in mind to restore priv_validator_key.json and node_key.json after reset.
```
$ terrad unsafe-reset-all
```
Move the new genesis.json to your .terrad/config/ directory
Update the .terrad/config/*.toml:

Update config.toml

[SKIPPABLE] DB Backend (rocksdb is added)

# Database backend: goleveldb | cleveldb | boltdb | rocksdb
# * goleveldb (github.com/syndtr/goleveldb - most popular implementation)
#   - pure go
#   - stable
# * cleveldb (uses levigo wrapper)
#   - fast
#   - requires gcc
#   - use cleveldb build tag (go build -tags cleveldb)
# * boltdb (uses etcd's fork of bolt - github.com/etcd-io/bbolt)
#   - EXPERIMENTAL
#   - may be faster is some use-cases (random reads - indexer)
#   - use boltdb build tag (go build -tags boltdb)
# * rocksdb (uses github.com/tecbot/gorocksdb)
#   - EXPERIMENTAL
#   - requires gcc
#   - use rocksdb build tag (go build -tags rocksdb)
db_backend = "goleveldb"

[MUST] New Configs in p2p section. Add these two configs are under [p2p] section

##### peer to peer configuration options #####
[p2p]

# List of node IDs, to which a connection will be (re)established ignoring any existing limits
unconditional_peer_ids = ""

# Maximum pause when redialing a persistent peer (if zero, exponential backoff is used)
persistent_peers_max_dial_period = "0s"

[SKIPPABLE] Fastsync Version (v2 is added)

##### fast sync configuration options #####
[fastsync]

# Fast Sync version to use:
#   1) "v0" (default) - the legacy fast sync implementation
#   2) "v1" - refactor of v0 version for better testability
#   3) "v2" - refactor of v1 version for better usability
version = "v0"

[MUST] Tx Index (tags => keys)

##### transactions indexer configuration options #####
[tx_index]

# What indexer to use for transactions
#
# Options:
#   1) "null"
#   2) "kv" (default) - the simplest possible indexer, backed by key-value storage (defaults to levelDB; see DBBackend).
indexer = "kv"

# Comma-separated list of compositeKeys to index (by default the only key is "tx.hash")
# Remember that Event has the following structure: type.key
# type: [
#  key: value,
#  ...
# ]
#
# You can also index transactions by height by adding "tx.height" key here.
#
# It's recommended to index only a subset of keys due to possible memory
# bloat. This is, of course, depends on the indexer's DB and the volume of
# transactions.
index_keys = ""

# When set to true, tells indexer to index all compositeKeys (predefined keys:
# "tx.hash", "tx.height" and all keys from DeliverTx responses).
#
# Note this may be not desirable (see the comment above). IndexKeys has a
# precedence over IndexAllKeys (i.e. when given both, IndexKeys will be
# indexed).
index_all_keys = true

Replace app.toml

# This is a TOML config file.
# For more information, see https://github.com/toml-lang/toml

##### main base config options #####

# 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"

# 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"

# HaltHeight contains a non-zero block height at which a node will gracefully
# halt and shutdown that can be used to assist upgrades and testing.
#
# Note: Commitment of state will be attempted on the corresponding block.
halt-height = 0

# HaltTime contains a non-zero minimum block time (in Unix seconds) at which
# a node will gracefully halt and shutdown that can be used to assist upgrades
# and testing.
#
# Note: Commitment of state will be attempted on the corresponding block.
halt-time = 0

# InterBlockCache enables inter-block caching.
inter-block-cache = true

Create wasm.toml

# This is a TOML config file.
# For more information, see https://github.com/toml-lang/toml

##### main base config options #####

# 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"

# Storing instances in the LRU will have no effect on the results
# (still deterministic), but should lower execution time at
# the cost of increased memory usage. We cannot pick universal
# parameters for this, so we should allow node operators to set it.
lru-size = "0"

Notes for Service Providers

The block_meta field in /blocks/{block_height} has been removed, because almost all data can be found in block_header
The whitelist of /oracle/parameters response has been changed from []string to []{ name: string; tobin_tax: string; }.
The events of /txs/{txhash} has been removed, because it was redundant data with logs.events.
The CosmosSDK is now using keyring based keystore, so a terracli user need to migrate keys to keying please refer changelog
We expect that developers with iOS or Android based apps may have to notify their users of downtime and ship an upgrade for columbus-4 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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly