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#seidb-configuration",
+      "permanent": true
+    },
     {
       "source": "/node/oracle-price-feeder",
       "destination": "/learn/oracles",

diff --git a/node/giga-storage-migration.mdx b/node/giga-storage-migration.mdx
@@ -2,7 +2,7 @@
 title: 'Giga SS Store Migration Guide'
 sidebarTitle: 'Giga SS Store Migration'
 description: 'Migrate a Sei RPC node to Giga SS Store: split EVM state into a dedicated state-store backend so non-EVM modules stop paying EVM write amplification.'
-keywords: ['sei node', 'giga storage', 'seidb', 'state sync', 'evm ss', 'flatkv', 'rpc node', 'pebbledb', 'rocksdb']
+keywords: ['sei node', 'giga storage', 'seidb', 'state sync', 'evm ss', 'flatkv', 'rpc node', 'pebbledb']
 ---
 
 Giga SS Store is the next step in Sei's storage evolution on top of [SeiDB](/node/node-operators#architecture).
@@ -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 under `data/evm_ss/` |
 
 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.</Warning>
 
 ### Step 2: State sync into the new layout
 
@@ -205,7 +194,7 @@

 <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?

@@ -214,7 +203,7 @@
 - EVM SS data lives under `data/evm_ss/`.
 - 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 +230,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
@@ -9,9 +9,9 @@
 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/`:

@@ -31,9 +31,9 @@
 [Default Configurations](#default-configurations) at the bottom of this
 section.

 ### Essential Configuration Parameters

 #### Network Settings (config.toml)

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

 #### Application Settings (app.toml)

 ```toml
 # Minimum gas prices to prevent spam transactions
@@ -89,6 +89,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 +99,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 +1353,7 @@
  </Tab>
 </Tabs>

 ## Database Management

 ### Architecture

@@ -1366,15 +1370,18 @@
    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**. RocksDB support for this layer will be removed. No target
+   release has been published. Check the
+   [Sei release notes](https://github.com/sei-protocol/sei-chain/releases)
+   before each upgrade. Use PebbleDB for new nodes. Before upgrading, resync
+   any node that uses RocksDB onto PebbleDB through [state sync](/node/statesync)
+   or a [PebbleDB snapshot](/node/snapshot).
 
 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 +1427,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
@@ -1444,11 +1451,26 @@
 prune-interval-seconds = 600
 ```
 
+#### 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.
+
 Setting small (more frequent) pruning intervals may collide with
 snapshot creation. Too-large (less frequent) intervals mean pruning takes
 longer overall, which can cause missed blocks and excessive resync time.

 ### 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 +1514,7 @@
 occ_enabled = false
 ```

 ### Database Maintenance

 The database is typically stable and can be left alone, although some attention
 may be required:
@@ -1519,9 +1541,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 +1562,7 @@
 journalctl -fu seid -o cat
 ```

 ### Log Management

 Prevent logs from consuming excessive disk space by enabling rotation:

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

 ## Update Procedures

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

 ### Minor Updates

 For minor updates that are non-consensus-breaking:

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

 ### Major Updates

 For major upgrades that introduce state-breaking changes:

@@ -1657,7 +1679,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 +1687,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 +1701,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 +1715,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 +1725,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 +1746,7 @@
 systemctl start seid
 ```

 ### Recovery Procedure

 Restoring from backup in case of corruption or accidental deletion:

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

 ## Security Considerations

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

diff --git a/node/rocksdb-backend.mdx b/node/rocksdb-backend.mdx
diff --git a/node/snapshot.mdx b/node/snapshot.mdx
@@ -8,11 +8,13 @@

 Follow this guide to join an existing network through **snapshot sync**. To quickly spin up a fresh full node and join the network, it's recommended to restore from a snapshot instead of replaying all historical blocks.

 ## Snapshot Sync
 
 Snapshot sync allows a new node to join a network by downloading a recent, compressed copy of the entire application state and extracting it directly into the data directory. This reduces the initial sync time from days to minutes.
 
+<Warning>RocksDB support for the SeiDB state store will be removed. No target release has been published. For new or resynced nodes, use a snapshot only after confirming that its state store uses PebbleDB. Keep `ss-backend = "pebbledb"` in `app.toml`.</Warning>
+
 ## Snapshot Providers
 
 You can select from various providers for downloading snapshots:

@@ -23,6 +25,10 @@
 
 <iframe src="https://seistream.app/labs?page=snapshots" width="100%" height="600" style={{ border: 'none', borderRadius: '8px' }} title="Sei Snapshot Providers" />
 
+Snapshot providers do not consistently label the state-store backend. Follow
+the verification step below before you extract a snapshot. If you cannot
+identify the backend from the archive, ask the provider to confirm it.
+
 ## Clean Up & Preparation
 
 If you are **not** starting a node from fresh, perform the following backups and clean‑ups first.
@@ -79,21 +85,37 @@
    SNAPSHOT_URL="<PASTE_SNAPSHOT_URL_HERE>"
    ```
 
-2. **Download and Extract**
-   Most providers compress the `data` and `wasm` directory directly. The following command streams the download and extracts it into `$HOME/.sei`.
+2. **Download, verify, and extract**
+   Most providers compress the `data` and `wasm` directories directly. Download the archive so you can inspect its state-store path before extraction:
 
    ```bash
-   curl -L $SNAPSHOT_URL | lz4 -c -d | tar -x -C $HOME/.sei
+   curl -L "$SNAPSHOT_URL" -o snapshot.tar.lz4
+
+   lz4 -c -d snapshot.tar.lz4 | tar -tf - | \
+     awk '/(^|\/)data\/(state_store\/cosmos\/)?(pebbledb|rocksdb)\// { print; exit }'
    ```
 
-   **Alternative: Parallel Download with aria2**
+   The printed path must contain either `data/pebbledb/` or
+   `data/state_store/cosmos/pebbledb/`. Do not extract the archive if the path
+   contains `rocksdb` or the command prints no state-store path.
+
+   Extract the verified archive, then remove it:
+
+   ```bash
+   lz4 -c -d snapshot.tar.lz4 | tar -x -C $HOME/.sei
+   rm snapshot.tar.lz4
+   ```
+
+   **Alternative: parallel download with aria2**
 
    For faster downloads, especially with large snapshots, you can use `aria2c` which supports parallel connections:
 
    ```bash
    # Download with 16 parallel connections
    aria2c -x 16 -s 16 -o snapshot.tar.lz4 $SNAPSHOT_URL
 
+   # Run the backend verification command above before extraction
+
    # Extract after download completes
    lz4 -c -d snapshot.tar.lz4 | tar -x -C $HOME/.sei
 
@@ -117,13 +139,18 @@
    cp $HOME/priv_validator_state.json $HOME/.sei/data/priv_validator_state.json
    ```
 
-4. **Enable SeiDB**
-   Make sure to enable `sei-db` in your config if it's not already enabled:
+4. **Enable SeiDB and configure PebbleDB**
+   Make sure SeiDB is enabled and the state-store backend is PebbleDB:
 
    ```bash
-   sed -i.bak -E "/^\[state-commit\]/,/^\[.*\]/ s|^(sc-enable[[:space:]]*=[[:space:]]*).*$|\1true| ; /^\[state-store\]/,/^\[.*\]/ s|^(ss-enable[[:space:]]*=[[:space:]]*).*$|\1true|" $HOME/.sei/config/app.toml
+   sed -i.bak -E "/^\[state-commit\]/,/^\[.*\]/ s|^[#[:space:]]*(sc-enable[[:space:]]*=[[:space:]]*).*$|\1true| ; /^\[state-store\]/,/^\[.*\]/ s|^[#[:space:]]*(ss-enable[[:space:]]*=[[:space:]]*).*$|\1true| ; /^\[state-store\]/,/^\[.*\]/ s|^[#[:space:]]*(ss-backend[[:space:]]*=[[:space:]]*).*$|\1\"pebbledb\"|" $HOME/.sei/config/app.toml
+
+   sed -n '/^\[state-store\]/,/^\[.*\]/p' $HOME/.sei/config/app.toml
    ```
 
+   Confirm that the output includes `ss-backend = "pebbledb"`. If the key is
+   absent, add it directly below `[state-store]` before you restart the node.
+
 5. **Restart the Node**
 
    ```bash