Conversation
There was a problem hiding this comment.
Pull request overview
This PR adds comprehensive documentation for a bounded history sidecar architecture that enables reliable eth_getProof queries for historical state on Optimism rollups. The documentation explains the motivation, architecture, and usage of the new system that addresses Out-Of-Memory issues when serving historical proofs.
Key changes:
- Complete documentation of the bounded history sidecar architecture and its core mechanisms
- Detailed usage instructions including initialization, node operation, and management commands
- Performance benchmarks and metrics dashboard information
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| Avg Latency | 15 ms | ||
| Throughput | ~5,000 req/sec | ||
|
|
||
| Benchmark Configuration |
There was a problem hiding this comment.
The heading "Benchmark Configuration" should be formatted as a proper markdown heading (e.g., "### Benchmark Configuration") to maintain consistency with the document's heading structure and improve navigation.
| Benchmark Configuration | |
| ### Benchmark Configuration |
| As described in Reth issue [#18070](https://github.com/paradigmxyz/reth/issues/18070), many applications on Optimism and other rollups (e.g. Base infrastructure, ENS, fault-proof systems) depend on fast and reliable `eth_getProof` queries within a bounded challenge window (typically 7 days). At present, the lack of reliable recent-state proof support is a blocker for broader Reth adoption in these environments. | ||
|
|
||
| ... | ||
| The core issue lies in Reth's architecture for historical state calculation. To serve `eth_getProof` for a historical block, Reth must perform an **in-memory revert**, applying state diffs backwards from the chain tip. While efficient for recent blocks, reverting state for a block 7 days ago requires loading thousands of changesets into Memory. This operation is computationally expensive and often causes the node to crash due to **Out-Of-Memory (OOM)** errors, effectively making deep historical proofs impossible on a standard node. |
There was a problem hiding this comment.
The phrase "loading thousands of changesets into Memory" has an incorrectly capitalized word. "Memory" should be lowercase "memory" as it refers to the general concept of computer memory, not a proper noun or specific entity.
| The core issue lies in Reth's architecture for historical state calculation. To serve `eth_getProof` for a historical block, Reth must perform an **in-memory revert**, applying state diffs backwards from the chain tip. While efficient for recent blocks, reverting state for a block 7 days ago requires loading thousands of changesets into Memory. This operation is computationally expensive and often causes the node to crash due to **Out-Of-Memory (OOM)** errors, effectively making deep historical proofs impossible on a standard node. | |
| The core issue lies in Reth's architecture for historical state calculation. To serve `eth_getProof` for a historical block, Reth must perform an **in-memory revert**, applying state diffs backwards from the chain tip. While efficient for recent blocks, reverting state for a block 7 days ago requires loading thousands of changesets into memory. This operation is computationally expensive and often causes the node to crash due to **Out-Of-Memory (OOM)** errors, effectively making deep historical proofs impossible on a standard node. |
| - Versioned Storage: Implements MdbxProofsStorage, a specialized database schema optimized for time-series trie node retrieval. | ||
| - Proof Generation: Replaces the standard "revert-based" proof logic with a direct "lookup-based" approach. | ||
| - Pruning Logic: Implements the smart retention algorithm that safely deletes old history |
There was a problem hiding this comment.
The list items under "reth-optimism-trie" are missing proper formatting. These lines should be formatted as a bullet list with dashes (-) or asterisks (*) at the beginning of each line to maintain consistency with the markdown list format used elsewhere in the document.
| - Versioned Storage: Implements MdbxProofsStorage, a specialized database schema optimized for time-series trie node retrieval. | |
| - Proof Generation: Replaces the standard "revert-based" proof logic with a direct "lookup-based" approach. | |
| - Pruning Logic: Implements the smart retention algorithm that safely deletes old history | |
| - **Versioned Storage:** Implements MdbxProofsStorage, a specialized database schema optimized for time-series trie node retrieval. | |
| - **Proof Generation:** Replaces the standard "revert-based" proof logic with a direct "lookup-based" approach. | |
| - **Pruning Logic:** Implements the smart retention algorithm that safely deletes old history. |
| --proofs-history.prune-interval=15s | ||
| ``` | ||
|
|
||
| Configuration Flags |
There was a problem hiding this comment.
The heading "Configuration Flags" should be formatted as a proper markdown heading (e.g., "### Configuration Flags" or "#### Configuration Flags") to maintain consistency with the document's heading structure and improve navigation.
| Configuration Flags | |
| #### Configuration Flags |
| --proofs-history.prune-batch-size=10000 | ||
| ``` | ||
|
|
||
| `unwind-op-proofs` |
There was a problem hiding this comment.
The command name "unwind-op-proofs" should be formatted with backticks (i.e., unwind-op-proofs) to maintain consistency with markdown formatting standards for inline code and command names.
| - Ingestion Pipeline: Subscribes to the node's canonical state notifications to capture ExecutionOutcomes in real-time. | ||
| - Diff Extraction: Isolates the specific TrieUpdates (branch nodes) and HashedPostState (leaf values) changed in each block. | ||
| - Persistence: Writes these versioned updates to the sidecar MDBX database without blocking the main datastore. | ||
| - Lifecycle Management: Orchestrates the pruning process, ensuring the sidecar storage remains bounded by the configured window. |
There was a problem hiding this comment.
The list items under "reth-optimism-exex" are missing proper formatting. These lines should be formatted as a bullet list with dashes (-) or asterisks (*) at the beginning of each line to maintain consistency with the markdown list format used elsewhere in the document (e.g., lines 20-22).
| - Ingestion Pipeline: Subscribes to the node's canonical state notifications to capture ExecutionOutcomes in real-time. | |
| - Diff Extraction: Isolates the specific TrieUpdates (branch nodes) and HashedPostState (leaf values) changed in each block. | |
| - Persistence: Writes these versioned updates to the sidecar MDBX database without blocking the main datastore. | |
| - Lifecycle Management: Orchestrates the pruning process, ensuring the sidecar storage remains bounded by the configured window. | |
| * **Ingestion Pipeline:** Subscribes to the node's canonical state notifications to capture ExecutionOutcomes in real-time. | |
| * **Diff Extraction:** Isolates the specific TrieUpdates (branch nodes) and HashedPostState (leaf values) changed in each block. | |
| * **Persistence:** Writes these versioned updates to the sidecar MDBX database without blocking the main datastore. | |
| * **Lifecycle Management:** Orchestrates the pruning process, ensuring the sidecar storage remains bounded by the configured window. |
|
|
||
| - Versioned Storage: Implements MdbxProofsStorage, a specialized database schema optimized for time-series trie node retrieval. | ||
| - Proof Generation: Replaces the standard "revert-based" proof logic with a direct "lookup-based" approach. | ||
| - Pruning Logic: Implements the smart retention algorithm that safely deletes old history |
There was a problem hiding this comment.
This line appears to be incomplete. The sentence "Implements the smart retention algorithm that safely deletes old history" ends abruptly without completing the thought. Consider adding a period at the end or completing the sentence with additional context about what happens after deletion.
| - Pruning Logic: Implements the smart retention algorithm that safely deletes old history | |
| - Pruning Logic: Implements the smart retention algorithm that safely deletes old history while preserving the configured proof window. |
|
|
||
| ### 2. Running the Node (Syncing) | ||
|
|
||
| Once initialized, start the node with the --proofs-history flags to enable the sidecar service. |
There was a problem hiding this comment.
The sentence "Once initialized, start the node with the --proofs-history flags to enable the sidecar service" should use proper markdown formatting. The flag "--proofs-history" should be wrapped in backticks to maintain consistency with other command-line flags shown in the document.
| Once initialized, start the node with the --proofs-history flags to enable the sidecar service. | |
| Once initialized, start the node with the `--proofs-history` flags to enable the sidecar service. |
|
|
||
| We provide custom CLI commands to manage the proof history manually. | ||
|
|
||
| `prune-op-proofs` |
There was a problem hiding this comment.
The command name "prune-op-proofs" should be formatted with backticks (i.e., prune-op-proofs) to maintain consistency with markdown formatting standards for inline code and command names.
| - Syncing speed | ||
| - Sidecar storage size. | ||
| - Pruning performance. | ||
| - Proof generation latency. |
There was a problem hiding this comment.
The list items describing what the dashboard monitors are inconsistently formatted. The first item uses "- " (dash with three spaces) while the remaining items use "- " or "- ". All list items should use consistent spacing for proper markdown rendering.
| - Syncing speed | |
| - Sidecar storage size. | |
| - Pruning performance. | |
| - Proof generation latency. | |
| - Syncing speed | |
| - Sidecar storage size. | |
| - Pruning performance. | |
| - Proof generation latency. |
1 participant
No description provided.