diff --git a/migrate/v0_27/iavl-v1.md b/migrate/v0_27/iavl-v1.md deleted file mode 100644 index 28845e3d3..000000000 --- a/migrate/v0_27/iavl-v1.md +++ /dev/null @@ -1,110 +0,0 @@ -# IAVL V1 - -IAVL V1 is an updated data format for the low-level storage of application data in the Kava blockchain. -The change in format results in much more performant syncing of the chain, and greatly reduces the -storage footprint required for Kava nodes. - -As of `v0.27.0`, IAVL V1 is the data storage format for the Kava blockchain. - -# Configuration - -> [!IMPORTANT] -> Nodes running IAVL V1 should set `iavl-disable-fastnode = true` in their `app.toml` file. - -> [!IMPORTANT] -> Before starting kava on existing IAVL V0 data, please read the note about pruning changes. - -### `goleveldb` nodes -1. Replace or recreate your node data with IAVL V1: see [Data](#data). -2. Install an IAVL V1 binary: -```sh -git checkout v0.27.0 -make install -``` -3. Start kava as usual: `kava start` - -### `rocksdb` nodes - -> [!TIP] -> Since v0.26.2, databases are opened with [opendb](https://github.com/Kava-Labs/opendb/) which -> makes rocksdb more configurable. For best memory performance, node operators are encouraged to add -> these settings to their `app.toml` when running with `db_backend = rocksdb`: -> ```toml -> [rocksdb] -> max_open_files = 16384 # increase default max # of open files from 4096 -> block_size = 16384 # decreases block index memory by 4x! -> ``` - -1. Replace or recreate your node data with IAVL V1: see [Data](#data). -2. Update your default memory allocator: see [default memory allocator](#default-memory-allocator) -3. Install an IAVL V1 binary: -```sh -git checkout v0.26.2-iavl-v1 -make install COSMOS_BUILD_OPTIONS=rocksdb -``` -4. Start kava with the desired memory allocator: `LD_PRELOAD=/path/to/tcmalloc kava start` - -## Data - -The IAVL V1 binaries are compatible with IAVL V0 data, but it is recommended to start from state sync or a IAVL v1 snapshot. -However, for maximum performance & storage benefit, node operators should use data that is completely -built with IAVL V1. - -### Validators & Pruning nodes - -For nodes with minimal historical state, we recommend bootstrapping your node with statesync. -For an example of how to setup a node with statesync, see [here](https://www.polkachu.com/state_sync/kava). - -A public RPC server is available at `https://rpc.kava.io:443`. - -### Full-archive node - -For nodes that need complete historical data, a full archive IAVL v1 snapshot is avaiable at https://quicksync.io/kava. - -In addition to the most recent version on this file, the Release Notes for -[`v0.26.2-iavl-v1`](https://github.com/Kava-Labs/kava/releases/tag/v0.26.2-iavl-v1) will contain -links to data when they are available. - -Node operators can expect a more performant kava process that uses less than half the data storage -required of IAVL V0. - -## Default memory allocator - -For nodes using rocksdb, greatly improved memory performance was seen when using [`tcmalloc`](https://github.com/google/tcmalloc) -as the memory allocator. - -To update your node to use `tcmalloc`: -1. install `tcmalloc` - * via gperftools collection package (recommended) - * package manager: `apt-get install google-perftools` - * [gperftools Releases](https://github.com/gperftools/gperftools/releases) - * from source: see [tcmalloc Quickstart](https://google.github.io/tcmalloc/quickstart.html) -2. whenever running kava, do so with the new memory allocator: `LD_PRELOAD=/path/to/tcmalloc kava start` - * replace `/path/to/tcmalloc` above with correct path - -## IAVL V1 Pruning Changes - -There is an important difference in how changes to pruning settings are handled in IAVL V1. - -In IAVL V0, a change to pruning settings takes effect only for new blocks. In IAVL V1, all blocks are -pruned to the new settings the moment the change is made. - -When switching to IAVL V1 in this upgrade, you will experience a long startup time if your node has -had a change to pruning settings. If your node has changed its pruning settings during its runtime, -you are encouraged to upgrade with `pruning = "nothing"`. - -If you experience a long start time or an out of memory error on startup, try again with `pruning = "nothing"`. -For optimal performance, node operators are encouraged to reinitialize their node with fully IAVL V1 -data. - -**Example:** -A node is started with `pruning = "nothing"` on IAVL V0 (any release prior to `kava@v0.26.2-iavl-v1`). - -The node runs for awhile, is stopped, and then switched to `pruning = "everything"`. - -On startup, the node does not prune the existing blocks. Only new blocks are processed with the current -pruning setting. - -In IAVL V1 (when you start v0.27 on top of the above data), the `pruning = "everything"` setting is -applied to the entire state. Depending on how many blocks there are that should be pruned, the intial -start up can take a long time and may fail due to a lack of memory. diff --git a/migrate/v0_27/migrate.md b/migrate/v0_27/migrate.md deleted file mode 100644 index a01e08760..000000000 --- a/migrate/v0_27/migrate.md +++ /dev/null @@ -1,88 +0,0 @@ -# Kava 17 Upgrade Instructions - -## Software Version and Key Dates - -- The version of `kava` for Kava 17 is `v0.27.0` -- The Kava 17 chain will be shutdown with a `SoftwareUpgradeProposal` that - activates at height 12766500 at approximately 15:00 UTC on November 21, 2024. - -## Data Storage Changes - -Kava 17 uses IAVL V1, an improved storage format for the low-level data storage used by the Kava blockchain. - -Using IAVL V1 brings performance speedups for syncing and massively reduces the data stored on disk (~2.4x less data storage required for a full-archive node). - -For full-archive node operators, an IAVL V1 snapshot will be linked when available. We are working with partners to host IAVL V1 full historical data. -For validators & operators of pruning nodes, it is recommended that node data is recreated from scratch via statesync. - -Node operators using rocksdb are encouraged to [use `tcmalloc` as their memory allocator](./iavl-v1.md#default-memory-allocator). - -**See the [IAVL V1 migration guide](./iavl-v1.md).** - -## 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 if you are using `< v9.3.1`. The tested and recommended RocksDB version is `v9.3.1`. -Please reference the [RocksDB repository](https://github.com/facebook/rocksdb/tree/v9.3.1) to update your installation before building the RocksDB kava binary. - -Node operators using rocksdb are encouraged to [use `tcmalloc` as their memory allocator](https://github.com/Kava-Labs/kava/blob/v0.26.2-iavl-v1/migrate/v0_26/iavl-v1.md#default-memory-allocator). - -## On the day of the upgrade - -The kava chain is expected to halt at block height **12766500**. **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.22.7+ and not a different version.** Golang 1.22.6 and below may cause app hash mismatches! - -To update to v0.27.0 - -```sh -# check go version - look for 1.22.7+! -go version -# go version go1.22.9 linux/amd64 - -# in the `kava` folder -git fetch -git checkout v0.27.0 - -# Note: Golang 1.22.7+ must be installed before this step -make install - -# verify versions -kava version --long -# name: kava -# server_name: kava -# version: 0.27.0 -# commit: e77e0fed1cd64fdbc9f40dac6737c9e7a33cd4ae -# build_tags: netgo ledger, -# go: go version go1.22.9 linux/amd64 -# build_deps: -# ... -# cosmos_sdk_version: v0.47.10 - -# 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 17 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.26.x of the Kava software and restore to their latest snapshot before restarting their nodes. - -### Coordination - -If the Kava 17 chain does not launch by November 22nd 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). diff --git a/migrate/v0_28/migrate.md b/migrate/v0_28/migrate.md new file mode 100644 index 000000000..b88bfc22a --- /dev/null +++ b/migrate/v0_28/migrate.md @@ -0,0 +1,103 @@ +# Kava 18 Upgrade Instructions + +## Software Version and Key Dates + +- The version of `kava` for Kava 18 is `v0.28.0` +- The Kava 18 chain will be shutdown with a `SoftwareUpgradeProposal` that + activates at height 14136737 at approximately 15:00 UTC on February 25, 2025. + +## Dependency Changes + +packet-forwarding-middleware is updated to resolve unreliability of USDT IBC +transactions. + +### For validators using RocksDB + +> [!NOTE] +> If you use goleveldb or other database backends, this is not required. + +There are no changes in rocksDB version requirements for this upgrade. + +Same as the previous version, the recommended RocksDB version is `v9.3.1`. + +Please reference the [RocksDB repository](https://github.com/facebook/rocksdb/tree/v9.3.1) to update your installation before building the RocksDB kava binary. + +Node operators using rocksdb are encouraged to [use `tcmalloc` as their memory allocator](https://github.com/Kava-Labs/kava/blob/v0.26.2-iavl-v1/migrate/v0_26/iavl-v1.md#default-memory-allocator). + +## On the day of the upgrade + +The kava chain is expected to halt at block height **14136737**. +**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.22.7+ and not a different version.** Golang 1.22.6 and below may cause app hash mismatches! + +To update to v0.28.0 + +```sh +# check go version - look for 1.22.7+! +go version +# go version go1.22.9 linux/amd64 + +# in the `kava` folder +git fetch +git checkout v0.28.0 + +# Note: Golang 1.22.7+ must be installed before this step +make install + +# verify versions +kava version --long +# build_deps: +# ... +# build_tags: netgo ledger, +# commit: d9ce773f62418183beac2e9168c7cfafa30bc508 +# cosmos_sdk_version: v0.47.15 +# go: go version go1.22.9 linux/amd64 +# name: kava +# server_name: kava +# version: 0.28.0 + +# 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 18 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.27.x of the Kava software and restore to their latest +snapshot before restarting their nodes. + +### Coordination + +If the Kava 18 chain does not launch by February 26th 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).