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.
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
Options for configuring the historical proof store.proofs-history
If true, enable the historical proof store and keep it updated as new blocks are processed.- Syntax
--proofs-historyproofs-history.storage-path
The path to the storage DB for proofs history.- Syntax
--proofs-history.storage-path <PROOFS_HISTORY_STORAGE_PATH>proofs-history.storage-version
Deprecated. v2 is the only storage format, sov2 is accepted as a no-op and any other value is rejected. The flag is kept so existing deployments that pass v2 keep working.
- Syntax
- Accepted value
--proofs-history.storage-version <PROOFS_HISTORY_STORAGE_VERSION>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
- Default
--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).
- Syntax
- Default
--proofs-history.verification-interval <PROOFS_HISTORY_VERIFICATION_INTERVAL>Lifecycle and management commands
Operators usually follow this lifecycle:- Run
op-reth proofs initonce to initialize the proofs DB at the current tip. - Start
op-rethwith--proofs-history. - Let the store fill proofs data forward from the initialization point.
- Let automatic pruning enforce the configured retention window.
- Use manual
pruneorunwindonly for recovery/maintenance scenarios.
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 blockRPC Endpoints
debug_proofsSyncStatus
Returns the current sync status of the proofs store.earliest and latest define the currently available historical-proof interval.
Once latest tracks chain tip, eth_getProof calls for blocks within [earliest, latest] are served from the versioned proofs store.
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 initestablishes 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.
Upgrading from storage version flags
Releases after op-reth v2.6.x only support the v2 storage format. They accept--proofs-history.storage-version=v2 as a no-op and reject any other value. How you upgrade depends on how you ran the previous release:
- You never set
--proofs-history.storage-version, or set it tov1: your proofs database uses the removed v1 format, and op-reth refuses to open it. Stop the node, remove--proofs-history.storage-version=v1if you set it, delete the proofs database directory (or point--proofs-history.storage-pathat a fresh path), runop-reth proofs init, and restart with--proofs-history. The new database only serves proofs from the initialization point forward, so plan for the retention window to refill. - You set
--proofs-history.storage-version=v2: no change is needed, and your existing proofs database is compatible. The flag is now a no-op, so you can remove it fromop-reth nodeand everyop-reth proofscommand.
Metrics
When themetrics 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.