Wenchang testnet 3 Upgrade Instructions

This document describes the procedure to upgrade from a Wenchang-testnet3 node to a Guanyu-testnet3 node. We will perform these steps together on September 17, 2020 at 14:00 UTC.

Upgrade Procedure

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

The upgrade height for this testnet is 305335

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-testnet3

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

# Copy `.bandd` and `.bandcli` 
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=305335 > wenchang_testnet3_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_testnet3_genesis_export.json | shasum -a 256
4ce9e67ba7567cd279eba83e04520920af75f5175749978de448a666c8339052  -

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_testnet3_genesis_export.json --chain-id=band-guanyu-testnet3 --genesis-time=2020-09-17T15:00:00Z > genesis.json

$ jq -S -c -M '' genesis.json | shasum -a 256
716c82135b7f7b77f06bf4be440b43371113326e5fdc1c1ba91357d76bea8459  -

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. 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 --p2p.persistent_peers "ceb2fe644d03a33b3c1ba4a384384433e7bb5b6b@guanyu-testnet3-alice.node.bandchain.org:26656,dd8397061f31a0b99c5742049e2ffc8e3956f9c7@guanyu-testnet3-bob.node.bandchain.org:26656"
Restart=always
RestartSec=3
LimitNOFILE=4096

[Install]
WantedBy=multi-user.target

11. Start Gaunyu testnet

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 (2020-09-17T15:00:00Z).

... 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=...
...

12. If chain starts running, you need to migrate the Wenchang keys (e.g. validator key) from previous key store to new key store to send transaction on new node.

bandcli keys migrate

Answer No on key that you want to migrate.

Recovery

Before exporting our band-wenchang-testnet3 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 testnet, 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 "ceb2fe644d03a33b3c1ba4a384384433e7bb5b6b@wenchang-testnet3-alice.node.bandchain.org:26656,dd8397061f31a0b99c5742049e2ffc8e3956f9c7@wenchang-testnet3-bob.node.bandchain.org: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-testnet3 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=...
...