docs: prepare state store guidance for RocksDB removal

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:
 

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",

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 deprecated and removed in upcoming Sei releases.</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.

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.

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,7 @@
 [state-store]
 # Historical SS layer for queries. Required for any node serving RPC.
 ss-enable = true
+ss-backend = "pebbledb"
 # 0 = keep everything; 100,000 is roughly 28 hours of pacific-1 history.
 ss-keep-recent = 100000
 
@@ -97,12 +98,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 deprecated and removed in upcoming Sei releases.</Warning>
+
 <Tabs>
   <Tab title="app.toml">
 
@@ -1349,7 +1352,7 @@
   </Tab>
 </Tabs>
 
 ## Database Management
 
 ### Architecture
 
@@ -1366,15 +1369,16 @@
    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 deprecated and removed
+   in upcoming Sei releases. 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 +1424,7 @@
 # serving RPC must keep it on.
 ss-enable = true
 
-# pebbledb (default) or rocksdb (faster iteration, archive-friendly).
+# Use the default PebbleDB backend.
 ss-backend = "pebbledb"
 
 ss-async-write-buffer = 100
@@ -1448,7 +1452,7 @@
 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 +1496,7 @@
 occ_enabled = false
 ```
 
 ### Database Maintenance
 
 The database is typically stable and can be left alone, although some attention
 may be required:
@@ -1519,9 +1523,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 +1544,7 @@
 journalctl -fu seid -o cat
 ```
 
 ### Log Management
 
 Prevent logs from consuming excessive disk space by enabling rotation:
 
@@ -1561,7 +1565,7 @@
 EOF
 ```
 
 ## Update Procedures
 
 <Info>
   Upgrade with the same method you originally installed with: `make install`
@@ -1571,7 +1575,7 @@
   `which -a seid` lists every copy.
 </Info>
 
 ### Minor Updates
 
 For minor updates that are non-consensus-breaking:
 
@@ -1613,7 +1617,7 @@
   </Tab>
 </Tabs>
 
 ### Major Updates
 
 For major upgrades that introduce state-breaking changes:
 
@@ -1657,7 +1661,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 +1669,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 +1683,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 +1697,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 +1707,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 +1728,7 @@
 systemctl start seid
 ```
 
 ### Recovery Procedure
 
 Restoring from backup in case of corruption or accidental deletion:
 
@@ -1742,7 +1746,7 @@
 systemctl start seid
 ```
 
 ## Security Considerations
 
 - Use firewalls and rate-limiting to prevent attacks
 - Keep your system and node software updated

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 deprecated and removed in upcoming Sei releases. Use a PebbleDB snapshot for new or resynced nodes, and keep `ss-backend = "pebbledb"` in `app.toml`. If your node currently uses RocksDB, resync it onto PebbleDB before upgrading to a release without RocksDB support.</Warning>
+
 ## Snapshot Providers
 
 You can select from various providers for downloading snapshots:
 
@@ -117,11 +119,11 @@
    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|^(sc-enable[[:space:]]*=[[:space:]]*).*$|\1true| ; /^\[state-store\]/,/^\[.*\]/ s|^(ss-enable[[:space:]]*=[[:space:]]*).*$|\1true| ; /^\[state-store\]/,/^\[.*\]/ s|^(ss-backend[[:space:]]*=[[:space:]]*).*$|\1\"pebbledb\"|" $HOME/.sei/config/app.toml
    ```
 
 5. **Restart the Node**

node/statesync.mdx

@@ -6,11 +6,13 @@
 ---
 Follow this guide to join an existing network through statesync. To quickly spin up a fresh full node and join in the network, it's recommended to sync through state sync.
 
 ## State Sync
 
 State sync allows a new node to join a network by fetching a snapshot of the application state at a recent height instead of fetching and replaying all historical blocks. This can reduce the time needed to sync with the network from days to minutes.
 
+<Warning>RocksDB support for the SeiDB state store will be deprecated and removed in upcoming Sei releases. Set `ss-backend = "pebbledb"` before you start state sync, especially when rebuilding a node that previously used RocksDB.</Warning>
+
 ## Clean Up
 
 If you are not starting a node from fresh, then you need to do some backups and clean ups.
 
@@ -37,7 +39,7 @@
 cp $HOME/priv_validator_state.json $HOME/.sei/data/priv_validator_state.json
 ```
 
 ## Statesync script
 
 Set up the RPC servers for primary and secondary endpoints. You can use one of these RPC endpoints for Statesyning
 
@@ -112,6 +114,10 @@
 # Set the persistent peers in the config.toml file to the specified State Sync Peer
 sed -i.bak -e "s|^persistent-peers *=.*|persistent-peers = \"$STATE_SYNC_PEER\"|" \
   $HOME/.sei/config/config.toml
+
+# Use PebbleDB for the SeiDB state store
+sed -i.bak -E '/^\[state-store\]/,/^\[.*\]/ s|^(ss-backend[[:space:]]*=[[:space:]]*).*$|\1"pebbledb"|' \
+  $HOME/.sei/config/app.toml
 ```
 
 Finally start the daemon: