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

[palango]

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.

Changes

• 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 the op-reth images celo-v1.0.5 and celo-v1.0.6 forward. Both celo-reth releases pin celo-org/optimism rev 49ee2f71, and the list matches rust/op-reth/crates/rpc/src/historical.rs at that rev. 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, eth_getBlockReceipts returns null, and so do the transaction count, by-index and uncle methods.
• The warning gives two workarounds: fetch receipts one transaction at a time, and send eth_getLogs to the historical node directly. Forwarding eth_getLogs depends on op-reth: forward pre-bedrock eth_getLogs to historical endpoint ethereum-optimism/optimism#22663, which is still open, so the page does not mention it.
• 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, eth_getBlockReceipts, count, by-index and uncle-count behaviour against celo-reth backends on forno.celo.org, batching each request with web3_clientVersion to see which client answered. Forno does not allow eth_getHeaderByNumber, so I could not check the header methods and the page does not mention them.

Residual risk

• The list describes celo-v1.0.5 and celo-v1.0.6 only. Forward pre-migration eth_getBlockReceipts to the historical RPC (celo/reth-v1.0) celo-kona#338 merged into celo/reth-v1.0 on 2026-10-05, after v1.0.6 was cut, and moves the pin to celo-org/optimism rev b08a8d0a. That rev also forwards eth_getBlockReceipts, eth_getHeaderBy*, the count, by-index and raw by-index methods and the four uncle methods. No release carries it yet, so the page does not describe it. The warning needs an update together with the first release that does.
• mint broken-links --check-redirects, mint validate and scripts/check-orphans.sh pass locally with mint 4.2.746. The CI-pinned mintlify@4.2.920 would not install locally, so CI is the check on that version.
• 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.

Merge this before #2376. That PR touches the same lines in archive-node.mdx, configuration.mdx and run-node.mdx and keeps the claim that the snapshot provides the pre-L2 history, which this PR corrects. #2376 should rebase onto this wording so a conflict resolution does not restore the old sentence.

[GigaHierz]

head 0d8ed97 · 0 commits behind main (418506f), merge-tree with main clean, PR diff = 5 files under operate/operators; CI "Check for broken links" pass; local mint broken-links --check-redirects, mint validate, scripts/check-orphans.sh all pass; mint dev on :3811 served the PR text (Warning renders as a callout, not a code block, 0 console errors)

Verdict: REQUEST-CHANGES

Status of earlier findings

1. "Forwarding eth_getLogs depends on ethereum-optimism/optimism#22663, which is not merged yet" -- NOT FIXED. The sentence is still at operate/operators/archive-node.mdx:112. #22663 is still OPEN (last update 2026-10-03). It documents a pending upstream change (AGENTS.md section 4) and goes stale silently.
2. PR body "v2.3.1, the version the celo-reth release line pins" -- NOT FIXED in the body, and the picture moved (see new finding 1). Latest release celo/reth-v1.0.6 (2026-10-05) still pins celo-org/optimism rev 49ee2f71..., same as v1.0.5, and that rev's historical.rs forwards exactly the 17 listed methods (lines 240-243, 363-374). So the page is correct for the released line, but the body names an upstream version rather than the celo-reth releases the page describes.

New findings (severity-ordered)

1. MEDIUM · operate/operators/archive-node.mdx:97-110 (and the eth_getBlockReceipts claim at :110) · The warning describes the released set, but the fix for it has already merged: celo-org/celo-kona#338 merged 2026-10-05 into celo/reth-v1.0 (after v1.0.6 was cut) and moves the pin to celo-org/optimism rev b08a8d0a, whose historical.rs additionally forwards eth_getBlockReceipts, eth_getHeaderBy{Number,Hash}, eth_getBlockTransactionCountBy{Number,Hash}, eth_getTransactionByBlock{Number,Hash}AndIndex, eth_getRawTransactionByBlock{Number,Hash}AndIndex and the four uncle methods. · Scenario: the next celo-reth release (v1.0.7 or later) makes "eth_getBlockReceipts returns null" and "any other method is answered from the local database" false, and the page names no version, so an operator on the new image cannot tell which reading applies; the PR body's residual-risk note still calls #338 a draft. · Fix: scope the Warning to the images it was checked against ("celo-v1.0.5 and celo-v1.0.6"; the compose default is v1.0.5) and either update it together with the release that carries #338 or hold the merge until then; correct the body (#338 is merged, unreleased).
2. MEDIUM · operate/operators/archive-node.mdx:112 · Unresolved earlier finding 1 (pending upstream PR documented). · Scenario: #22663 merges or is closed and nothing in the repo notices; operators keep being told to bypass forwarding. · Fix: delete the sentence; keep "To read pre-L2 logs, send eth_getLogs directly to the Historical RPC Service." If the dependency matters, track it in a filed issue linked from the PR, not on the page.
3. LOW · operate/operators/archive-node.mdx:76 vs :74 · Line 74 now says the Historical RPC Service applies to every mainnet node, but line 76 still says "configure a Historical RPC Service for your archive node". · Scenario: a full-node operator reads :76 and concludes the setup is archive-only, the exact misreading this PR removes elsewhere. · Fix: "for your node".
4. LOW · operate/operators/archive-node.mdx:109-110 · "In particular" lists only eth_getLogs and eth_getBlockReceipts. Observed on forno (reth backend, pre-L2 block 31,000,000): eth_getBlockTransactionCountByNumber returns null while the Geth backend returns 0x33. It is covered by "any other method" but is the same class of silent gap (count, by-index, header and uncle methods). · Fix: add one clause naming these, or fold it into finding 1's version scoping since #338 forwards them.

