Skip to content

docs(operators): document which pre-L2 requests op-reth forwards to the historical RPC - #2345

Draft
palango wants to merge 2 commits into
mainfrom
palango/pre-l2-history-docs
Draft

palango wants to merge 2 commits into
mainfrom
palango/pre-l2-history-docs

Conversation

@palango

@palango palango commented Sep 30, 2026

Copy link
Copy Markdown
Contributor

The operator docs say the mainnet snapshot provides the pre-L2 history, and imply that op-reth serves all of it. Neither is true. The snapshot holds only the Celo L1 state at the migration, and op-reth forwards only some pre-L2 requests to the Historical RPC Service, so pre-L2 eth_getLogs quietly returns no logs and eth_getBlockReceipts returns null. This corrects the snapshot wording, adds a warning to the archive node page that lists what is forwarded and what is not, and fixes the documented OP_RETH__SNAPSHOT default and some archive-only wording that contradicted the new text.

The hole, and the fix

  • run-node.mdx, archive-node.mdx, configuration.mdx and network-config.mdx said the mainnet snapshot provides the pre-L2 history. import-celo-state writes pre-migration headers without bodies or receipts, so the snapshot provides only the L1 state at block 31,056,500.
  • A new <Warning> under "Configure Historical RPC Service" lists the 17 methods that op-reth v2.3.1 forwards (rust/op-reth/crates/rpc/src/historical.rs), which is the version the celo-reth release line pins. Everything else is answered locally. For eth_getLogs that means [] for a pre-L2 range, only the L2 logs for a range across the migration, and "block not found" for a pre-L2 blockHash. The filter methods are not forwarded, and eth_getBlockReceipts returns null.
  • The warning gives two workarounds, fetching receipts one transaction at a time and sending eth_getLogs to the historical node directly, and names op-reth: forward pre-bedrock eth_getLogs to historical endpoint ethereum-optimism/optimism#22663 as the upstream change that forwarding eth_getLogs depends on.
  • OP_RETH__SNAPSHOT was documented with default false. The compose repo ships true in mainnet.env and celo-sepolia.env, and its README calls true the default. The table and the Sepolia instructions now match.
  • configuration.mdx and maintenance.mdx described the Historical RPC Service as an archive-node feature. The compose start script passes --rollup.historicalrpc for any NODE_TYPE, and op-reth installs the forwarding layer regardless of prune mode.

I checked the forwarded list against the code, and the eth_getLogs and eth_getBlockReceipts behaviour against celo-reth backends on forno.celo.org, batching each request with web3_clientVersion to see which client answered.

What this does NOT do / residual risk

  • The list describes the current release. The draft Forward pre-migration eth_getBlockReceipts to the historical RPC (celo/reth-v1.0) celo-kona#338 would add eth_getBlockReceipts, eth_getHeaderBy*, and the by-index and count methods to the forwarded set. If it lands in a release, the warning needs an update.
  • I could not render the pages locally because the pinned mintlify@4.2.920 would not install. CI validation is the first render check.
  • An existing <Warning> further down archive-node.mdx indents its body by 8 spaces and may render as a code block. This PR leaves it alone.

Judgement calls

The OP_RETH__SNAPSHOT default and the archive-only wording were wrong before this change. I fixed them because they sit in lines this PR edits and contradicted the new text. Happy to split them out.

Issues

Refs celo-org/celo-blockchain-planning#1464

Stacking / conflicts

Branched off main, independent of my other open PRs.

Pre-L2 eth_getLogs and eth_getBlockReceipts are answered locally and
return empty results; the forwarded set is the one in op-reth v2.3.1.
Also correct the OP_RETH__SNAPSHOT default and drop the archive-only
wording for the Historical RPC Service.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant