You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 95084f7
Browse filesBrowse the repository at this point in the historyBrowse files
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).
Copy file name to clipboardExpand all lines: evm/installing-seid-cli.mdx
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -12,7 +12,7 @@ The `seid` CLI is the command-line tool for interacting with the Sei blockchain.
12
12
13
13
## Prerequisites
14
14
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.
Copy file name to clipboardExpand all lines: llms.txt
-1Lines changed: 0 additions & 1 deletion
Original file line number
Diff line number
Diff line change
@@ -171,7 +171,6 @@ Sei supports full nodes (recent state, consensus relay), archive nodes (complete
171
171
- [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.
172
172
- [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.
173
173
- [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.
175
174
- [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.
176
175
- [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.
|**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|
19
19
20
20
Only the **SS** layer changes for this migration. SC layer config is untouched
21
21
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.
43
43
44
44
- EVM reads are served exclusively from a dedicated EVM SS database.
45
45
- 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.
49
46
50
47
## What's different about EVM SS
51
48
@@ -69,8 +66,7 @@ sc-enable = true
69
66
[state-store]
70
67
ss-enable = true
71
68
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.
74
70
ss-backend = "pebbledb"
75
71
76
72
# Route EVM state to the dedicated EVM SS backend.
@@ -80,14 +76,7 @@ ss-backend = "pebbledb"
80
76
evm-ss-split = true
81
77
```
82
78
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>
91
80
92
81
### Step 2: State sync into the new layout
93
82
@@ -175,10 +164,9 @@ flipping `evm-ss-split` from `false` to `true` without state syncing.
175
164
176
165
1.**EVM SS directory missing or empty** (before the EVM SS is opened). When
177
166
`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.
182
170
2.**EVM SS DB empty post-open, pre-recovery.** Belt-and-suspenders for (1)
183
171
when the directory exists but its DBs are empty. The WAL only covers the
184
172
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.
190
178
191
179
If any check fires, the correct fix is either (a) complete the state sync
192
180
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.
194
183
195
184
## Rollback
196
185
197
186
To roll back:
198
187
199
188
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.
202
191
203
192
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.
205
194
206
195
<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>
207
196
@@ -316,16 +305,15 @@ and bytes migrated.
316
305
317
306
### Where do the data files live after migrating?
318
307
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.
329
317
- SC data (`memiavl` + FlatKV) is untouched by this migration.
330
318
331
319
### Does Giga SS Store change the app hash or consensus?
Copy file name to clipboardExpand all lines: node/node-operators.mdx
+70-5Lines changed: 70 additions & 5 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,7 +2,7 @@
2
2
title: 'Sei Node Operations Guide'
3
3
sidebarTitle: 'Overview'
4
4
description: 'Detailed guide for running and maintaining Sei nodes. Learn about configuration management, database maintenance, service management, and update procedures.'
This guide covers the detailed operational aspects of running a Sei node,
@@ -25,6 +25,15 @@ $HOME/.sei/config/
25
25
└── priv_validator_key.json # Validator private signing key (if running as a validator)
26
26
```
27
27
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
+
28
37
The snippets below are opinionated tuning recommendations layered on top of
29
38
the defaults. For the *full* unmodified `app.toml`, `config.toml`, and
30
39
`client.toml` shipped by the latest tagged `seid` release, jump to
@@ -91,6 +100,8 @@ sc-enable = true
91
100
[state-store]
92
101
# Historical SS layer for queries. Required for any node serving RPC.
93
102
ss-enable = true
103
+
# State-store backend. Use PebbleDB; RocksDB support will be removed.
104
+
ss-backend = "pebbledb"
94
105
# 0 = keep everything; 100,000 is roughly 28 hours of pacific-1 history.
95
106
ss-keep-recent = 100000
96
107
@@ -115,6 +126,8 @@ The full unmodified `app.toml`, `config.toml`, and `client.toml` produced by
115
126
`seid init` against the latest tagged `seid` release. Use these as the
116
127
canonical reference for every available knob and its default value.
117
128
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
+
118
131
<Tabs>
119
132
<Tabtitle="app.toml">
120
133
@@ -1429,9 +1442,8 @@ legacy single-database IAVL store with separate hot- and historical-data tiers:
1429
1442
migration mode or `flatkv_only`.
1430
1443
2.**State Store (SS)** — versioned raw key/value pairs used for historical
1431
1444
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.
1435
1447
1436
1448
The legacy IAVL backend has been fully removed. Setting `sc-enable = false`
1437
1449
makes the node panic at startup with `SeiDB state-commit (SC) must be
@@ -1487,7 +1499,7 @@ snapshot-keep-recent = 2
1487
1499
# serving RPC must keep it on.
1488
1500
ss-enable = true
1489
1501
1490
-
#pebbledb (default) or rocksdb (faster iteration, archive-friendly).
1502
+
#Use PebbleDB. RocksDB support will be removed.
1491
1503
ss-backend = "pebbledb"
1492
1504
1493
1505
ss-async-write-buffer = 100
@@ -1515,6 +1527,59 @@ Setting small (more frequent) pruning intervals may collide with
1515
1527
snapshot creation. Too-large (less frequent) intervals mean pruning takes
1516
1528
longer overall, which can cause missed blocks and excessive resync time.
1517
1529
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
0 commit comments