From 2c2a3a332dbf253b14b9960ace477730fbd1585d Mon Sep 17 00:00:00 2001 From: Robert Pirtle Date: Thu, 22 Aug 2024 12:07:19 -0700 Subject: [PATCH] docs: prepare release candidate for iavl v1 (#2013) * docs: prepare release candidate for iavl v1 includes first pass migration instructions for upgrading to iavl v1. --- CHANGELOG.md | 38 +++++++++++++++++++++++++- migrate/v0_26/iavl-v1.md | 59 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 96 insertions(+), 1 deletion(-) create mode 100644 migrate/v0_26/iavl-v1.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 4234592f26..a79ac5ae31 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -36,6 +36,41 @@ Ref: https://keepachangelog.com/en/1.0.0/ ## [unreleased] +## [v0.26.2-iavl-v1-alpha.0] + +This is the first release candidate for Kava on IAVL V1. + +IAVL V1 is a new 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). + +The release is compatible with v0 data, but for the full performance benefits, node operators are +encouraged to update their data to the v1 format. + +For full-archive operators, an IAVL V1 snapshot will be made available in the coming weeks. +For validators & operators of pruning nodes, it is recommended that node data is re-created from scratch +via statesync. + +Future minor versions of v0.26 will be made available for both iavl v0 and iavl v1. +Future major versions will use IAVL V1 unless otherwise specified. + +Node operators using rocksdb are encouraged to use `tcmalloc` as their memory allocator. + +For more details see the [IAVL V1 migration guide](/migrate/v0_26/iavl-v1.md). + +### Features + +- (deps) Upgrade to IAVL V1 + - For backwards compatibility with v0 state, a patched version of IAVL v1 is used, available [here](https://github.com/Kava-Labs/iavl/tree/v1.2.0-kava.2). + - The patched version includes the following changes: + - Initial version of new modules is 1, not the current height. This matches the behavior of v0 + and prevents app hash mismatches during the v0.25 & v0.26 upgrade blocks that added modules. + - To prevent being interpreted as data for height 1, the version is saved with nonce 0, creating + a state similar to if the data has been pruned. + - An IAVL v1 reference node is saved at the upgrade height pointing to the version 1 data so app + data for the upgrade version can be properly loaded. + + ## [v0.26.2] ### Features @@ -419,7 +454,8 @@ the [changelog](https://github.com/cosmos/cosmos-sdk/blob/v0.38.4/CHANGELOG.md). [#750]: https://github.com/Kava-Labs/kava/pull/750 [#751]: https://github.com/Kava-Labs/kava/pull/751 [#780]: https://github.com/Kava-Labs/kava/pull/780 -[unreleased]: https://github.com/Kava-Labs/kava/compare/v0.26.2...release/v0.26.x +[unreleased]: https://github.com/Kava-Labs/kava/compare/v0.26.2-iavl-v1-alpha.0...release/v0.26.x-iavl-v1 +[v0.26.2-iavl-v1-alpha.0]: https://github.com/Kava-Labs/kava/compare/v0.26.2...v0.26.2-iavl-v1-alpha.0 [v0.26.2]: https://github.com/Kava-Labs/kava/compare/v0.26.1...v0.26.2 [v0.26.1]: https://github.com/Kava-Labs/kava/compare/v0.26.0...v0.26.1 [v0.26.0]: https://github.com/Kava-Labs/kava/compare/v0.25.0...v0.26.0 diff --git a/migrate/v0_26/iavl-v1.md b/migrate/v0_26/iavl-v1.md new file mode 100644 index 0000000000..2418a5e627 --- /dev/null +++ b/migrate/v0_26/iavl-v1.md @@ -0,0 +1,59 @@ +# IAVL V1 + +**IAVL V1 is a work in progress. Proceed at your own risk until a non-alpha version is tagged.** + +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 reduced the +storage footprint required for Kava nodes. + +Steps for using IAVL V1: + +**For `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.26.2-alpha.0 +make install +``` +3. Start kava as usual: `kava start` + +**For `rocksdb` nodes:** +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-alpha.0 +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 (all chain data snapshots available up until this time). +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 with the complete historical data, we expect to release archive data snapshots in the coming weeks. Stay tuned. + +## 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