Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.optimism.io/llms.txt

Use this file to discover all available pages before exploring further.

This page provides documentation for the configuration options available in op-reth for supporting historical proofs via ExEx. By enabling this Execution Extension (ExEx), the node initializes a separate storage database specifically for historical trie nodes. This allows the node to generate and serve historical proofs efficiently, which is critical for applications requiring historical state access, such as fault proof systems. 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.

​
Proof History

Options for configuring the proof history ExEx.

​
proofs-history

If true, initialize external-proofs exex to save and serve trie nodes to provide proofs faster.
--proofs-history

​
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.prune-interval

Interval between proof-storage prune runs. Accepts human-friendly durations like “100s”, “5m”, “1h”.
  • Shorter intervals prune smaller batches more often.
  • Longer intervals prune larger batches less often.
A shorter interval is preferred so that prune runs stay small and don’t stall writes for too long.
--proofs-history.prune-interval <PROOFS_HISTORY_PRUNE_INTERVAL>

​
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>

​
Management Commands

The op-reth proofs command allows you to manage the storage of historical proofs.

​
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>

​
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, on the cadence set by --proofs-history.prune-interval. Running this command manually is only required at startup if op-reth detects a gap larger than 1000 blocks between the configured window and the data on disk and refuses to start. 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> }
Once latest tracks the chain tip, eth_getProof calls for blocks within [earliest, latest] will be served from the versioned store.

​
Metrics

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

​
Block processing (optimism_trie.block.*)

MetricTypeDescription
total_duration_secondsHistogramEnd-to-end time to process a block
execution_duration_secondsHistogramTime spent in EVM execution
state_root_duration_secondsHistogramTime spent calculating state root
write_duration_secondsHistogramTime spent writing trie updates to storage
account_trie_updates_written_totalCounterNumber of account trie branch nodes written
storage_trie_updates_written_totalCounterNumber of storage trie branch nodes written
hashed_accounts_written_totalCounterNumber of hashed account entries written
hashed_storages_written_totalCounterNumber of hashed storage entries written
earliest_numberGaugeEarliest block number in the proofs store
latest_numberGaugeLatest block number in the proofs store

​
Pruner (optimism_trie.pruner.*)

MetricTypeDescription
total_duration_secondsHistogramDuration of each prune run
pruned_blocksGaugeNumber of blocks pruned in the last run
account_trie_updates_writtenGaugeAccount trie entries deleted in the last prune
storage_trie_updates_writtenGaugeStorage trie entries deleted in the last prune
hashed_accounts_writtenGaugeHashed account entries deleted in the last prune
hashed_storages_writtenGaugeHashed storage entries deleted in the last prune

​
RPC (optimism_rpc.eth_api_ext.*)

MetricTypeDescription
get_proof_latencyHistogramLatency of successful eth_getProof requests
get_proof_requestsCounterTotal eth_getProof requests received
get_proof_successful_responsesCounterTotal successful eth_getProof responses
get_proof_failuresCounterTotal 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.