op-reth historical proof configuration

Configuration options for the op-reth historical proof store (v2).

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.

Syntax--proofs-history

proofs-history.storage-version

Storage format version for the historical proofs database.

For the v2 system, set this to v2.

Syntax--proofs-history.storage-version <PROOFS_HISTORY_STORAGE_VERSION>

Recommendedv2

proofs-history.storage-path

The path to the storage DB for proofs history.

Syntax--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).

Syntax--proofs-history.window <PROOFS_HISTORY_WINDOW>

Default1296000

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.

Syntax--proofs-history.verification-interval <PROOFS_HISTORY_VERIFICATION_INTERVAL>

Default0

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.

op-reth proofs init --chain <CHAIN> --datadir <DATA_DIR> --proofs-history.storage-path <PROOFS_HISTORY_STORAGE_PATH> --proofs-history.storage-version=v2

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.

op-reth proofs prune --chain <CHAIN> --datadir <DATA_DIR> --proofs-history.storage-path <PROOFS_HISTORY_STORAGE_PATH> --proofs-history.window <PROOFS_HISTORY_WINDOW>

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

op-reth proofs unwind --datadir <DATA_DIR> --proofs-history.storage-path <PROOFS_HISTORY_STORAGE_PATH> --target <TARGET_BLOCK>

RPC Endpoints

debug_proofsSyncStatus

Returns the current sync status of the proofs store.

debug_proofsSyncStatus → { "earliest": <block>, "latest": <block> }

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.*)

Metric	Type	Description
total_duration_seconds	Histogram	End-to-end time to process a block
execution_duration_seconds	Histogram	Time spent in EVM execution
state_root_duration_seconds	Histogram	Time spent calculating state root
write_duration_seconds	Histogram	Time spent writing trie updates to storage
account_trie_updates_written_total	Counter	Number of account trie branch nodes written
storage_trie_updates_written_total	Counter	Number of storage trie branch nodes written
hashed_accounts_written_total	Counter	Number of hashed account entries written
hashed_storages_written_total	Counter	Number of hashed storage entries written
earliest_number	Gauge	Earliest block number in the proofs store
latest_number	Gauge	Latest block number in the proofs store

Pruner (optimism_trie.pruner.*)

Metric	Type	Description
total_duration_seconds	Histogram	Duration of each prune run
pruned_blocks	Gauge	Number of blocks pruned in the last run
account_trie_updates_written	Gauge	Account trie entries deleted in the last prune
storage_trie_updates_written	Gauge	Storage trie entries deleted in the last prune
hashed_accounts_written	Gauge	Hashed account entries deleted in the last prune
hashed_storages_written	Gauge	Hashed storage entries deleted in the last prune

RPC (optimism_rpc.eth_api_ext.*)

Metric	Type	Description
get_proof_latency	Histogram	Latency of successful eth_getProof requests
get_proof_requests	Counter	Total eth_getProof requests received
get_proof_successful_responses	Counter	Total successful eth_getProof responses
get_proof_failures	Counter	Total failed eth_getProof requests

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.