mirror of
https://github.com/0glabs/0g-chain.git
synced 2024-12-27 00:35:18 +00:00
Add v0.25.0 upgrade guide and staking rewards doc (#1769)
* Add upgrade guide and staking rewards doc * Update date * Update date for upgrade vs failure * Use height 7637650 for upgrade * Adjust bolding * Use linux/amd64 in docs * Upgrade height at 7637070
This commit is contained in:
drklee3
0g-wh
parent
577f39b998
commit
897846b46f
80
migrate/v0_25/migrate.md
Normal file
80
migrate/v0_25/migrate.md
Normal file
@ -0,0 +1,80 @@
|
||||
# Kava 15 Upgrade Instructions
|
||||
|
||||
## Software Version and Key Dates
|
||||
|
||||
- The version of `kava` for Kava 15 is v0.25.0
|
||||
- The Kava 14 chain will be shutdown with a `SoftwareUpgradeProposal` that
|
||||
activates at approximately 15:00 UTC on December 7th, 2023.
|
||||
|
||||
## Dependency Changes
|
||||
|
||||
### For validators using RocksDB
|
||||
|
||||
> [!NOTE]
|
||||
> If you use goleveldb or other database backends, this is not required.
|
||||
|
||||
If you use RocksDB as your database backend, you will need to update RocksDB
|
||||
from v7 to v8. The tested and recommended RocksDB version is `v8.1.1`.
|
||||
Please reference the [RocksDB repository](https://github.com/facebook/rocksdb/tree/v8.1.1)
|
||||
to update your installation before building the RocksDB kava binary.
|
||||
|
||||
## API Changes
|
||||
|
||||
If you require calculating the yearly staking reward percentages, standard
|
||||
calculation will no longer be accurate. [Additional Details can be found here.](./staking_rewards.md)
|
||||
|
||||
### On the day of the upgrade
|
||||
|
||||
The kava chain is expected to halt at block height **7637070**. **Do not stop your node and begin the upgrade before the upgrade height**, or you may go offline and be unable to recover until after the upgrade!
|
||||
|
||||
**Make sure the kava 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.
|
||||
|
||||
**Ensure you are using golang 1.20.x and not a different version.** Golang 1.19 and below may cause app hash mismatches!
|
||||
|
||||
To update to v0.25.0
|
||||
|
||||
```sh
|
||||
# check go version - look for 1.20!
|
||||
go version
|
||||
# go version go1.20.5 linux/amd64
|
||||
|
||||
# in the `kava` folder
|
||||
git fetch
|
||||
git checkout v0.25.0
|
||||
|
||||
# Note: Golang 1.20 must be installed before this step
|
||||
make install
|
||||
|
||||
# verify versions
|
||||
kava version --long
|
||||
# name: kava
|
||||
# server_name: kava
|
||||
# version: 0.25.0
|
||||
# commit: <commit placeholder>
|
||||
# build_tags: netgo ledger,
|
||||
# go: go version go1.20.5 linux/amd64
|
||||
# build_deps:
|
||||
# ...
|
||||
# cosmos_sdk_version: v0.46.11
|
||||
|
||||
# Restart node -
|
||||
kava 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 applying the Kava 15 upgrade, validators are encouraged to take a full data snapshot at the upgrade height before proceeding. Snap-shotting depends heavily on infrastructure, but generally this can be done by backing up the .kava directory.
|
||||
|
||||
It is critically important to back-up the .kava/data/priv_validator_state.json file after stopping your kava 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.24.x of the Kava software and restore to their latest snapshot before restarting their nodes.
|
||||
|
||||
### Coordination
|
||||
|
||||
If the Kava 15 chain does not launch by December 8th, 2023 at 00:00 UTC, the launch should be considered a failure. In the event of launch failure, coordination will occur in the [Kava discord](https://discord.com/invite/kQzh3Uv).
|
||||
80
migrate/v0_25/staking_rewards.md
Normal file
80
migrate/v0_25/staking_rewards.md
Normal file
@ -0,0 +1,80 @@
|
||||
# Migrate Staking Reward Calculation to Endpoint
|
||||
|
||||
Kava 15 (v0.25.x) changes the mechanism for staking rewards, which will no longer be inflationary but will be paid out of the community module. In order to continue displaying expected yields or APYs to users, wallets and explorers will need to update.
|
||||
|
||||
The endpoint calculates staking rewards for the current kava version and is forward compatible with future changes.
|
||||
|
||||
All consumers who display yearly staking reward percentages are encouraged to migrate from the standard calculation to using the endpoint, as the standard calculation will no longer be accurate.
|
||||
|
||||
Endpoint: `/kava/community/v1beta1/annualized_rewards`
|
||||
Example Response:
|
||||
```json
|
||||
{
|
||||
"staking_rewards": "0.203023625910000000"
|
||||
}
|
||||
```
|
||||
|
||||
## Before Kava 15
|
||||
|
||||
The staking APR is calculated the same way as other cosmos-sdk chains. Various parameters are fetched and then combined in this calculation:
|
||||
```
|
||||
staking_apr ≈ mint_inflation *
|
||||
(1 - distribution_params.community_tax) *
|
||||
(total_supply_ukava/pool.bonded_tokens)
|
||||
```
|
||||
|
||||
_Note this doesn’t include transaction fees paid to stakers._
|
||||
|
||||
Endpoints used:
|
||||
|
||||
* https://api.data.kava.io/cosmos/mint/v1beta1/params
|
||||
* https://api.data.kava.io/cosmos/distribution/v1beta1/params
|
||||
* https://api.data.kava.io/cosmos/bank/v1beta1/supply/by_denom?denom=ukava
|
||||
* https://api.data.kava.io/cosmos/staking/v1beta1/pool
|
||||
|
||||
Informational Endpoints
|
||||
|
||||
* https://api.data.kava.io/cosmos/mint/v1beta1/inflation
|
||||
* https://api.data.kava.io/cosmos/mint/v1beta1/annual_provisions
|
||||
|
||||
## After Kava 15
|
||||
|
||||
Kava 15 implements new staking rewards as ratified in this proposal: https://www.mintscan.io/kava/proposals/141. They will come into effect at the “switchover time” on 2024-01-01 00:00 UTC.
|
||||
|
||||
* All delegating and claiming transactions remain unchanged. There is no change in how rewards are claimed or how claimable balances are queried.
|
||||
* After the switchover time, inflation will be set to zero (and rewards will be paid from the community module account).
|
||||
* After the switchover time, rewards are paid out according to:
|
||||
```
|
||||
staking apy ≈ community_params.staking_rewards_per_second *
|
||||
seconds_per_year / pool.bonded_tokens
|
||||
```
|
||||
|
||||
_Note this doesn’t include transaction fees paid to stakers._
|
||||
|
||||
* There is a new endpoint `kava/community/v1beta1/annualized_rewards`
|
||||
* before the switchover time, it will return the current staking APY (calculated in the previous section)
|
||||
* after the switchover time, it will return the new staking APY above
|
||||
|
||||
* Existing endpoints above will remain active, but the params will change such that the old apr calculation will return 0.
|
||||
|
||||
* https://api.data.kava.io/cosmos/mint/v1beta1/params
|
||||
* no format changes
|
||||
* `inflation_max` and `inflation_min` will be 0.0
|
||||
|
||||
* https://api.data.kava.io/cosmos/distribution/v1beta1/params
|
||||
* no format changes
|
||||
* `community_tax` will be 0.0
|
||||
|
||||
* https://api.data.kava.io/cosmos/bank/v1beta1/supply/by_denom?denom=ukava
|
||||
* no changes
|
||||
|
||||
* https://api.data.kava.io/cosmos/staking/v1beta1/pool
|
||||
* no changes
|
||||
|
||||
* https://api.data.kava.io/cosmos/mint/v1beta1/inflation
|
||||
* no format changes
|
||||
* `inflation` will be 0.0
|
||||
|
||||
* https://api.data.kava.io/cosmos/mint/v1beta1/annual_provisions
|
||||
* no format changes
|
||||
* `annual_provisions` will be 0.0
|
||||
Loading…
Reference in New Issue
Block a user