Wenchang to GuanYu mainnet Upgrade Instructions

This document describes the procedure to upgrade from a Wenchang-mainnet node to a Guanyu-mainnet node. We will perform these steps together at block 4172935 on October 14, 2020 at or around 14:00 UTC.

Upgrade Procedure

Note: It is assumed you are currently operating a node running v0.2.4+

The upgrade height for mainnet is 4172935

You may obtain the canonical UTC timestamp of the exported block by any of the following methods:

• Block explorer (e.g. https://cosmoscan.io/block/4172935)
• Through manually querying an RPC node (e.g. /block?height=4172935)
• Through manually querying a Band REST client (e.g. /blocks/4172935)

1. Stop current node by running the command below

sudo systemctl stop bandd

2. Download binary release of Wenchang version v0.2.5 (We fix bug when export for more detail you can look at the release description.

wget https://github.com/bandprotocol/bandchain/releases/download/v0.2.5/bandd_linux_amd64
chmod +x bandd_linux_amd64
sudo mv bandd_linux_amd64 /usr/local/bin/bandd

wget https://github.com/bandprotocol/bandchain/releases/download/v0.2.5/bandcli_linux_amd64
chmod +x bandcli_linux_amd64
sudo mv bandcli_linux_amd64 /usr/local/bin/bandcli

Check bandd and bandcli version

$ bandd version --long

name: bandchain
server_name: bandd
client_name: bandcli
version: 0.2.5
commit: 99ee7800f6c534c7aa4d37180817d2c6ca96ba56
build_tags: ledger
go: go version go1.14.7 linux/amd64

3. Backup current folders and export the existing state from band-wenchang-mainnet

NOTE: It is recommended for validator and sentry nodes to backup data snapshot at the export height before proceeding. Please look at Recovery section for more detail.

# Remove old backup (in case have old backup)
rm -r $HOME/.bandd.bak
rm -r $HOME/.bandcli.bak

# Check $HOME/.bandd file space usage
du -h --max-depth=0 $HOME/.bandd # the result would be ~90G

# Make sure you have enough disk space for backup $HOME/.bandd
df -h 

# Copy `.bandd` and `.bandcli` (Estimated time ~11 mins)
cp -r $HOME/.bandd $HOME/.bandd.bak
cp -r $HOME/.bandcli $HOME/.bandcli.bak 

# Export genesis file
/usr/local/bin/bandd export --for-zero-height --height=4172935 > wenchang_mainnet_genesis_export.json

4. Verify the SHA256 has of the sorted genesis file (We will announce the expected hash on discord channel)

$ sudo apt-get update
$ sudo apt-get install jq
jq -S -c -M '' wenchang_mainnet_genesis_export.json | shasum -a 256
5e947be3c4717446a35337a823e7944c2e211d0936d4af0ba405d360c1fbc0ab  -

Note Please check this hash before doing the next step.

5. Rename the old bandd and bandcli directories to another name

sudo mv /usr/local/bin/bandd /usr/local/bin/wenchang_bandd
sudo mv /usr/local/bin/bandcli /usr/local/bin/wenchang_bandcli

6. After this step, we require bandd v1.2.6. This can be built by calling the following commands.

sudo apt-get update
sudo apt-get install -y build-essential

# Install go
wget https://golang.org/dl/go1.14.9.linux-amd64.tar.gz
sudo tar -C /usr/local -xzf go1.14.9.linux-amd64.tar.gz

echo "export PATH=\$PATH:/usr/local/go/bin:~/go/bin" >> $HOME/.profile
source ~/.profile
    
# Clone code and build bandd, bandcli, and yoda
git clone https://github.com/bandprotocol/bandchain
cd bandchain/chain
git checkout v1.2.6 
make install

7. Migrate the exported genesis state

cd $HOME
bandd migrate wenchang_mainnet_genesis_export.json --chain-id=band-guanyu-mainnet --genesis-time=2020-10-14T15:02:58.885270063Z > genesis.json

$ jq -S -c -M '' genesis.json | shasum -a 256
9673376e8416d1e7fc87d271b8a9e5e3d3ce78a076b0d907d87c782bb0320e30  -

Note Please check this hash before doing the next step.

8. Copy GuanYu genesis file and delete the old state

mv genesis.json ~/.bandd/config/genesis.json
bandd unsafe-reset-all

9. Upgrade config.toml in tx_index field

sed -i -e \
  's/index_tags/index_keys/g' \
  $HOME/.bandd/config/config.toml

sed -i -e \
  's/index_all_tags/index_all_keys/g' \
  $HOME/.bandd/config/config.toml

10. Update persistence peers of your node to BandChain peers.

• If you run with a single validator, you can replace the old peers with new peers by this command

sed -E -i \
  's/persistent_peers = \".*\"/persistent_peers = \"[email protected]:26656,[email protected]:26656,[email protected]:26656,[email protected]:26656,[email protected]:26656\"/' \
  $HOME/.bandd/config/config.toml

• Otherwise, you use the validator-sentry model to run your system. Please remove the old peers and add the new peers at $HOME/.band/config/config.toml

Remove these old peers: 
[email protected]:26656,[email protected]:26656
And add new peers:
[email protected]:26656,[email protected]:26656,[email protected]:26656,[email protected]:26656,[email protected]:26656

11. Modify /etc/systemd/system/bandd.service file with new content (Replace location of bandd)

[Unit]
Description=BandChain Node Daemon
After=network-online.target

[Service]
User=ubuntu
ExecStart=/home/ubuntu/go/bin/bandd start
Restart=always
RestartSec=3
LimitNOFILE=4096

[Install]
WantedBy=multi-user.target

12. Start Gaunyu mainnet

sudo systemctl daemon-reload
sudo systemctl start bandd

You can tail the log output with journalctl -u bandd.service -f. If all goes well, you should see that the node daemon has started syncing after pass agreed block time.

... bandd: I[..] starting ABCI with Tendermint                module=main 
... bandd: I[..] Executed block                               module=state height=1 validTxs=0 invalidTxs=0
... bandd: I[..] Committed state                              module=state height=1 txs=0 appHash=...
...

Noted: Before proceeding the next instruction, please make sure the upgrade process has been successful. This command cannot revert, you can recover by the backup file only.

13. Migrate the Wenchang keys (e.g. validator key) from the previous key store to the new key store for sending transactions on the new node. (Skip this step if you are upgrading sentry nodes)

bandcli keys migrate

Answer No on key that you want to migrate.

Recovery

Before exporting our band-wenchang-mainnet state, we recommend that validators take a full data snapshot at the export height before proceeding. In most cases, this can be done by backing up the .bandcli and .bandd directories.

You'll also need to back-up the ~/.bandd/data/priv_validator_state.json file after stopping your node process. This file is updated every block as your validator participates in a consensus round. It is a critical file needed to prevent double-signing, in case the upgrade fails, and the previous chain needs to be restarted.

In case the upgrade doesn't go as planned or not enough validators come online in a sufficient and agreed upon amount of time, validators and operators must downgrade back to v0.2.4 and restore to their latest snapshot before restarting their nodes.

In case we need to reset to wenchang mainnet, please follow these steps.

1. Stop current node by running the command below

sudo systemctl stop bandd

2. Remove bandd and bandcli Guanyu version

rm -r ~/go/bin

3. Rename bandd and bandcli back to Wenchang version

sudo mv /usr/local/bin/wenchang_bandd /usr/local/bin/bandd 
sudo mv /usr/local/bin/wenchang_bandcli /usr/local/bin/bandcli 

4. Recover .bandd and .bandcli directories by backup folders

# Remove failed folder
rm -r ~/.bandd
rm -r ~/.bandcli

# Recover backup
cp -r ~/.bandd.bak ~/.bandd
cp -r ~/.bandcli.bak ~/.bandcli

5. Copy old service file to /etc/systemd/system/bandd.service

[Unit]
Description=BandChain Node Daemon
After=network-online.target

[Service]
User=ubuntu
ExecStart=/usr/local/bin/bandd start --p2p.persistent_peers "[email protected]:26656,[email protected]:26656"
Restart=always
RestartSec=3
LimitNOFILE=4096

[Install]
WantedBy=multi-user.target

6. Restart bandd service

sudo systemctl daemon-reload
sudo systemctl start bandd

Tail the log output with journalctl -u bandd.service -f. If all goes well, you should see that the node daemon has started syncing on wenchang-mainnet chain again.

... bandd: I[..] starting ABCI with Tendermint                module=main 
... bandd: I[..] Executed block                               module=state height=xx validTxs=0 invalidTxs=0
... bandd: I[..] Committed state                              module=state height=xx txs=0 appHash=...
...