Merge-order hazards

• Open PR #2376 (outside contributor) conflicts textually with this PR in archive-node.mdx (snapshot paragraph, line 67-70), configuration.mdx (OP_RETH__SNAPSHOT row, line 20) and run-node.mdx (From genesis bullet); maintenance.mdx and network-config.mdx auto-merge (git merge-tree of the two heads: 3 conflicts). Both agree OP_RETH__SNAPSHOT defaults to true (matches the compose README and the mainnet env file line 55). But #2376 keeps "it provides the pre-L2 (Celo L1) history", which is the claim this PR corrects. Merge this PR first and have #2376 rebase onto its wording (Celo L1 state at the migration); otherwise a conflict resolution can silently restore the wrong sentence. #2376 also updates network-config.mdx image tags; this PR does not touch them.
• No contradiction with merged #2351: the PR's text keeps "Support for op-geth has ended" and the empty-datadir rules; learn/celo-l1.mdx:45 and the notice page still point at the archive-node page, consistent.

Verified good

• The 17-method list matches rust/op-reth/crates/rpc/src/historical.rs at celo-org/optimism 49ee2f71 (the rev pinned by celo/reth-v1.0.5 and v1.0.6) and at b4ba5c39 (the rev in celo-kona celo/v1.1.1): 4 transaction-keyed methods, 4 block-keyed, 7 with block id in param 1, 2 in param 2. Transaction-hash methods forward when the tx is pre-bedrock or not found locally; is_pre_bedrock forwards an unknown block hash.
• Live on https://forno.celo.org, batched with web3_clientVersion: reth backend (reth/v2.2.0-1fc77b9) returns [] for eth_getLogs 1,000,000-1,000,100 while the Geth backend returns logs; null for eth_getBlockReceipts on 31,000,000 (Geth: 51 receipts); -32001 block not found: hash 0x8f29e8cb... for eth_getLogs with the pre-L2 blockHash of block 31,000,000 (Geth returns logs); range 31,056,400-31,056,976: reth first log at 31,056,517 (560 logs), Geth from 31,056,400 (16,279 logs). Migration block 31,056,500 matches.
• OP_RETH__SNAPSHOT default true: compose README ("the default", twice) and the mainnet env file (line 55, read through gh api). configuration.mdx:20 wording "(default in the shipped .env files)" is accurate. The Sepolia env file was not read directly; the README is consistent.
• Historical RPC for any NODE_TYPE: the README describes HISTORICAL_RPC_DATADIR_PATH / OP_RETH__HISTORICAL_RPC without a node-type condition. Geth-all 1.8.9 is the Celo L1 client in network-config.mdx:62, so the new sentence at archive-node.mdx:74 points at a listed version.
• Style: no frontmatter changes, no heading regressions, Warning component (no blockquote), no promotional wording, links root-relative; the new anchor /operate/operators/archive-node#configure-historical-rpc-service matches the heading at archive-node.mdx:72. run-node, configuration, maintenance, network-config all render (200, new text present).

What the PR got right

It fixes a real operator trap (pre-L2 eth_getLogs silently empty, receipts null) with an exact method list, exact failure shapes and two workarounds, checked against both source and live backends. It also corrects the OP_RETH__SNAPSHOT default and the archive-only framing in lines it was already editing, and the snapshot wording now matches what import-celo-state writes. What remains is one round: drop the pending-PR sentence, scope the list to the releases it was checked against, fix the PR body, and sequence against #2376.