Skip to content

op-core, op-alloy: align the RPC JSON of deposit transactions and receipts with the specs #24223

Open

Description

@sebastianst

The RPC JSON of OP deposit transactions and of receipts differs between the Go codec in op-core/types and what the Rust stack (op-alloy rpc-types, served by op-reth) encodes. These differences are in RPC output only; consensus encodings and hashes agree. Because the Go services already run against op-reth, decoding works in both directions for real chain data, with the exceptions marked below. op-core/types mirrors op-geth's core/types JSON codec. op-geth's own RPC server did not serve that codec's output: it built its responses in internal/ethapi, and in several rows below op-reth matches that server rather than the codec. This issue lists each difference against the specs so that each side can be fixed later.

"ran" means checked by a throwaway test; "read" means read from the code only.

Go codec: deposit txJSON, MarshalJSON, UnmarshalJSON; Receipt.
Rust: TxDeposit serde, serde_deposit_tx_rpc, RPC Transaction and its serde helper; OpTransactionReceipt, L1BlockInfo, deposit receipt serde; op-reth receipt builder.

Spec references: deposited tx type, deposit receipt, Isthmus receipts, Jovian receipts, Jovian DA footprint, SDM receipt extension.

Deposit transaction (eth_getTransactionByHash, block transactions)

Field Go (op-core/types) Rust (op-alloy) Spec
nonce Always null; the effective deposit nonce is not part of the type. The decoder accepts and ignores a number (ran). The deposit nonce from the receipt; omitted when unknown, for example before Regolith (read). Accepts Go's null (ran). deposited tx type: API responses include nonce: 0 before Regolith, the receipt's depositNonce from Regolith. Go deviates; Rust deviates before Regolith.
v, r, s null "0x0" (ran) deposited tx type: zeroed v, r, s. Go deviates. Go's decoder accepts zeros (read); Rust's accepts null (ran).
yParity absent "0x0" (ran) Silent. Go's decoder ignores it (read).
gasPrice null "0x0" on mined deposits, the RPC effective gas price (read) Silent. op-geth's RPC server served "0x0". Go's decoder accepts zero (read).
maxFeePerGas, maxPriorityFeePerGas null omitted (ran) Silent. Each side accepts the other's form (ran/read).
to on contract creation null omitted (ran) Silent. Each side accepts the other's form (ran/read).
isSystemTx always present, false or true omitted when false (ran) deposited tx type: "API responses contain these as additional fields", which reads as always present. op-geth's RPC server also omitted false. Both decoders treat a missing field as false (ran).
mint omitted when unset; zero mint is written as "0x0" always present (ran) Same sentence as isSystemTx: present. Rust decodes a missing mint as zero (ran); Go decodes "0x0" (read).
mint range uint256 u128; a mint above 2^128-1 fails to decode (ran) deposited tx type: uint256 mint. Not reachable on a real chain: mint is the portal's msg.value.
blockHash, blockNumber, transactionIndex, blockTimestamp, depositReceiptVersion not produced; the codec encodes the transaction only, and its decoder ignores them (read) present on mined transactions (read) Silent (depositReceiptVersion on the transaction object is not specified). op-geth's RPC server served them.

Post-exec (0x7D) transaction JSON is fixed separately in #24221: Go wrote null where the Lagoon spec says the fields are omitted.

Receipt (eth_getTransactionReceipt), deposit and user receipts

Field Go (op-core/types) Rust (op-alloy) Spec
from, to absent: go-ethereum's types.Receipt has no such fields; Go's decoder ignores them (read) present; Rust's decoder rejects a receipt without from (ran) OP specs silent; standard Ethereum receipt fields.
root "0x" on every post-Byzantium receipt omitted (ran) Silent. Rust accepts Go's "0x" next to status (ran); Go accepts it missing (read).
contractAddress without creation zero address null (read) Silent. op-geth's RPC server served null. Rust decodes Go's zero address as a real address (ran).
depositNonce, depositReceiptVersion written whenever set, on any receipt type written only on deposit (0x7e) receipts; dropped on other types (ran) deposit receipt: depositNonce included from Regolith. The spec names the version field depositNonceVersion; both codecs use depositReceiptVersion. Real deposit receipts agree.
l1GasPrice, l1GasUsed, l1Fee, l1BaseFeeScalar, l1BlobBaseFee, l1BlobBaseFeeScalar names and hex quantities agree (ran) same; u128 instead of uint256 (read) Silent: the fee formulas name the parameters, but no receipt field is specified.
L1 fee fields on deposit receipts carries whatever the server sends; op-geth left them unset on deposits (read) op-reth fills them on every receipt, deposits included: l1Fee is zero, l1GasUsed is computed from the deposit's bytes (read) Silent.
l1FeeScalar decimal string from big.Float decimal string from f64 (read) Silent. Both give "0.5" (ran); whether they format small or exponent values the same way is not checked.
operatorFeeScalar, operatorFeeConstant codec agrees (ran) op-reth includes them only if one is non-zero (read) Isthmus receipts: present iff at least one is non-zero. Matches op-geth.
daFootprintGasScalar codec agrees (ran) op-reth also sets it on deposit receipts (read) Jovian receipts: the block's scalar. Silent on deposits.
blobGasUsed omitempty: a zero footprint is omitted (read) present on every receipt from Jovian (read). On deposit receipts op-reth reports a non-zero DA footprint (builder, encoded_tx_da_footprint skips only post-exec) (read) Jovian receipts: the transaction's DA footprint; Jovian DA footprint skips deposits, so a deposit's footprint is zero. op-geth left it unset on deposits. Tracked in #24222.
opGasRefund no such field; dropped on decode (read) written when set, omitted otherwise (read) SDM receipt extension: Quantity or null. Go loses the field; Rust omits it where the spec says null.

Proposed direction

  • Deposit nonce, v/r/s, mint: change Go to match the spec (zeroed signature, mint always present, the deposit nonce where the caller knows it). Rust: report nonce 0 before Regolith.
  • Deposit isSystemTx: decide. Either fix the spec wording to "omitted when false" (op-geth's RPC server and Rust) or make both always emit it.
  • Deposit gasPrice, yParity, unset fee fields, to on creation: decide, and specify the shape in deposits.md.
  • Receipt from/to: change Go to carry them, so Go can serve receipts that Rust decodes.
  • Receipt root, contractAddress: change Go to omit root and to write null for no contract.
  • depositNonceVersion in deposits.md: fix the spec to name depositReceiptVersion.
  • blobGasUsed and the L1 fee fields on deposit receipts: op-reth: deposit receipts report a non-zero blobGasUsed from Jovian #24222 fixes op-reth so a deposit's blobGasUsed is zero; decide whether deposits report L1 fee fields at all.
  • blobGasUsed of zero: change Go to emit it instead of omitting it.
  • opGasRefund: add it to Go; decide null vs omitted with the spec.
  • l1FeeScalar formatting: check that both sides format small and exponent values the same way, then decide.

🤖 Co-created with Claude Opus 5.5 and Claude Fable 5.2

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