mirror of
https://github.com/0glabs/0g-chain.git
synced 2024-12-26 08:15:19 +00:00
update docs for kava-9 and v0.16.1 (#1165)
This commit is contained in:
Adam Robert Turman
GitHub
parent
79ef1a52a4
commit
205825658f
95
docs/kava-9/validator_guide.md
Normal file
95
docs/kava-9/validator_guide.md
Normal file
@ -0,0 +1,95 @@
|
|||||||
|
# Kava-9 Validator Guide
|
||||||
|
|
||||||
|
## Software Version and Key Dates
|
||||||
|
|
||||||
|
- We will be upgrading from chain-id "kava-8" to chain-id "kava-9".
|
||||||
|
- The version of Kava for kava-9 is v0.16.1
|
||||||
|
- The kava-8 chain will be shutdown with a `SoftwareUpgradeProposal` that activates at block height __1803250__, which is approximately 14:00 UTC on January, 19 2022.
|
||||||
|
- kava-9 genesis time is set to January 19, 2022 at 16:00 UTC
|
||||||
|
- The version of cosmos-sdk for kava-9 is v0.44.5
|
||||||
|
- The version of tendermint for kava-9 v0.34.14
|
||||||
|
- The minimum version of golang for kava-9 is __1.17+__.
|
||||||
|
|
||||||
|
__NOTE__: As part of the upgrade to kava-9, the `kvd` and `kvcli` binaries were combined into a single blockchain binary named `kava`. When restarting the chain, be sure to use `kava start` and not the deprecated `kvd start`.
|
||||||
|
|
||||||
|
### 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-8 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.15.2 of the Kava software and restore to their latest snapshot before restarting their nodes.
|
||||||
|
|
||||||
|
## Upgrade Procedure
|
||||||
|
|
||||||
|
### Before the upgrade
|
||||||
|
|
||||||
|
Kava Labs has submitted a `SoftwareUpgradeProposal` that specifies block height __1803250__ as the final block height for kava-8. This height corresponds to approximately 14:00 UTC on January 19th. 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 block height __1803250__, at approximately 14:00 UTC, and restart with new software at 16:00 UTC January 19th. Do not stop your node and begin the upgrade before 14:00UTC on January 19th, or you may go offline and be unable to recover until after the upgrade!**
|
||||||
|
|
||||||
|
**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.15.x**)
|
||||||
|
|
||||||
|
```sh
|
||||||
|
# verify version before export:
|
||||||
|
kvd version --long
|
||||||
|
# name: kava
|
||||||
|
# server_name: kvd
|
||||||
|
# client_name: kvcli
|
||||||
|
# version: 0.15.0 (any 0.15 version is fine)
|
||||||
|
# commit: 8691ac44ed0e65db7ebc4a2fe85c58c717f63c39
|
||||||
|
# build_tags: netgo,ledger
|
||||||
|
# go: go version go1.17.1 linux/amd64
|
||||||
|
|
||||||
|
# export genesis using v0.15.x
|
||||||
|
kvd export --for-zero-height --height 1803249 > export-genesis.json
|
||||||
|
```
|
||||||
|
|
||||||
|
**Note:** This can take a while!
|
||||||
|
|
||||||
|
2. Update to kava-9
|
||||||
|
|
||||||
|
```sh
|
||||||
|
# in the `kava` folder
|
||||||
|
git pull
|
||||||
|
git checkout v0.16.1
|
||||||
|
make install
|
||||||
|
|
||||||
|
# verify versions
|
||||||
|
kava version --long
|
||||||
|
# name: kava
|
||||||
|
# server_name: kava
|
||||||
|
# version: v0.16.1
|
||||||
|
# commit: [PLACEHOLDER]
|
||||||
|
# build_tags: netgo,ledger
|
||||||
|
# go: go version go1.17.1 linux/amd64
|
||||||
|
|
||||||
|
|
||||||
|
# Migrate genesis state
|
||||||
|
kava migrate export-genesis.json > genesis.json
|
||||||
|
|
||||||
|
# Verify output of genesis migration
|
||||||
|
kava validate-genesis genesis.json # should say it's valid
|
||||||
|
kava assert-invariants genesis.json # should say invariants pass
|
||||||
|
jq -S -c -M '' genesis.json | shasum -a 256
|
||||||
|
# [PLACEHOLDER]
|
||||||
|
|
||||||
|
# Restart node with migrated genesis state
|
||||||
|
cp genesis.json ~/.kava/config/genesis.json
|
||||||
|
kava unsafe-reset-all
|
||||||
|
|
||||||
|
# Restart node -
|
||||||
|
# ! Be sure to remove --halt-time flag if it is set in systemd/docker
|
||||||
|
# NOTE: THE BINARY IS NOW NAMED KAVA
|
||||||
|
kava start
|
||||||
|
```
|
||||||
90
docs/kava-9/wallet_explorer_exchange_guide.md
Normal file
90
docs/kava-9/wallet_explorer_exchange_guide.md
Normal file
@ -0,0 +1,90 @@
|
|||||||
|
# Kava-9 Upgrade Guide for Wallets, Explorers, and Exchanges
|
||||||
|
|
||||||
|
The Kava-9 Upgrade migrates the Kava blockchain from v0.39.x of the cosmos-sdk to v0.44.x of the cosmos-sdk. A full description of the v0.39 -> v0.40-42 REST changes can be found at:
|
||||||
|
|
||||||
|
https://github.com/cosmos/cosmos-sdk/blob/v0.42.11/docs/migrations/rest.md
|
||||||
|
|
||||||
|
**Note**: Kava engineers have implemented a custom POST /txs endpoint to preserve backwards compatibility (v0.42 -> v0.44 REST changes) for legacy encoded transaction:
|
||||||
|
|
||||||
|
https://docs.cosmos.network/master/migrations/rest.html
|
||||||
|
|
||||||
|
**Note**: Cosmos, Terra, and Osmosis blockchains have also been upgraded to v0.44 of the cosmos-sdk. Changes needed to support those chains will apply to Kava as well.
|
||||||
|
|
||||||
|
For wallets, explorers, and exchanges, there are a few particular changes to be aware of:
|
||||||
|
|
||||||
|
### Account data
|
||||||
|
Account data has been separated from balances data. In v0.15 of kava (kava-8), querying an account would return the following JSON, which contains both the account data and balance data:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
curl /auth/accounts/kava173w2zz287s36ewnnkf4mjansnthnnsz7rtrxqc`
|
||||||
|
```
|
||||||
|
```json
|
||||||
|
{"height":"38","result":{"type":"cosmos-sdk/Account","value":{"address":"kava173w2zz287s36ewnnkf4mjansnthnnsz7rtrxqc","coins":[{"denom":"ukava","amount":"1000000000000"}],"public_key":null,"account_number":"16","sequence":"0"}}}`
|
||||||
|
```
|
||||||
|
|
||||||
|
In v0.16 (kava-9):
|
||||||
|
|
||||||
|
|
||||||
|
```sh
|
||||||
|
curl /auth/accounts/kava173w2zz287s36ewnnkf4mjansnthnnsz7rtrxqc`
|
||||||
|
```
|
||||||
|
```json
|
||||||
|
{"height":"6","result":{"type":"cosmos-sdk/BaseAccount","value":{"address":"kava173w2zz287s36ewnnkf4mjansnthnnsz7rtrxqc","account_number":"15"}}}`
|
||||||
|
```
|
||||||
|
|
||||||
|
|
||||||
|
Note: The `sequence` field is now omitted from the response if an account has not signed a transaction.
|
||||||
|
|
||||||
|
To get the balance data, the /bank/balances endpoint must be used in addition to /auth/accounts:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
curl /bank/balances/kava173w2zz287s36ewnnkf4mjansnthnnsz7rtrxqc`
|
||||||
|
```
|
||||||
|
```json
|
||||||
|
{"height":"198","result":[{"denom":"ukava","amount":"10000000000000000"}]}`
|
||||||
|
```
|
||||||
|
|
||||||
|
|
||||||
|
### Vesting Account Data
|
||||||
|
The address, account sequence and account number fields for periodic vesting accounts have moved:
|
||||||
|
|
||||||
|
In v0.15 (kava-8):
|
||||||
|
|
||||||
|
|
||||||
|
```sh
|
||||||
|
curl /auth/accounts/kava1z3ytjpr6ancl8gw80z6f47z9smug7986x29vtj
|
||||||
|
```
|
||||||
|
```json
|
||||||
|
{"height":"3","result":{"type":"cosmos-sdk/PeriodicVestingAccount","value":{"address":"kava1z3ytjpr6ancl8gw80z6f47z9smug7986x29vtj","coins":[{"denom":"ukava","amount":"565077579"},{"denom":"usdx","amount":"1363200"}],"public_key":null,"account_number":"6","sequence":"0","original_vesting":[{"denom":"ukava","amount":"560159828"}],"delegated_free":[],"delegated_vesting":[],"end_time":"1628213878","start_time":"1596677878","vesting_periods":[{"length":"31536000","amount":[{"denom":"ukava","amount":"560159828"}]}]}}}
|
||||||
|
```
|
||||||
|
|
||||||
|
|
||||||
|
**Note**: address, account sequence and account number can be found at
|
||||||
|
- `.result.value.address`
|
||||||
|
- `.result.value.sequence`
|
||||||
|
- `.result.value.account_number`
|
||||||
|
|
||||||
|
In v0.16 (kava-9):
|
||||||
|
|
||||||
|
```sh
|
||||||
|
curl /auth/accounts/kava1z3ytjpr6ancl8gw80z6f47z9smug7986x29vtj`
|
||||||
|
```
|
||||||
|
|
||||||
|
```json
|
||||||
|
{"height":"4059","result":{"type":"cosmos-sdk/PeriodicVestingAccount","value":{"base_vesting_account":{"base_account":{"address":"kava1fwfwmt6vupf3m9uvpdsuuc4dga8p5dtl4npcqz","public_key":{"type":"tendermint/PubKeySecp256k1","value":"A3CJ0ejMGhGhxC9dRqKooEkiOj++kMh+lFDbdN283QHE"},"account_number":"18","sequence":"2"},"original_vesting":[{"denom":"ukava","amount":"560159828"}],"delegated_free":[],"delegated_vesting":[],"end_time":"1664632800"},"start_time":"1633096800","vesting_periods":[{"length":"31536000","amount":[{"denom":"ukava","amount":"560159828"}]}]}}}`
|
||||||
|
```
|
||||||
|
|
||||||
|
**Note**: address, account sequence and account number can be found at
|
||||||
|
- `.result.value.base_vesting_account.base_account.address`
|
||||||
|
- `.result.value.base_vesting_account.base_account.sequence`
|
||||||
|
- `.result.value.base_vesting_account.base_account.account_number`
|
||||||
|
|
||||||
|
### Legacy encoded transactions (POST /txs)
|
||||||
|
The Cosmos team found vulnerabilities in legacy transaction support and removed the [POST] /txs endpoints from v0.44.0 of the cosmos-sdk. To avoid this backwards incompatibility, kava-9 introduces a custom [POST] /txs endpoint that converts legacy (amino) transactions to the new proto encoding and broadcasts the converted tx. Implementation details can be found [here](https://github.com/Kava-Labs/kava/pull/1070).
|
||||||
|
|
||||||
|
### Javascript-SDK
|
||||||
|
|
||||||
|
The Kava Javascript-SDK has been updated to support kava-9, including the new [POST] /txs endpoint. This means that applications utilizing the Javascript-SDK can simply update:
|
||||||
|
|
||||||
|
`npm i @kava-labs/javascript-sdk@latest`
|
||||||
|
|
||||||
@ -25,15 +25,15 @@ make install
|
|||||||
|
|
||||||
### Upgrade
|
### Upgrade
|
||||||
|
|
||||||
The scheduled mainnet upgrade to `kava-8` took place on August 30th, 2021 at 15:00 UTC. The current version of Kava for `kava-8` is [__v0.15.1__](https://github.com/Kava-Labs/kava/releases/tag/v0.15.1).
|
The scheduled mainnet upgrade to `kava-9` took place on January 19th, 2022 at 15:00 UTC. The current version of Kava for `kava-9` is [__v0.16.1__](https://github.com/Kava-Labs/kava/releases/tag/v0.16.1).
|
||||||
|
|
||||||
The canonical genesis file can be found [here](https://github.com/Kava-Labs/launch/tree/master/kava-8)
|
The canonical genesis file can be found [here](https://github.com/Kava-Labs/launch/tree/master/kava-9)
|
||||||
|
|
||||||
The canonical genesis file hash is
|
The canonical genesis file hash is
|
||||||
|
|
||||||
```
|
```
|
||||||
jq -S -c -M '' genesis.json | shasum -a 256
|
jq -S -c -M '' genesis.json | shasum -a 256
|
||||||
f0c90f0cbf96d230a83cd2309b8fd032e52d7fb933881541472df1bf2703a939 -
|
5c688df5ae6cba9c9e5a9bab045eb367dd54ce9b7f5fab78cf3e636cf2e2b793 -
|
||||||
```
|
```
|
||||||
|
|
||||||
For additional information about upgrades:
|
For additional information about upgrades:
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user