> ## 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.

# 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](https://github.com/ethereum-optimism/optimism/tree/develop/rust/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.

<Warning>
  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.
</Warning>

<Info>
  Use the **historical proofs storage format v2** by setting `--proofs-history.storage-version=v2`.
</Info>

For a complete setup guide, see the tutorial on [Running op-reth with Historical Proofs](/node-operators/tutorials/reth-historical-proofs).

<Info>
  This fork inherits all standard op-reth configuration options. See the [op-reth configuration reference](/node-operators/reference/op-reth-config).
</Info>

## 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.

<Tabs>
  <Tab title="Syntax">`--proofs-history`</Tab>
</Tabs>

### proofs-history.storage-version

Storage format version for the historical proofs database.

For the v2 system, set this to `v2`.

<Tabs>
  <Tab title="Syntax">`--proofs-history.storage-version <PROOFS_HISTORY_STORAGE_VERSION>`</Tab>
  <Tab title="Recommended">`v2`</Tab>
</Tabs>

### proofs-history.storage-path

The path to the storage DB for proofs history.

<Tabs>
  <Tab title="Syntax">`--proofs-history.storage-path <PROOFS_HISTORY_STORAGE_PATH>`</Tab>
</Tabs>

### 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`).

<Tabs>
  <Tab title="Syntax">`--proofs-history.window <PROOFS_HISTORY_WINDOW>`</Tab>
  <Tab title="Default">`1296000`</Tab>
</Tabs>

### 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.

<Tabs>
  <Tab title="Syntax">`--proofs-history.verification-interval <PROOFS_HISTORY_VERIFICATION_INTERVAL>`</Tab>
  <Tab title="Default">`0`</Tab>
</Tabs>

## 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.

```bash theme={null}
op-reth proofs init --chain <CHAIN> --datadir <DATA_DIR> --proofs-history.storage-path <PROOFS_HISTORY_STORAGE_PATH> --proofs-history.storage-version=v2
```

<Info>
  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.
</Info>

### prune

Prune old proof history to reclaim space.

```bash theme={null}
op-reth proofs prune --chain <CHAIN> --datadir <DATA_DIR> --proofs-history.storage-path <PROOFS_HISTORY_STORAGE_PATH> --proofs-history.window <PROOFS_HISTORY_WINDOW>
```

<Info>
  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](/node-operators/tutorials/reth-historical-proofs#manual-prune) for details.
</Info>

### unwind

Unwind the proofs storage to a specific block

```bash theme={null}
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`.