sei-protocol · alexander-sei · Aug 14, 2026 · Aug 13, 2026 · Aug 13, 2026 · Aug 14, 2026
diff --git a/STYLE_GUIDE.md b/STYLE_GUIDE.md
@@ -1,4 +1,4 @@
 # Sei Docs Style Guide

 This style guide contains general rules and principles to ensure the documentation is cohesive, useful, and organized.

@@ -6,7 +6,7 @@

 This documentation strives to be:

 ### Beginner Friendly

 The Sei community welcomes members from all walks of life. As such, the documentation should be understandable by anyone, including those who are new to Web3 or non-technical.

@@ -22,8 +22,8 @@

 - To be clear and inclusive, avoid using jargon and obscure words where possible.
 - Limit the number of clauses in a sentence and make sure that your points are structured.
 - Avoid qualifying language, which is ~~quite~~ often ~~completely~~ unnecessary.
 - Information should be simply organized and easy to find.

 ### Self-explanatory

@@ -64,30 +64,30 @@
 - **Reference**: Transactions, RPC reference, tokens, changelog, ecosystem contracts
 - **Hardware Wallets**: Ledger integration with Ethers

 ### Cosmos-SDK (Deprecated)

 > ⚠️ **Deprecation Notice**: Cosmos SDK and CosmWasm functionality is being deprecated in favor of EVM-only. For more details, see [SIP-3](https://github.com/sei-protocol/sips/blob/main/sips/sip-3.md) and [Proposal 99](https://seistream.app/proposals/99).

 This section contains legacy documentation for Cosmos SDK functionality. New development should focus on the EVM.

 ### Operate (Node)

 The Operate section covers topics related to running Sei infrastructure. This is relevant for node operators, validators, and those looking to contribute to chain infrastructure.

 **Contents include:**
 
 - **Node Operations**: Overview, Seictl setup, statesync, snapshot sync, node types, troubleshooting, API configuration, validators, oracle price feeder
-- **Advanced Operations**: Configuration & monitoring, RocksDB backend, technical reference
+- **Advanced Operations**: Configuration & monitoring, Giga SS Store migration, technical reference
 
 ## Style Guidelines
 
 ### Acronyms and Abbreviations

 To maximize clarity, we should avoid acronyms and abbreviations where possible, especially for shorter, more ambiguous acronyms:

 - Just use 'CosmWasm' instead of 'CW'

 However, there are occasions where acronyms might be more easily understandable (e.g., NFT instead of Non-Fungible Token, RPC instead of Remote Procedure Call), or referred to very frequently.

 In these cases, we should first use the spelled-out term followed by the shortened form in parentheses:

@@ -252,7 +252,7 @@
 </Frame>
 ```

 ### Callouts and Admonitions

 Use callouts to highlight important information. Mintlify supports the following callout types:


diff --git a/assets/pebbledb-vs-rocksdb.png b/assets/pebbledb-vs-rocksdb.png
diff --git a/docs.json b/docs.json
@@ -339,7 +339,6 @@
             "group": "Advanced Operations",
             "pages": [
               "node/advanced-config-monitoring",
-              "node/rocksdb-backend",
               "node/giga-storage-migration",
               "node/technical-reference"
             ]
@@ -899,6 +898,11 @@
       "destination": "/node",
       "permanent": true
     },
+    {
+      "source": "/node/rocksdb-backend",
+      "destination": "/node/node-operators#move-off-rocksdb",
+      "permanent": true
+    },
     {
       "source": "/node/oracle-price-feeder",
       "destination": "/learn/oracles",

diff --git a/node/giga-storage-migration.mdx b/node/giga-storage-migration.mdx
@@ -15,7 +15,7 @@
 | Layer | Cosmos backend | EVM backend |
 |---|---|---|
 | **SC** (State Commit, app hash) | `memiavl` | FlatKV |
-| **SS** (State Store, historical queries) | single MVCC DB (PebbleDB or RocksDB) | dedicated EVM SS MVCC DB(s) under `data/evm_ss/` |
+| **SS** (State Store, historical queries) | single PebbleDB MVCC database | dedicated EVM SS MVCC databases in the configured EVM SS directory |
 
 Only the **SS** layer changes for this migration. SC layer config is untouched
 and `memiavl` remains the authoritative source for the app hash, so this is
@@ -43,9 +43,6 @@
 
 - EVM reads are served exclusively from a dedicated EVM SS database.
 - Non-EVM modules no longer pay write amplification for EVM state.
-- A backend change (PebbleDB ↔ RocksDB) can be combined with the same state
-  sync, since `ss-backend` drives both the Cosmos SS MVCC DB and every EVM SS
-  sub-DB.
 
 ## What's different about EVM SS
 
@@ -55,9 +52,9 @@
 per-type sub-DB layout. Any EVM read that needs iteration must stay on the
 Cosmos SS side.

 ## Migration Steps

 ### Step 1: Update `app.toml`

 Apply the following settings in `~/.sei/config/app.toml`:

@@ -69,8 +66,7 @@
 [state-store]
 ss-enable = true
 
-# DBBackend for the Cosmos SS MVCC DB and for every EVM SS sub-DB.
-# Supported: pebbledb, rocksdb. Default pebbledb.
+# Use PebbleDB for the Cosmos SS MVCC DB and every EVM SS sub-DB.
 ss-backend = "pebbledb"
 
 # Route EVM state to the dedicated EVM SS backend.
@@ -80,14 +76,7 @@
 evm-ss-split = true
 ```
 
-If you want to switch SS backend in the same step:
-
-- **PebbleDB → RocksDB**: set `ss-backend = "rocksdb"`, build `seid` with
-  `-tags rocksdbBackend`, and install RocksDB per the
-  [RocksDB Backend Guide](/node/rocksdb-backend). `ss-backend` drives both the
-  Cosmos SS MVCC DB and every EVM SS sub-DB, so a single setting flips both.
-- No data migration tool is needed across backends — the state sync populates
-  the new layout.
+<Warning>Keep `ss-backend = "pebbledb"` during this migration. RocksDB support for the state store will be removed. No target release has been published. If the node already uses RocksDB, follow [Move off RocksDB](/node/node-operators#move-off-rocksdb).</Warning>
 
 ### Step 2: State sync into the new layout
 
@@ -175,10 +164,9 @@
 
 1. **EVM SS directory missing or empty** (before the EVM SS is opened). When
    `evm-ss-split = true`, the composite state store refuses to proceed if
-   Cosmos SS already has committed history but the EVM SS directory
-   (`data/evm_ss/` by default) does not exist or is empty. Failing before
-   the sub-DBs are opened means a rejected config does not leave a confusing
-   empty `data/evm_ss/` behind.
+   Cosmos SS already has committed history but the configured EVM SS directory
+   does not exist or is empty. Failing before the sub-DBs are opened means a
+   rejected config does not leave a confusing empty directory behind.
 2. **EVM SS DB empty post-open, pre-recovery.** Belt-and-suspenders for (1)
    when the directory exists but its DBs are empty. The WAL only covers the
    last `KeepRecent` blocks, so replay cannot rebuild a fresh EVM SS from
@@ -190,31 +178,35 @@
 
 If any check fires, the correct fix is either (a) complete the state sync
 described above, or (b) set `evm-ss-split = false` and restart. If
-`data/evm_ss/` is stale from a failed attempt, remove it before state syncing.
+the configured EVM SS directory is stale from a failed attempt, remove it
+before state syncing.
 
 ## Rollback
 
 To roll back:
 
 1. Set `evm-ss-split = false` in `app.toml`.
-2. Restart the node. The EVM SS DB under `data/evm_ss/` is no longer opened
-   but stays on disk until manually removed.
+2. Restart the node. The EVM SS DB is no longer opened but stays on disk until
+   you remove it.
 
 To fully reclaim the disk used by EVM SS, stop the node and delete
-`data/evm_ss/` after reverting the setting.
+the configured EVM SS directory after reverting the setting.
 
 <Warning>Cleanly rolling back to `evm-ss-split = false` requires another state sync. Under `evm-ss-split = true`, EVM writes go only to the EVM SS DB, so Cosmos SS will not have those writes. Restarting with `evm-ss-split = false` stops opening the EVM SS DB, but EVM-state queries will miss anything written after the Giga state sync until you re-state-sync without the split.</Warning>
 
 ## FAQ
 
 ### Where do the data files live after migrating?
 
-- Cosmos SS data lives under the same directory as before, typically
-  `data/pebbledb/` for the default `pebbledb` backend.
-- EVM SS data lives under `data/evm_ss/`.
+- Cosmos SS data uses `data/pebbledb/` in the legacy layout and
+  `data/state_store/cosmos/pebbledb/` in the current layout.
+- EVM SS data uses `data/evm_ss/` in the legacy layout and
+  `data/state_store/evm/pebbledb/` in the current layout.
+- A non-empty `ss-db-directory` or `evm-ss-db-directory` overrides the
+  corresponding default path.
 - SC data (`memiavl` + FlatKV) is untouched by this migration.
 
 ### Does Giga SS Store change the app hash or consensus?

 No. The SC layer is unchanged, so `memiavl` remains the authoritative source
 for the app hash. Giga SS Store is a per-node SS change that is invisible to
@@ -241,7 +233,7 @@
 translate into missing EVM state at query time. The safety checks above
 block this scenario at startup.

 ### Does Giga SS Store support historical proofs?

 No, same as SeiDB. SS stores raw KVs and does not reconstruct IAVL-style
 proofs.
diff --git a/node/index.mdx b/node/index.mdx
@@ -19,13 +19,13 @@
  <Card horizontal title="Archive Nodes" icon="database" />
 </CardGroup>

 ## Network Versions

 <VersionTable />

 _Live binary versions, genesis, and seed peers — see the [technical reference](/node/technical-reference)._

 ## Hardware Requirements

 | Component | Required                                               |
 | --------- | ------------------------------------------------------ |
@@ -34,7 +34,7 @@
 | Storage   | 2 TB NVMe SSD (high IOPS required)                     |
 | Network   | 2 Gbps with low latency                                |

 ## Installation & Setup Steps

 <Steps>

@@ -47,13 +47,13 @@
 sudo apt update && sudo apt upgrade -y
 ```

 ###### 2. Install Essential Packages

 ```bash
 sudo apt install make gcc git jq chrony curl lz4 wget tar build-essential -y
 ```

 ###### 3. Synchronize System Time

 ```bash
 sudo timedatectl set-timezone UTC
@@ -61,7 +61,7 @@
 timedatectl
 ```

 ##### Install Go

 You need Go only if you build `seid` from source. The prebuilt binary and Docker
 install paths in the next step do not require it.
@@ -71,7 +71,7 @@
 (e.g. [`v6.6.1`](https://github.com/sei-protocol/sei-chain/blob/v6.6.1/go.mod)) for its
 exact requirement.

 ###### Installation Steps

 ```bash
 # Check for existing Go installations — more than one entry means another copy
@@ -138,12 +138,10 @@
     ```
 
     <Info>
-      Prebuilt binaries are attached from `v6.6.1` onward — for earlier versions, build
-      from source or use Docker. They are `linux/amd64` only, omit hardware Ledger
-      support, and don't include the optional
-      [RocksDB state-store backend](/node/rocksdb-backend). On other architectures, or
-      if you sign with a Ledger device, build from source or use Docker; a
-      RocksDB-enabled `seid` must be built from source.
+      Prebuilt binaries are attached from `v6.6.1` onward. For earlier versions,
+      build from source or use Docker. They are `linux/amd64` only and omit hardware
+      Ledger support. On other architectures, or if you sign with a Ledger device,
+      build from source or use Docker.
     </Info>
 
     <Note>
@@ -198,7 +196,7 @@
  </Tab>
 </Tabs>

 ##### Initialize Chain Files

 <Info>Default init mode is **full** (RPC/P2P bind to all interfaces). For **validator** or **seed** nodes, use `--mode validator` or `--mode seed` so RPC and P2P bind to localhost only. See the [Validator Operations Guide](/node/validators) for the full validator init example.</Info>

@@ -226,7 +224,7 @@
 sed -i 's/persistent-peers = .*/persistent-peers = "'$PEERS'"/' ~/.sei/config/config.toml
 ```

 ##### Configure App Settings

 ```bash
 # Set minimum gas price (recommended; helps prevent spam transactions)
@@ -256,7 +254,7 @@

 <Accordion title="Advanced Configuration">

 #### Archive Node Setup

 An archive node maintains the complete historical record of the chain. This requires disabling state sync and starting with a pre-existing database using a "snapshot".

@@ -270,7 +268,7 @@

 **2. Configure Archive Node Peers** — To sync from the height your snapshot was created at, you need peers retaining a large amount of historical blocks. The node will require specific peers during initial sync, which can be changed at a later time.

 #### Mempool Configuration

 For optimal transaction handling and resource management, it is recommended to update the mempool settings in your `config.toml` file.

@@ -358,7 +356,7 @@
 sudo systemctl start seid
 ```

 ##### Monitoring & Troubleshooting

 Check your node's status with these commands:

@@ -394,9 +392,9 @@

 [View Complete Node Setup Guide](/node/node-operators)

 ## Node Resources

 ### Node Setup

 <CardGroup cols={3}>
  <Card horizontal title="Node Operations Guide" icon="server" href="/node/node-operators">
@@ -410,14 +408,14 @@
  </Card>
 </CardGroup>

 ### Advanced Operations

 <CardGroup cols={3}>
   <Card horizontal title="Configuration & Monitoring" icon="gauge-simple-high" href="/node/advanced-config-monitoring">
     Optimize your node's performance with advanced settings and monitoring tools.
   </Card>
-  <Card horizontal title="RocksDB Backend" icon="database" href="/node/rocksdb-backend">
-    Run with RocksDB instead of the default backend.
+  <Card horizontal title="Giga SS Store Migration" icon="database" href="/node/giga-storage-migration">
+    Move EVM historical state into dedicated state-store databases on supported RPC nodes.
   </Card>
   <Card horizontal title="Technical Reference" icon="terminal" href="/node/technical-reference">
     Detailed technical specifications, API endpoints, and commands for node operators.

diff --git a/node/node-operators.mdx b/node/node-operators.mdx
@@ -2,16 +2,16 @@
 title: 'Sei Node Operations Guide'
 sidebarTitle: 'Overview'
 description: 'Detailed guide for running and maintaining Sei nodes. Learn about configuration management, database maintenance, service management, and update procedures.'
-keywords: ['sei node', 'blockchain node', 'node configuration', 'seidb', 'node maintenance', 'system operations']
+keywords: ['sei node', 'blockchain node', 'node configuration', 'seidb', 'node maintenance', 'system operations', 'rocksdb']
 ---
 
 This guide covers the detailed operational aspects of running a Sei node,
 including configuration management, maintenance procedures, and best practices
 for stable and performant operations.

 ## Configuration Management

 ### Directory Structure

 The Sei node configuration is stored in `$HOME/.sei/config/`:

@@ -25,15 +25,24 @@
 └── priv_validator_key.json  # Validator private signing key (if running as a validator)
 ```
 
+The state-store databases live outside the config directory:
+
+- Cosmos SS uses `$HOME/.sei/data/{backend}` in the legacy layout and
+  `$HOME/.sei/data/state_store/cosmos/{backend}` in the current layout.
+- EVM SS uses `$HOME/.sei/data/evm_ss` in the legacy layout and
+  `$HOME/.sei/data/state_store/evm/{backend}` in the current layout.
+- Non-empty `ss-db-directory` and `evm-ss-db-directory` settings override
+  those locations.
+
 The snippets below are opinionated tuning recommendations layered on top of
 the defaults. For the *full* unmodified `app.toml`, `config.toml`, and
 `client.toml` shipped by the latest tagged `seid` release, jump to
 [Default Configurations](#default-configurations) at the bottom of this
 section.

 ### Essential Configuration Parameters

 #### Network Settings (config.toml)

 ```toml
 [p2p]
@@ -59,7 +68,7 @@
 timeout-broadcast-tx-commit = "10s"
 ```

 #### Application Settings (app.toml)

 ```toml
 # Minimum gas prices to prevent spam transactions
@@ -89,6 +98,8 @@
 [state-store]
 # Historical SS layer for queries. Required for any node serving RPC.
 ss-enable = true
+# State-store backend. Use PebbleDB; RocksDB support will be removed.
+ss-backend = "pebbledb"
 # 0 = keep everything; 100,000 is roughly 28 hours of pacific-1 history.
 ss-keep-recent = 100000
 
@@ -97,12 +108,14 @@
 rs-backend = "pebbledb"
 ```

 ### Default Configurations

 The full unmodified `app.toml`, `config.toml`, and `client.toml` produced by
 `seid init` against the latest tagged `seid` release. Use these as the
 canonical reference for every available knob and its default value.
 
+<Warning>The generated `app.toml` below mirrors the latest tagged release and may still list RocksDB as a state-store option. Do not use RocksDB for new or resynced nodes. RocksDB support for the SeiDB state store will be removed. No target release has been published.</Warning>
+
 <Tabs>
   <Tab title="app.toml">
 
@@ -1349,7 +1362,7 @@
  </Tab>
 </Tabs>

 ## Database Management

 ### Architecture

@@ -1366,15 +1379,14 @@
    modes is set to a non-default value.
 2. **State Store (SS)** — versioned raw key/value pairs used for historical
    queries. Required for any node that serves RPC. The default backend is
-   **PebbleDB**; **RocksDB** is available for iteration-heavy workloads such
-   as archive nodes or RPC nodes that run a lot of `debug_trace*` (see the
-   [RocksDB Backend Guide](/node/rocksdb-backend) for build instructions).
+   **PebbleDB**. Do not use RocksDB for new nodes. If you already use RocksDB,
+   follow [Move off RocksDB](#move-off-rocksdb) before support is removed.
 
 The legacy IAVL backend is still selectable via `sc-enable = false` but is
 deprecated and slated for removal — new deployments and existing nodes
 should run on SeiDB.

 ### SeiDB Configuration

 The full set of knobs is in the auto-generated
 [Default Configurations](#default-configurations) above. The block below
@@ -1420,7 +1432,7 @@
 # serving RPC must keep it on.
 ss-enable = true
 
-# pebbledb (default) or rocksdb (faster iteration, archive-friendly).
+# Use PebbleDB. RocksDB support will be removed.
 ss-backend = "pebbledb"
 
 ss-async-write-buffer = 100
@@ -1448,7 +1460,60 @@
 snapshot creation. Too-large (less frequent) intervals mean pruning takes
 longer overall, which can cause missed blocks and excessive resync time.
 
+#### PebbleDB version encoding
+
+Fresh PebbleDB state stores use descending-version MVCC encoding. Sei includes
+the version in each key and sorts newer versions first. This lets
+latest-version reads reach the newest visible value without scanning older
+versions. The store records this format with the `s/_mvcc_descending` sentinel
+key, which `seid` detects automatically when it opens the database.
+
+PebbleDB state stores created by older builds use ascending-version encoding.
+`seid` detects these stores and opens them in compatibility mode without an
+error. They remain on the slower ascending read path. Rebuild the state store
+through [state sync](/node/statesync) with a current `seid` release to adopt
+descending encoding. A filesystem snapshot preserves the source store's
+encoding, so confirm its encoding with the snapshot provider.
+
+### Move off RocksDB
+
+<Warning>RocksDB support for the SeiDB state store will be removed. No target release has been published. Check the [Sei release notes](https://github.com/sei-protocol/sei-chain/releases) before every upgrade.</Warning>
+
+RocksDB and PebbleDB use different on-disk formats. Changing
+`ss-backend = "rocksdb"` to `ss-backend = "pebbledb"` against the same data
+does not convert the store. Rebuild the state store instead.
+
+For a non-archive node:
+
+1. Stop `seid` and back up the validator key, validator state, node key,
+   configuration, and genesis file that you need to preserve.
+2. Check `ss-db-directory` and `evm-ss-db-directory` in `app.toml`. An empty
+   value uses a path under `$HOME/.sei/data`. If either setting points
+   elsewhere, move the old RocksDB data out of the active path and keep it
+   with the backup. Clearing `$HOME/.sei/data` does not clear a custom
+   directory.
+3. Set `ss-backend = "pebbledb"`, then rebuild through
+   [state sync](/node/statesync) or a provider-confirmed
+   [PebbleDB snapshot](/node/snapshot).
+4. Confirm the startup log reports `"SeiDB SS is enabled"` with the PebbleDB
+   backend. Test the RPC methods your node serves before you delete the old
+   RocksDB backup.
+
+<Danger>Do not use state sync or a pruned snapshot to migrate an archive node. Both start from a recent height and discard the earlier state-store versions that an archive node must retain.</Danger>
+
+There is no documented in-place migration for a RocksDB archive node. Build a
+separate replacement from a trusted full-history PebbleDB source. Keep the
+RocksDB node on a compatible `seid` release until the replacement has caught
+up and you have tested historical queries at old heights. If you cannot obtain
+a full-history PebbleDB source, do not wipe the existing archive data. Contact
+the [Sei Tech Chat](https://t.me/+KZdhZ1eE-G01NmZk) before you upgrade.
+
+PebbleDB can be slower for iteration-heavy historical queries, including
+`debug_trace*` requests. Descending-version encoding improves recent reads,
+but it does not remove the cost of long-history iteration. Benchmark the
+replacement under your trace workload before you cut over.
+
 ### Giga Storage and Giga Executor
 
 These are two **separate** opt-in features that ship in newer `seid`
 releases. Both default to off; only enable them deliberately and after
@@ -1492,7 +1557,7 @@
 occ_enabled = false
 ```

 ### Database Maintenance

 The database is typically stable and can be left alone, although some attention
 may be required:
@@ -1519,9 +1584,9 @@

 <Warning>The wipe command above deletes the entire local database (everything except `priv_validator_state.json`) and the `wasm` folder. It does not compact data in place — after running it, the node must be re-synced from a [snapshot](/node/snapshot) or via [state sync](/node/statesync) before it can serve traffic again.</Warning>

 ## Service Management

 ### Systemd Commands

 ```bash
 # Check service status
@@ -1540,7 +1605,7 @@
 journalctl -fu seid -o cat
 ```

 ### Log Management

 Prevent logs from consuming excessive disk space by enabling rotation:

@@ -1561,7 +1626,7 @@
 EOF
 ```

 ## Update Procedures

 <Info>
  Upgrade with the same method you originally installed with: `make install`
@@ -1571,7 +1636,7 @@
  `which -a seid` lists every copy.
 </Info>

 ### Minor Updates

 For minor updates that are non-consensus-breaking:

@@ -1613,7 +1678,7 @@
  </Tab>
 </Tabs>

 ### Major Updates

 For major upgrades that introduce state-breaking changes:

@@ -1657,7 +1722,7 @@
  halt-height so the swap takes seconds at upgrade time.
 </Tip>

 ## Performance Optimization

 Performance optimizations can yield different results depending on your system's
 hardware, workload, and network conditions. Before implementing any changes,
@@ -1665,7 +1730,7 @@
 your specific configuration and requirements. Always back up important data
 before making modifications.

 ### Memory Management (sysctl tuning)

 Optimizing memory management settings can help improve performance and
 stability, particularly for high-load nodes. These settings control swap usage
@@ -1679,7 +1744,7 @@
 vm.dirty_writeback_centisecs = 100  # Frequency (in hundredths of a second) at which the system writes "dirty" pages to disk
 ```

 ### Network Stack Optimization

 Tuning the network stack can enhance packet processing efficiency and
 throughput, particularly for nodes handling a large number of peers and high
@@ -1693,7 +1758,7 @@
 net.core.wmem_max = 16777216  # send buffer size for network sockets
 ```

 ### Storage Optimization

 Optimizing storage settings can significantly reduce write latency and improve
 database performance, especially for nodes using NVMe SSDs.
@@ -1703,9 +1768,9 @@
 blockdev --setra 4096 /dev/nvme0n1  # readahead value to optimize sequential reads
 ```

 ## Backup and Recovery

 ### Regular Backups

 Automate backups to avoid data loss:

@@ -1724,7 +1789,7 @@
 systemctl start seid
 ```

 ### Recovery Procedure

 Restoring from backup in case of corruption or accidental deletion:

@@ -1742,7 +1807,7 @@
 systemctl start seid
 ```

 ## Security Considerations

 - Use firewalls and rate-limiting to prevent attacks
 - Keep your system and node software updated