Skip to content

op-service, op-devstack: review the eth client APIs for L2 reads #24098

Open

Description

@sebastianst

Part of #20257. A cleanup that does not block the go.mod flip (#20266) and can be done before or after it.

The test migration (#20265) moved L2 reads onto op-service/sources call site by call site. That was the right order, but it left seams in the client APIs that every new L2 read has to work around. This issue collects them for one review of the client surface: op-service/apis, op-service/sources, op-service/txplan and the op-devstack DSL on top.

Seams

1. The L2 body gate is tied to a Go type, not to the endpoint. sources.L2Client shadows HeaderAndTxsByHash and InfoAndTxsBy{Hash,Number,Label} of the embedded EthClient and returns ErrSyntheticTxInBody for a body that holds a deposit or post-exec tx (#23863). A plain sources.EthClient dialled at an L2 endpoint is not gated; op-interop-mon, check-karst and interopsmoke hold such clients. None calls the gated accessors today. The shadowing is also by hand: a whole-body accessor added to EthClient later is not gated until someone adds a matching shadow.

2. Whole-body and partitioned accessors live on different interfaces. apis.EthClient carries InfoAndTxsBy*, which is only correct on L1. The partitioned accessors (InfoAndUserTxsBy*, InfoAndDepositsBy*, InfoAndFirstDepositBy*) are in apis.EthL2BlockTxs, which only the extended and L2 client interfaces embed. Code that holds a generic client must downcast to reach them. The partitioned set has no ByLabel variants, and no accessor returns only a block's tx hashes, so "is this tx in that block" reads full bodies.

3. A DSL EOA does not know it is on an L2. It holds a generic ELNode. OperatorFee.ValidateTransactionFees asserts from.el.stackEL().(stack.L2ELNode) to reach the L2 client (dsl/operator_fee.go, added in #23863), while dsl/fjord_fees.go takes it from its L2Network.

4. txplan drops the OP receipt fields. PlannedTx.Included is a plan.Lazy[*types.Receipt]. Its fetchers already receive an *optypes.Receipt from the ReceiptGetter and return &receipt.Receipt, which discards L1Fee, OperatorFeeScalar and the other L2-only fields. A helper that needs them fetches the same receipt a second time through sources. After #23863 this happens in dsl/operator_fee.go, dsl/fjord_fees.go, dsl/ecotone_fees.go, dsl/bridge.go and tests/fjord/check_scripts_test.go.

5. No accessor returns a response as the node sent it. op-sync-tester serves eth_getBlockByNumber, eth_getBlockByHash and eth_getBlockReceipts by relaying the read-only EL's JSON, so that no OP Stack field is lost in a decode and re-encode. sources.EthClient only returns decoded values, so ELReader issues these calls by method name on the bare RPC client, next to the typed client it holds for its own reads (#24185). The relayed calls bypass that client's cache and its hash checks.

6. The caches sit above the decode, per client and per return type. sources.EthClient holds separate caches for receipts, transactions, headers, payloads and block refs, and L2Client adds two more. The same block read as a header, as info plus transactions and as a payload is fetched once per shape. Two clients on the same endpoint in one process share nothing, and a relay that needs the node's JSON (seam 5) cannot use any of these caches. A cache at the client.RPC layer, keyed by method and params and holding the response JSON, would serve all three; recordingRPC is a wrapper of that shape.

Work

Review the surface as a whole and decide the target shape before changing call sites. Questions to settle:

  • Should L1 and L2 clients be distinct types with distinct interfaces, so that a whole-body accessor does not exist on an L2 client and the runtime gate is unnecessary?
  • Which partitioned accessors are missing (ByLabel, tx hashes only, a paired user-tx/receipt read), and which existing ones have no caller?
  • How does a DSL helper get the L2 client: through the network, or through an EOA that knows its chain kind?
  • Does a relay like op-sync-tester's need a raw-response accessor in op-service/sources, or should it keep calling the RPC by method name?
  • Should responses be cached at the RPC layer, shared by the typed accessors, relays and all clients of an endpoint? If so:
    • Only a request keyed by a block or transaction hash has an immutable response.
    • A hit on cached JSON is decoded and hash-checked again; does a decoded cache stay on top, or does the raw cache replace the typed ones?
    • eth_getBlockByHash with and without full transactions are different responses; a header read would have to be served from a cached full body to share its entry.

Concrete items that hold whatever the answers are:

  • Make PlannedTx.Included a plan.Lazy[*optypes.Receipt] and delete the second receipt fetches listed in 4. L1 plans keep getting receipts whose OP fields are nil through FromGethReceipts.
  • Drop the type assertion in dsl/operator_fee.go.

🤖 Co-created with Claude Fable 5.2

Activity

  1. changed the title [-]op-service/txplan, op-devstack: keep OP receipt fields on included txs and drop the DSL's receipt re-fetches[/-] [+]op-service, op-devstack: review the eth client APIs for L2 reads[/+] on Nov 12, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions