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

operate/operators/archive-node.mdx

@@ -67,12 +67,13 @@ Ensure any datadir you supply is not in use by a running node before proceeding.
     OP_RETH__SNAPSHOT=true
     ```
 
-    On first start this downloads the snapshot matching your `NODE_TYPE` (here, the archive snapshot) and continues from there. **On mainnet a snapshot is required** — it provides the pre-L2 (Celo L1) history. On **Celo Sepolia**, which has no pre-L2 history, you can instead set `OP_RETH__SNAPSHOT=false` and execute every block from genesis. Either way, `NODE_TYPE=archive` is what keeps the full historical state available, and `DATADIR_PATH` must be empty on first start — a datadir written by `op-geth` cannot be reused.
+    On first start this downloads the snapshot matching your `NODE_TYPE` (here, the archive snapshot) and continues from there. **On mainnet a snapshot is required** — it provides the Celo L1 state at the L2 migration. Requests for pre-L2 blocks, transactions and state go to the Historical RPC Service configured below, with the gaps listed there. On **Celo Sepolia**, which has no pre-L2 history, you can instead set `OP_RETH__SNAPSHOT=false` and execute every block from genesis. Either way, `NODE_TYPE=archive` is what keeps the full historical state available, and `DATADIR_PATH` must be empty on first start — a datadir written by `op-geth` cannot be reused.
 
     #### Configure Historical RPC Service
 
-    To handle RPC requests for pre-hardfork state and execution, an L2 archive node proxies to a legacy archive node or "Historical RPC Service".
-    There are two ways to configure a Historical RPC Service for your archive node:
+    To handle RPC requests for pre-hardfork blocks, transactions, state and execution, an L2 node proxies to a legacy archive node or "Historical RPC Service". This applies to every mainnet node that serves such requests, not only to archive nodes. Run the legacy archive node with the Celo L1 client version listed in [Network config](/operate/operators/network-config).
+
+    There are two ways to configure a Historical RPC Service for your node:
 
     1. Supply a pre-hardfork archive datadir and let [celo-l2-node-docker-compose](https://github.com/celo-org/celo-l2-node-docker-compose) start a legacy archive node. To do this configure `.env` as follows:
 
@@ -92,6 +93,26 @@ Ensure any datadir you supply is not in use by a running node before proceeding.
 
         If you choose to run your own legacy archive node, you should do so with different flags than before the hardfork, as the node will no longer be syncing blocks or communicating with other nodes. To see how we recommend re-starting a legacy archive node as a Historical RPC Service, see [this script](https://github.com/celo-org/celo-l2-node-docker-compose/blob/30ee2c4ec2dacaff10aaba52e59969053c652f05/scripts/start-historical-rpc-node.sh#L19).
 
+    <Warning>
+    **Not every pre-L2 request is forwarded**
+
+    The `op-reth` images `celo-v1.0.5` and `celo-v1.0.6` forward these methods when they target a block before the L2 migration (mainnet block 31,056,500). They also forward the methods that take a block or transaction hash whenever they cannot find that hash locally, for example because it was pruned.
+
+    - `eth_getBlockByNumber`, `eth_getBlockByHash`
+    - `eth_getTransactionByHash`, `eth_getRawTransactionByHash`, `eth_getTransactionReceipt`
+    - `eth_getBalance`, `eth_getCode`, `eth_getTransactionCount`, `eth_getStorageAt`, `eth_getProof`
+    - `eth_call`, `eth_estimateGas`, `eth_createAccessList`
+    - `debug_traceTransaction`, `debug_traceBlockByNumber`, `debug_traceBlockByHash`, `debug_traceCall`
+
+    Any other method is answered from the local database, which holds no pre-L2 blocks or receipts. In particular:
+
+    - `eth_getLogs` with a block range returns no logs from pre-L2 blocks, and it does not return an error. A range that crosses the migration block returns only the logs from L2 blocks. With a pre-L2 `blockHash` it returns a "block not found" error. The filter methods (`eth_newFilter`, `eth_getFilterLogs`, `eth_getFilterChanges`) are not forwarded either.
+    - `eth_getBlockReceipts` returns `null` for pre-L2 blocks. Fetch each receipt with `eth_getTransactionReceipt` instead.
+    - The transaction count, by-index and uncle methods, such as `eth_getBlockTransactionCountByNumber`, `eth_getTransactionByBlockNumberAndIndex` and `eth_getUncleCountByBlockNumber`, return `null` for pre-L2 blocks.
+
+    To read pre-L2 logs, send `eth_getLogs` directly to the Historical RPC Service.
+    </Warning>
+
     #### Configure P2P for external network access
 
     <Warning>

operate/operators/configuration.mdx

@@ -17,7 +17,7 @@ The variables below configure `op-reth`, Celo's supported execution client. Supp
 | Variable | Values | Description |
 |---|---|---|
 | `NODE_TYPE` | `minimal`, `full` (default), `archive` | Sets the prune profile and the snapshot tier downloaded. A `minimal` node prunes transaction lookups fully and keeps only the most recent receipts, so it serves latest-state RPC on the smallest disk but little history. A `full` node stores historical state only for recent blocks. An `archive` node stores historical state for the entire chain (roughly 10x the storage). All three execute every block. |
-| `OP_RETH__SNAPSHOT` | `true` (default in the shipped `.env` files), `false` | When `true`, an empty datadir is bootstrapped from a published snapshot (`snapshots.celo.org`). Required on mainnet, which needs the pre-L2 history; optional on Celo Sepolia, which can sync from genesis. Ignored once the datadir holds data. |
+| `OP_RETH__SNAPSHOT` | `true` (default in the shipped `.env` files), `false` | When `true`, an empty datadir is bootstrapped from a published snapshot (`snapshots.celo.org`). Required on mainnet, which needs the Celo L1 state at the L2 migration (pre-L2 blocks and receipts come from the historical RPC, not the snapshot); optional on Celo Sepolia, which can sync from genesis. Ignored once the datadir holds data. |
 
 `op-reth` syncs by executing every block. A new node starts from an empty datadir (see [Run a node with Docker](/operate/operators/run-node)); datadirs written by `op-geth` cannot be reused. For archive nodes, see [Running an archive node](/operate/operators/archive-node).
 
@@ -32,7 +32,7 @@ The variables below configure `op-reth`, Celo's supported execution client. Supp
 
 ## Historical state (pre-hardfork)
 
-An L2 archive node serves pre-hardfork state by proxying to a legacy Celo L1 archive node.
+Any L2 node serves pre-hardfork state by proxying to a legacy Celo L1 archive node.
 
 | Variable | Description |
 |---|---|

operate/operators/maintenance.mdx

@@ -53,4 +53,4 @@ cp -a ./envs/<network>/datadir /path/to/backup
 
 ## Re-syncing
 
-If you need to rebuild a node, start from an empty `DATADIR_PATH` — a datadir written by op-geth cannot be reused. Bootstrap from a published snapshot (`OP_RETH__SNAPSHOT=true`, required on mainnet) or, on Celo Sepolia, execute every block from genesis; see [Run a node with Docker](/operate/operators/run-node). Pre-L2 historical state for archive nodes is served separately — see [Running an archive node](/operate/operators/archive-node).
+If you need to rebuild a node, start from an empty `DATADIR_PATH` — a datadir written by op-geth cannot be reused. Bootstrap from a published snapshot (`OP_RETH__SNAPSHOT=true`, required on mainnet) or, on Celo Sepolia, execute every block from genesis; see [Run a node with Docker](/operate/operators/run-node). Pre-L2 historical state is served separately, by a Historical RPC Service that every mainnet node needs — see [Configure Historical RPC Service](/operate/operators/archive-node#configure-historical-rpc-service).

operate/operators/network-config.mdx

@@ -14,7 +14,7 @@ The recommended [celo-l2-node-docker-compose](https://github.com/celo-org/celo-l
 
 ## Mainnet
 
-- op-reth snapshots — published at [`snapshots.celo.org`](https://snapshots.celo.org); a mainnet node must bootstrap from one (`OP_RETH__SNAPSHOT=true`) for the pre-L2 history (see [Run a node](/operate/operators/run-node))
+- op-reth snapshots — published at [`snapshots.celo.org`](https://snapshots.celo.org); a mainnet node must bootstrap from one (`OP_RETH__SNAPSHOT=true`) for the Celo L1 state at the L2 migration (see [Run a node](/operate/operators/run-node))
 - [Rollup deploy config](https://storage.googleapis.com/cel2-rollup-files/celo/config.json)
 - [L1 contract addresses](https://storage.googleapis.com/cel2-rollup-files/celo/deployment-l1.json)
 - [L2 allocs](https://storage.googleapis.com/cel2-rollup-files/celo/l2-allocs.json)

operate/operators/run-node.mdx

@@ -74,7 +74,7 @@ Follow these steps to run a full node. If you would like to run an archive node,
         OP_RETH__SNAPSHOT=true
         ```
 
-        **On mainnet a snapshot is required** — it provides the pre-L2 (Celo L1) history, which `op-reth` cannot reproduce by executing blocks.
+        **On mainnet a snapshot is required** — it provides the Celo L1 state at the L2 migration, which `op-reth` cannot reproduce by executing blocks. The snapshot does not contain the pre-L2 blocks, transactions or receipts. `op-reth` serves most requests for them by proxying to a Historical RPC Service, but pre-L2 `eth_getLogs` returns no logs; see [Configure Historical RPC Service](/operate/operators/archive-node#configure-historical-rpc-service).
 
     - **From genesis.** On **Celo Sepolia**, which has no pre-L2 history, you can set `OP_RETH__SNAPSHOT=false` (the shipped `.env` files set it to `true`) and execute every block from genesis. This needs no external data but takes considerably longer to reach the chain tip.