diff --git a/migrate/v0_15/migrate.md b/migrate/v0_15/migrate.md new file mode 100644 index 00000000..1269b700 --- /dev/null +++ b/migrate/v0_15/migrate.md @@ -0,0 +1,85 @@ +# kava-8 Upgrade Instructions + +## Software Version and Key Dates + +- We will be upgrading from chain-id "kava-7" to chain-id "kava-8". +- The version of Kava for kava-8 is [TODO: version] +- The kava-7 chain will be shutdown with a `SoftwareUpgradeProposal` that activates at approximately 13:00 UTC on August, 30 2021. +- kava-8 genesis time is set to August 30th, 2021 at 15:00 UTC +- The version of cosmos-sdk for kava-8 is v0.39.3 +- The version of tendermint for kava-8 v0.33.9 +- The minimum version of golang for kava-8 is 1.13+, 1.15+ has been tested and is recommended. + +### 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 Kava developer before resetting your validator. + +### Recovery + +Prior to exporting kava-7 state, validators are encouraged to take a full data snapshot at the export height before proceeding. Snap-shotting depends heavily on infrastructure, but generally this can be done by backing up the .kvd and .kvcli directories. + +It is critically important to back-up the .kvd/data/priv_validator_state.json file after stopping your kvd process. This file is updated every block as your validator participates in consensus rounds. It is a critical file needed to prevent double-signing, in case the upgrade fails and the previous chain needs to be restarted. + +In the event that the upgrade does not succeed, validators and operators must downgrade back to v0.14.2 of the Kava software and restore to their latest snapshot before restarting their nodes. + +## Upgrade Procedure + +### Before the upgrade + +Kava Labs will submit a `SoftwareUpgradeProposal` that specifies the exact block _height_ at which the chain should shut down. This height will correspond to approximately 13:00 UTG on August 30th. Once the proposal passes, the chain will shutdown automatically at the specified height and does not require manual intervention by validators. + +### On the day of the upgrade + +**The kava chain is expected to halt at 13:00 UTC, and restart with new software at 15:00 UTC August 30th. Do not stop your node and begin the upgrade before 13:00UTC on August 30th, or you may go offline and be unable to recover until after the upgrade!** + +Kava developers will update this PR with the final block number when it is reached. **Make sure the kvd process is stopped before proceeding and that you have backed up your validator**. Failure to backup your validator could make it impossible to restart your node if the upgrade fails. + +1. Export State (this **MUST** be done using **v0.14.3**, previous v0.14.x versions will not produce the same genesis hash!) + +```sh +kvd export --for-zero-height --height PLACEHOLDER > export-genesis.json +``` + +**Note:** This can take a while! + +2. Update to kava-8 + +```sh + # in the `kava` folder + git pull + git checkout [TODO: version] + make install + + # verify versions + kvd version --long + # name: kava + # server_name: kvd + # client_name: kvcli + # version: [TODO: version] + # commit: PLACEHOLDER + # build_tags: netgo,ledger + # go: go version go1.15.8 linux/amd64 + + + # Migrate genesis state + kvd migrate export-genesis.json > genesis.json + + # Verify output of genesis migration + kvd validate-genesis genesis.json # should say it's valid + jq -S -c -M '' genesis.json | shasum -a 256 + # PLACEHOLDER + + # Restart node with migrated genesis state + cp genesis.json ~/.kvd/config/genesis.json + kvd unsafe-reset-all + + # Restart node - + # ! Be sure to remove --halt-time flag if it is set in systemd/docker + kvd start +``` + +### Coordination + +If the kava-8 chain does not launch by August 30, 2021 at 19:00 UTC, the launch should be considered a failure and validators should refer to the [rollback](./rollback.md) instructions to restart the previous kava-7 chain. In the event of launch failure, coordination will occur in the [Kava discord](https://discord.com/invite/kQzh3Uv). diff --git a/migrate/v0_15/rollback.md b/migrate/v0_15/rollback.md new file mode 100644 index 00000000..4e49b51a --- /dev/null +++ b/migrate/v0_15/rollback.md @@ -0,0 +1,40 @@ +# Kava-8 Rollback Instructions + +In the event that the kava-8 relaunch is unsuccessful, we will restart the kava-7 chain using the last known state. + +In order to restore the previous chain, the following data must be recovered by validators: + +- The database that contains the state of the previous chain (in ~/.kvd/data by default) +- The priv_validator_state.json file of the validator (in ~/.kvd/data by default) + +If you don't have the database data, the Kava developer team or another validator will share a copy of the database via Amazon s3 or a similar service. You will be able to download a copy of the data and verify it before starting your node. +If you don't have the backup priv_validator_state.json file, you will not have double sign protection on the first block. If this is the case, it's best to consult in the validator discord before starting your node. + +## Restoring state procedure + +1. Copy the contents of your backup data directory back to the $KVD_HOME/data directory. By default this is ~/.kvd/data. + +``` +# Assumes backup is stored in "backup" directory +rm -rf ~/.kvd/data +mv backup/.kvd/data ~/.kvd/data +``` + +2. Install the previous version of kava + +``` +# from kava directory +git checkout v0.14.2 +make install + +## verify version +kvd version --long +``` + +3. Restart kvd process + +``` +### be sure to remove --halt-time flag if it is set +sudo systemctl daemon-reload +sudo systemctl restart kvd +```