Skip to main content
This page documents the configuration options for the historical proof store (v2) in op-reth. When enabled, op-reth maintains a separate storage database for versioned trie data used to serve eth_getProof for historical blocks. This is critical for historical state access (for example, fault proof workloads) without requiring full archive-style behavior from the execution database.
op-reth v2.2.3 or later is required to enable historical proofs v2. Earlier versions do not support the --proofs-history.storage-version=v2 flag.
Use the historical proofs storage format v2 by setting --proofs-history.storage-version=v2.
For a complete setup guide, see the tutorial on Running op-reth with Historical Proofs.
This fork inherits all standard op-reth configuration options. See the op-reth configuration reference.

​
Historical proof store (v2)

Options for configuring the v2 historical proof store.

​
proofs-history

If true, enable the historical proof store and keep it updated as new blocks are processed.
--proofs-history

​
proofs-history.storage-version

Storage format version for the historical proofs database. For the v2 system, set this to v2.
--proofs-history.storage-version <PROOFS_HISTORY_STORAGE_VERSION>

​
proofs-history.storage-path

The path to the storage DB for proofs history.
--proofs-history.storage-path <PROOFS_HISTORY_STORAGE_PATH>

​
proofs-history.window

The window to span blocks for proofs history. Value is the number of blocks. Default is 1 month of blocks based on 2 seconds block time (30 * 24 * 60 * 60 / 2 = 1,296,000).
--proofs-history.window <PROOFS_HISTORY_WINDOW>

​
proofs-history.verification-interval

Verification interval: perform full block execution every N blocks for data integrity.
  • 0: Disabled (Default). Always use fast path with pre-computed data.
  • 1: Always verify. Always execute blocks.
  • N: Verify every Nth block (e.g., 100 = every 100 blocks).
Periodic verification helps catch data corruption while maintaining good performance.
--proofs-history.verification-interval <PROOFS_HISTORY_VERIFICATION_INTERVAL>

​
Lifecycle and management commands

In v2, operators usually follow this lifecycle:
  1. Run op-reth proofs init once to initialize the proofs DB at the current tip.
  2. Start op-reth with --proofs-history --proofs-history.storage-version=v2 so the node uses historical proofs storage format v2.
  3. Let the store fill proofs data forward from the initialization point.
  4. Let automatic pruning enforce the configured retention window.
  5. Use manual prune or unwind only for recovery/maintenance scenarios.
The op-reth proofs command provides these maintenance operations.

​
init

Initialize the proofs storage with the current state of the chain.
The first time proofs init runs, it can take minutes to hours. Subsequent invocations should usually take seconds.proofs init does not backfill historical proofs. It records the current chain tip as the starting point of the proofs database. After initialization, run the node with --proofs-history so the store fills forward as new blocks are committed.To serve proofs across the full retention window (for example, 30 days with default settings), the node must accumulate that much forward history after init. In practice, operators should initialize from a snapshot that is already old enough to satisfy the required historical window as syncing advances.

​
prune

Prune old proof history to reclaim space.
Pruning runs automatically while the node is up, driven by the engine task as new blocks are committed; no separate interval flag is required.Manual prune is mainly a recovery action, for example if op-reth detects a large mismatch between configured retention and on-disk data and refuses startup. See the tutorial for details.

​
unwind

Unwind the proofs storage to a specific block

​
RPC Endpoints

​
debug_proofsSyncStatus

Returns the current sync status of the proofs store.
earliest and latest define the currently available historical-proof interval in the v2 store. Once latest tracks chain tip, eth_getProof calls for blocks within [earliest, latest] are served from the versioned proofs store.

​
v1 to v2 operator notes

  • The historical-proof path is now centered on a dedicated versioned proofs store lifecycle (init -> forward fill -> prune), rather than treating it as a standalone extension workflow.
  • proofs init establishes a starting point only; it does not reconstruct old proofs data.
  • Coverage is operationally measured via debug_proofsSyncStatus (earliest/latest).
  • For stable long-window proof serving, validate startup snapshots and retention settings together.

​
Metrics

When the metrics feature is enabled, the proofs-history system exposes Prometheus metrics to monitor health and performance.

​
Block processing (optimism_trie.block.*)

​
Pruner (optimism_trie.pruner.*)

​
RPC (optimism_rpc.eth_api_ext.*)

​
Storage operations (optimism_trie.storage.operation.*)

Per-operation duration_seconds histograms are recorded for: store_account_branch, store_storage_branch, store_hashed_account, store_hashed_storage, trie_cursor_seek_exact, trie_cursor_seek, trie_cursor_next, trie_cursor_current, hashed_cursor_seek, hashed_cursor_next.