Skip to main content

​
Overview

As Sei nodes accumulate more history and state data, iteration-heavy operations—like those performed during traceBlock calls—can become significantly slower. This is especially true for archive or RPC nodes where the state store contains millions of versions. To address this, Sei supports RocksDB as an alternative backend to PebbleDB. RocksDB provides native multi-version concurrency control (MVCC) and column family support, which leads to substantial iteration performance improvements as history grows.

​
Why RocksDB?

PebbleDB lacks native MVCC support, meaning Sei must manually encode versions into keys. This retrofit approach causes iteration time to grow linearly with the amount of stored history. As a result:
  • Archive nodes with large state stores experience slower debug trace latency.
  • Each key lookup may require scanning multiple key versions.
  • Iterations (e.g., over Oracle or EVM module keys) become increasingly expensive over time.
By contrast, RocksDB supports native user-defined timestamps and optimized column families for versioned data access. This means:
  • Iterations over keys at a single version are much faster.
  • Historical data growth has minimal effect on iteration cost.
  • The performance advantage amplifies with larger node history.
In Sei’s benchmarks, RocksDB achieved up to 10–30× faster traceBlock iteration times compared to PebbleDB, with even greater benefits observed on archive nodes.

​
PebbleDB descending-version encoding

Recent PebbleDB builds partly narrow this gap for latest-version reads. Because PebbleDB has no native MVCC, Sei encodes the version into each key. Freshly created PebbleDB state stores now use a descending-version MVCC encoding, which sorts newer versions before older ones for the same logical key. This lets latest-version reads land directly on the newest visible version instead of scanning through older versions, improving read performance on the fast path. Fresh stores are marked on disk with a sentinel key (s/_mvcc_descending) so the mode is detected automatically on open. Legacy PebbleDB stores written by earlier builds use the older ascending-version encoding. These are detected automatically on open and read using the legacy ascending path—no error is raised—but they stay unmarked and cannot benefit from the descending fast path unless the store is recreated or migrated. This mirrors the migration constraint on RocksDB: archive nodes that cannot recreate their state store will continue running on the slower legacy path. Note that even with descending encoding, PebbleDB still lacks native MVCC and column-family support, so RocksDB remains the recommended backend for iteration-heavy archive and long-history RPC workloads.

​
Example: TraceBlock Latency Comparison

The following chart compares iteration (trace time) performance between PebbleDB and RocksDB over a 3 million block history: PebbleDB vs RocksDB Trace Times Trace Times: Pebble vs Rocks (3M history): RocksDB shows a significantly flatter latency curve as state grows, while PebbleDB’s iteration times increase sharply for older blocks.

​
Setup Instructions

RocksDB only needs to be built once. After that, you can install seid with RocksDB support directly.

​
Prerequisites

Ensure your system includes the following packages:

​
Build & Install

Refer to the Sei Makefile here for the official targets.
Once installed, your seid binary will be built with RocksDB backend support:

​
Configuration

After installation, update your configuration file to enable the RocksDB backend:
Set

​
Node Setup Notes

  • RPC Nodes — must perform a state sync when spinning up a new node configured with RocksDB.
  • Archive Nodes — currently, RocksDB is not supported for existing data unless syncing from genesis. A migration route from PebbleDB to RocksDB is being developed and will be shared soon.

​
Summary

​
TL;DR

  • RocksDB backend drastically improves trace iteration and historical query performance.
  • Install once, then run:
  • Update ~/.sei/config/app.toml to use RocksDB:
  • RPC nodes require state sync; archive nodes must currently sync from genesis
  • Expect 10–30× faster trace latencies, especially on archive nodes or long-history setups.