Skip to content

Commit 95084f7

Browse files
committed
Merge main into docs-bridge/release-v6.6.0
Resolves the FAQ data-locations conflict in giga-storage-migration.mdx by taking main's pebbledb-only phrasing and override bullet (PR #62 RocksDB deprecation) and folding in the verified legacy-path precedence rule (GetStateStorePath/GetEVMStateStorePath: an existing legacy directory wins; new nodes use the structured layout).
2 parents 46de0dc + b9e98f3 commit 95084f7

13 files changed

Lines changed: 614 additions & 403 deletions

‎STYLE_GUIDE.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -77,7 +77,7 @@ The Operate section covers topics related to running Sei infrastructure. This is
7777
**Contents include:**
7878

7979
- **Node Operations**: Overview, Seictl setup, statesync, snapshot sync, node types, troubleshooting, API configuration, validators, oracle price feeder
80-
- **Advanced Operations**: Configuration & monitoring, RocksDB backend, technical reference
80+
- **Advanced Operations**: Configuration & monitoring, Giga SS Store migration, technical reference
8181

8282
## Style Guidelines
8383

‎assets/pebbledb-vs-rocksdb.png‎

-124 KB
Binary file not shown.

‎docs.json‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -339,7 +339,6 @@
339339
"group": "Advanced Operations",
340340
"pages": [
341341
"node/advanced-config-monitoring",
342-
"node/rocksdb-backend",
343342
"node/giga-storage-migration",
344343
"node/technical-reference"
345344
]
@@ -899,6 +898,11 @@
899898
"destination": "/node",
900899
"permanent": true
901900
},
901+
{
902+
"source": "/node/rocksdb-backend",
903+
"destination": "/node/node-operators#move-off-rocksdb",
904+
"permanent": true
905+
},
902906
{
903907
"source": "/node/oracle-price-feeder",
904908
"destination": "/learn/oracles",

‎evm/installing-seid-cli.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ The `seid` CLI is the command-line tool for interacting with the Sei blockchain.
1212

1313
## Prerequisites
1414

15-
- Go 1.23+ (build from source only): Installation instructions are available [here](https://go.dev/doc/install). The prebuilt binary has no prerequisites.
15+
- [Go 1.25.6 or later](https://go.dev/doc/install) is required only when building from source. Check the `go.mod` at the release tag you check out below (e.g. [`v6.6.1`](https://github.com/sei-protocol/sei-chain/blob/v6.6.1/go.mod)) for its exact requirement. Prebuilt binaries have no prerequisites.
1616

1717
## Installation
1818

‎llms-full.txt‎

Lines changed: 326 additions & 201 deletions
Large diffs are not rendered by default.

‎llms.txt‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -171,7 +171,6 @@ Sei supports full nodes (recent state, consensus relay), archive nodes (complete
171171
- [Swagger API Documentation](https://docs.sei.io/node/swagger): Learn how to enable and access Swagger API documentation for your Sei node. Configure the swagger endpoint in app.toml and view interactive API docs.
172172
- [Sei Validator Operations Guide](https://docs.sei.io/node/validators): Learn how to set up and maintain a validator node on Sei Network, including hardware security configuration, key management, monitoring practices, and governance participation requirements.
173173
- [Sei Node Advanced Configuration & Monitoring](https://docs.sei.io/node/advanced-config-monitoring): Optimize your Sei node's performance with advanced system configurations, monitoring setup with Prometheus and Grafana, and effective alerting strategies for maintaining reliable node operations.
174-
- [RocksDB Backend Setup & Performance](https://docs.sei.io/node/rocksdb-backend): Build and enable the RocksDB backend for seid to significantly improve iteration-heavy operations and traceBlock latency, especially on long-history RPC and archive nodes.
175174
- [Giga SS Store Migration Guide](https://docs.sei.io/node/giga-storage-migration): 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.
176175
- [Sei Technical Reference](https://docs.sei.io/node/technical-reference): Access detailed command syntax, configuration parameters, and troubleshooting procedures for node operators and validators running Sei network infrastructure.
177176

‎node/giga-storage-migration.mdx‎

Lines changed: 20 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ After migration the SS layer is repartitioned into two cooperating stores:
1515
| Layer | Cosmos backend | EVM backend |
1616
|---|---|---|
1717
| **SC** (State Commit, app hash) | `memiavl` | FlatKV |
18-
| **SS** (State Store, historical queries) | single MVCC DB (PebbleDB or RocksDB) | dedicated EVM SS MVCC DB(s) under `data/evm_ss/` |
18+
| **SS** (State Store, historical queries) | single PebbleDB MVCC database | dedicated EVM SS MVCC databases in the configured EVM SS directory |
1919

2020
Only the **SS** layer changes for this migration. SC layer config is untouched
2121
and `memiavl` remains the authoritative source for the app hash, so this is
@@ -43,9 +43,6 @@ local data directory and imports a fresh snapshot into the new layout.
4343

4444
- EVM reads are served exclusively from a dedicated EVM SS database.
4545
- Non-EVM modules no longer pay write amplification for EVM state.
46-
- A backend change (PebbleDB ↔ RocksDB) can be combined with the same state
47-
sync, since `ss-backend` drives both the Cosmos SS MVCC DB and every EVM SS
48-
sub-DB.
4946

5047
## What's different about EVM SS
5148

@@ -69,8 +66,7 @@ sc-enable = true
6966
[state-store]
7067
ss-enable = true
7168

72-
# DBBackend for the Cosmos SS MVCC DB and for every EVM SS sub-DB.
73-
# Supported: pebbledb, rocksdb. Default pebbledb.
69+
# Use PebbleDB for the Cosmos SS MVCC DB and every EVM SS sub-DB.
7470
ss-backend = "pebbledb"
7571

7672
# Route EVM state to the dedicated EVM SS backend.
@@ -80,14 +76,7 @@ ss-backend = "pebbledb"
8076
evm-ss-split = true
8177
```
8278

83-
If you want to switch SS backend in the same step:
84-
85-
- **PebbleDB → RocksDB**: set `ss-backend = "rocksdb"`, build `seid` with
86-
`-tags rocksdbBackend`, and install RocksDB per the
87-
[RocksDB Backend Guide](/node/rocksdb-backend). `ss-backend` drives both the
88-
Cosmos SS MVCC DB and every EVM SS sub-DB, so a single setting flips both.
89-
- No data migration tool is needed across backends — the state sync populates
90-
the new layout.
79+
<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>
9180

9281
### Step 2: State sync into the new layout
9382

@@ -175,10 +164,9 @@ flipping `evm-ss-split` from `false` to `true` without state syncing.
175164

176165
1. **EVM SS directory missing or empty** (before the EVM SS is opened). When
177166
`evm-ss-split = true`, the composite state store refuses to proceed if
178-
Cosmos SS already has committed history but the EVM SS directory
179-
(`data/evm_ss/` by default) does not exist or is empty. Failing before
180-
the sub-DBs are opened means a rejected config does not leave a confusing
181-
empty `data/evm_ss/` behind.
167+
Cosmos SS already has committed history but the configured EVM SS directory
168+
does not exist or is empty. Failing before the sub-DBs are opened means a
169+
rejected config does not leave a confusing empty directory behind.
182170
2. **EVM SS DB empty post-open, pre-recovery.** Belt-and-suspenders for (1)
183171
when the directory exists but its DBs are empty. The WAL only covers the
184172
last `KeepRecent` blocks, so replay cannot rebuild a fresh EVM SS from
@@ -190,18 +178,19 @@ flipping `evm-ss-split` from `false` to `true` without state syncing.
190178

191179
If any check fires, the correct fix is either (a) complete the state sync
192180
described above, or (b) set `evm-ss-split = false` and restart. If
193-
`data/evm_ss/` is stale from a failed attempt, remove it before state syncing.
181+
the configured EVM SS directory is stale from a failed attempt, remove it
182+
before state syncing.
194183

195184
## Rollback
196185

197186
To roll back:
198187

199188
1. Set `evm-ss-split = false` in `app.toml`.
200-
2. Restart the node. The EVM SS DB under `data/evm_ss/` is no longer opened
201-
but stays on disk until manually removed.
189+
2. Restart the node. The EVM SS DB is no longer opened but stays on disk until
190+
you remove it.
202191

203192
To fully reclaim the disk used by EVM SS, stop the node and delete
204-
`data/evm_ss/` after reverting the setting.
193+
the configured EVM SS directory after reverting the setting.
205194

206195
<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>
207196

@@ -316,16 +305,15 @@ and bytes migrated.
316305

317306
### Where do the data files live after migrating?
318307

319-
As of Sei v6.6, new nodes use a structured subdirectory layout. Existing nodes
320-
with legacy flat paths automatically keep using them (the legacy path takes
321-
precedence when present).
322-
323-
- Cosmos SS data lives under `data/state_store/cosmos/{backend}` on new nodes
324-
(e.g. `data/state_store/cosmos/pebbledb` for the default `pebbledb` backend).
325-
Existing nodes with legacy `data/pebbledb/` continue using it.
326-
- EVM SS data lives under `data/state_store/evm/{backend}` on new nodes
327-
(e.g. `data/state_store/evm/pebbledb`). Existing nodes with legacy
328-
`data/evm_ss/` continue using it.
308+
- Cosmos SS data uses `data/pebbledb/` in the legacy layout and
309+
`data/state_store/cosmos/pebbledb/` in the current layout.
310+
- EVM SS data uses `data/evm_ss/` in the legacy layout and
311+
`data/state_store/evm/pebbledb/` in the current layout.
312+
- Nodes created before the layout change keep their legacy paths automatically
313+
(a legacy directory takes precedence when present); new nodes use the
314+
current layout.
315+
- A non-empty `ss-db-directory` or `evm-ss-db-directory` overrides the
316+
corresponding default path.
329317
- SC data (`memiavl` + FlatKV) is untouched by this migration.
330318

331319
### Does Giga SS Store change the app hash or consensus?

‎node/index.mdx‎

Lines changed: 37 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -63,20 +63,34 @@ timedatectl
6363

6464
##### Install Go
6565

66-
Only needed if you build `seid` from source — the prebuilt binary and Docker
67-
install paths in the next step don't require Go.
66+
You need Go only if you build `seid` from source. The prebuilt binary and Docker
67+
install paths in the next step do not require it.
6868

69-
Suggested Version: Go 1.24.x (required for seid v6.3+)
69+
Current `seid` releases require Go 1.25.6 or later. Check the `go.mod` at the release tag
70+
you check out
71+
(e.g. [`v6.6.1`](https://github.com/sei-protocol/sei-chain/blob/v6.6.1/go.mod)) for its
72+
exact requirement.
7073

7174
###### Installation Steps
7275

7376
```bash
74-
# Check for existing Go installation
77+
# Check for existing Go installations — more than one entry means another copy
78+
# may still win on your PATH after this install
79+
which -a go
7580
go version
7681

77-
# Download and install Go 1.24.x
78-
wget https://go.dev/dl/go1.24.5.linux-amd64.tar.gz
79-
sudo tar -C /usr/local -xzf go1.24.5.linux-amd64.tar.gz
82+
# Bumping Go? Change these two lines only
83+
GO_TARBALL=go1.25.6.linux-amd64.tar.gz
84+
GO_SHA256=f022b6aad78e362bcba9b0b94d09ad58c5a70c6ba3b7582905fababf5fe0181a
85+
86+
curl -fLO https://go.dev/dl/${GO_TARBALL}
87+
88+
# Verify integrity before trusting the archive (go.dev/dl publishes a SHA256 per file
89+
# at ${GO_TARBALL}.sha256), then replace any previous installation — extracting over
90+
# one leaves stale files behind
91+
echo "${GO_SHA256} ${GO_TARBALL}" | sha256sum -c - \
92+
&& sudo rm -rf /usr/local/go \
93+
&& sudo tar -C /usr/local -xzf ${GO_TARBALL}
8094

8195
# Add Go to your environment variables
8296
echo 'export PATH=$PATH:/usr/local/go/bin' >> $HOME/.bashrc
@@ -85,6 +99,16 @@ source $HOME/.bashrc
8599
# Verify installation
86100
go version
87101
```
102+
103+
<Note>
104+
`sudo rm -rf /usr/local/go` is the replacement step [Go's install
105+
docs](https://go.dev/doc/install) prescribe, but it only clears a tarball install. A
106+
package-manager Go (`/usr/lib/go-*`, Homebrew) survives it and can still shadow
107+
`/usr/local/go/bin/go` — if the final `go version` reports the old release,
108+
`which -a go` lists every copy on your `PATH`. If the extraction itself fails, the
109+
verified tarball is still in your working directory: re-run the `sudo tar` command
110+
rather than starting over.
111+
</Note>
88112
</Step>
89113

90114
<Step title="Install Sei">
@@ -114,12 +138,10 @@ See the Network Versions table above for the current recommended version.
114138
```
115139

116140
<Info>
117-
Prebuilt binaries are attached from `v6.6.1` onward — for earlier versions, build
118-
from source or use Docker. They are `linux/amd64` only, omit hardware Ledger
119-
support, and don't include the optional
120-
[RocksDB state-store backend](/node/rocksdb-backend). On other architectures, or
121-
if you sign with a Ledger device, build from source or use Docker; a
122-
RocksDB-enabled `seid` must be built from source.
141+
Prebuilt binaries are attached from `v6.6.1` onward. For earlier versions,
142+
build from source or use Docker. They are `linux/amd64` only and omit hardware
143+
Ledger support. On other architectures, or if you sign with a Ledger device,
144+
build from source or use Docker.
123145
</Info>
124146

125147
<Note>
@@ -408,8 +430,8 @@ seid query staking validator $(seid keys show <your_key> --bech val -a)
408430
<Card horizontal title="Configuration & Monitoring" icon="gauge-simple-high" href="/node/advanced-config-monitoring">
409431
Optimize your node's performance with advanced settings and monitoring tools.
410432
</Card>
411-
<Card horizontal title="RocksDB Backend" icon="database" href="/node/rocksdb-backend">
412-
Run with RocksDB instead of the default backend.
433+
<Card horizontal title="Giga SS Store Migration" icon="database" href="/node/giga-storage-migration">
434+
Move EVM historical state into dedicated state-store databases on supported RPC nodes.
413435
</Card>
414436
<Card horizontal title="Technical Reference" icon="terminal" href="/node/technical-reference">
415437
Detailed technical specifications, API endpoints, and commands for node operators.

‎node/node-operators.mdx‎

Lines changed: 70 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
title: 'Sei Node Operations Guide'
33
sidebarTitle: 'Overview'
44
description: 'Detailed guide for running and maintaining Sei nodes. Learn about configuration management, database maintenance, service management, and update procedures.'
5-
keywords: ['sei node', 'blockchain node', 'node configuration', 'seidb', 'node maintenance', 'system operations']
5+
keywords: ['sei node', 'blockchain node', 'node configuration', 'seidb', 'node maintenance', 'system operations', 'rocksdb']
66
---
77

88
This guide covers the detailed operational aspects of running a Sei node,
@@ -25,6 +25,15 @@ $HOME/.sei/config/
2525
└── priv_validator_key.json # Validator private signing key (if running as a validator)
2626
```
2727

28+
The state-store databases live outside the config directory:
29+
30+
- Cosmos SS uses `$HOME/.sei/data/{backend}` in the legacy layout and
31+
`$HOME/.sei/data/state_store/cosmos/{backend}` in the current layout.
32+
- EVM SS uses `$HOME/.sei/data/evm_ss` in the legacy layout and
33+
`$HOME/.sei/data/state_store/evm/{backend}` in the current layout.
34+
- Non-empty `ss-db-directory` and `evm-ss-db-directory` settings override
35+
those locations.
36+
2837
The snippets below are opinionated tuning recommendations layered on top of
2938
the defaults. For the *full* unmodified `app.toml`, `config.toml`, and
3039
`client.toml` shipped by the latest tagged `seid` release, jump to
@@ -91,6 +100,8 @@ sc-enable = true
91100
[state-store]
92101
# Historical SS layer for queries. Required for any node serving RPC.
93102
ss-enable = true
103+
# State-store backend. Use PebbleDB; RocksDB support will be removed.
104+
ss-backend = "pebbledb"
94105
# 0 = keep everything; 100,000 is roughly 28 hours of pacific-1 history.
95106
ss-keep-recent = 100000
96107

@@ -115,6 +126,8 @@ The full unmodified `app.toml`, `config.toml`, and `client.toml` produced by
115126
`seid init` against the latest tagged `seid` release. Use these as the
116127
canonical reference for every available knob and its default value.
117128

129+
<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>
130+
118131
<Tabs>
119132
<Tab title="app.toml">
120133

@@ -1429,9 +1442,8 @@ legacy single-database IAVL store with separate hot- and historical-data tiers:
14291442
migration mode or `flatkv_only`.
14301443
2. **State Store (SS)** — versioned raw key/value pairs used for historical
14311444
queries. Required for any node that serves RPC. The default backend is
1432-
**PebbleDB**; **RocksDB** is available for iteration-heavy workloads such
1433-
as archive nodes or RPC nodes that run a lot of `debug_trace*` (see the
1434-
[RocksDB Backend Guide](/node/rocksdb-backend) for build instructions).
1445+
**PebbleDB**. Do not use RocksDB for new nodes. If you already use RocksDB,
1446+
follow [Move off RocksDB](#move-off-rocksdb) before support is removed.
14351447

14361448
The legacy IAVL backend has been fully removed. Setting `sc-enable = false`
14371449
makes the node panic at startup with `SeiDB state-commit (SC) must be
@@ -1487,7 +1499,7 @@ snapshot-keep-recent = 2
14871499
# serving RPC must keep it on.
14881500
ss-enable = true
14891501

1490-
# pebbledb (default) or rocksdb (faster iteration, archive-friendly).
1502+
# Use PebbleDB. RocksDB support will be removed.
14911503
ss-backend = "pebbledb"
14921504

14931505
ss-async-write-buffer = 100
@@ -1515,6 +1527,59 @@ Setting small (more frequent) pruning intervals may collide with
15151527
snapshot creation. Too-large (less frequent) intervals mean pruning takes
15161528
longer overall, which can cause missed blocks and excessive resync time.
15171529

1530+
#### PebbleDB version encoding
1531+
1532+
Fresh PebbleDB state stores use descending-version MVCC encoding. Sei includes
1533+
the version in each key and sorts newer versions first. This lets
1534+
latest-version reads reach the newest visible value without scanning older
1535+
versions. The store records this format with the `s/_mvcc_descending` sentinel
1536+
key, which `seid` detects automatically when it opens the database.
1537+
1538+
PebbleDB state stores created by older builds use ascending-version encoding.
1539+
`seid` detects these stores and opens them in compatibility mode without an
1540+
error. They remain on the slower ascending read path. Rebuild the state store
1541+
through [state sync](/node/statesync) with a current `seid` release to adopt
1542+
descending encoding. A filesystem snapshot preserves the source store's
1543+
encoding, so confirm its encoding with the snapshot provider.
1544+
1545+
### Move off RocksDB
1546+
1547+
<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>
1548+
1549+
RocksDB and PebbleDB use different on-disk formats. Changing
1550+
`ss-backend = "rocksdb"` to `ss-backend = "pebbledb"` against the same data
1551+
does not convert the store. Rebuild the state store instead.
1552+
1553+
For a non-archive node:
1554+
1555+
1. Stop `seid` and back up the validator key, validator state, node key,
1556+
configuration, and genesis file that you need to preserve.
1557+
2. Check `ss-db-directory` and `evm-ss-db-directory` in `app.toml`. An empty
1558+
value uses a path under `$HOME/.sei/data`. If either setting points
1559+
elsewhere, move the old RocksDB data out of the active path and keep it
1560+
with the backup. Clearing `$HOME/.sei/data` does not clear a custom
1561+
directory.
1562+
3. Set `ss-backend = "pebbledb"`, then rebuild through
1563+
[state sync](/node/statesync) or a provider-confirmed
1564+
[PebbleDB snapshot](/node/snapshot).
1565+
4. Confirm the startup log reports `"SeiDB SS is enabled"` with the PebbleDB
1566+
backend. Test the RPC methods your node serves before you delete the old
1567+
RocksDB backup.
1568+
1569+
<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>
1570+
1571+
There is no documented in-place migration for a RocksDB archive node. Build a
1572+
separate replacement from a trusted full-history PebbleDB source. Keep the
1573+
RocksDB node on a compatible `seid` release until the replacement has caught
1574+
up and you have tested historical queries at old heights. If you cannot obtain
1575+
a full-history PebbleDB source, do not wipe the existing archive data. Contact
1576+
the [Sei Tech Chat](https://t.me/+KZdhZ1eE-G01NmZk) before you upgrade.
1577+
1578+
PebbleDB can be slower for iteration-heavy historical queries, including
1579+
`debug_trace*` requests. Descending-version encoding improves recent reads,
1580+
but it does not remove the cost of long-history iteration. Benchmark the
1581+
replacement under your trace workload before you cut over.
1582+
15181583
### Giga Storage and Giga Executor
15191584

15201585
These are two **separate** opt-in features that ship in newer `seid`

0 commit comments

Comments
 (0)