RocksDB Backend Setup & Performance

Overview

As Paxeer 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, Paxeer 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 the node 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 benchmarks, RocksDB achieved up to 10 - 30× faster traceBlock iteration times compared to PebbleDB, with even greater benefits observed on archive nodes.

Setup Instructions

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

Prerequisites

Ensure your system includes the following packages:

sudo apt-get update
sudo apt-get install -y build-essential pkg-config cmake git zlib1g-dev \
    libbz2-dev libsnappy-dev liblz4-dev libzstd-dev libjemalloc-dev \
    libgflags-dev liburing-dev

Build & Install

# Step 1: Build RocksDB (one-time setup)
make build-rocksdb

# Step 2: Install paxd with RocksDB backend
make install-rocksdb

Once installed, your paxd binary will be built with RocksDB backend support:

paxd version
# should include "rocksdbBackend" build tag

Configuration

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

~/.paxeer/config/app.toml

Set

ss-backend = "rocksdb"

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.

Summary

TL;DR

• RocksDB backend drastically improves trace iteration and historical query performance.
• Install once, then run:

make install-rocksdb

• Update ~/.paxeer/config/app.toml to use RocksDB:

ss-backend = "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.