The monorepo is a single Go module that depends on upstream go-ethereum, not on the op-geth fork.
go-ethereum knows nothing of the OP Stack: it has no deposit (0x7E) or post-exec (0x7D)
transaction, no OP receipt fields, no OP hardforks in its params.ChainConfig and no OP state
transition. This doc says where the OP Stack code lives instead, and which go-ethereum uses are
safe. Tracking issue of the migration: #20257.
Compiling is not enough. go-ethereum code compiles against OP data and then behaves wrongly
or fails at runtime. Ask of every go-ethereum use: does it execute an OP state transition, or
decode OP transactions? If it does, it belongs in op-reth (Rust) or op-core/*. If it does
not — plain-EVM execution on L1, storage or trie work, header and RLP encoding — go-ethereum is
right.
| Package | Content |
|---|---|
op-core/types |
DepositTx, PostExecTx (binary and RPC JSON codecs), Receipt (go-ethereum's receipt plus the OP fields), Receipts (receipts-root encoding) |
op-core/fees |
L1 cost (Bedrock through Fjord), operator fee (Isthmus, Jovian), DA footprint |
op-core/params |
OptimismConfig, the standalone ChainConfig with the OP fork schedule, GethChainConfig() |
op-core/genesis |
the L2 Genesis and its JSON encoding, ToBlock() |
op-core/eip1559 |
Holocene/Jovian extraData helpers |
op-core/superchain, op-core/superchain/bundle |
registry types and loader; the embedded registry |
op-core/forks, op-core/predeploys |
fork names, predeploy addresses |
Conventions:
- Monorepo-best names and shapes. Inside
op-core/theOptimism/OPStackprefix is dropped, except forOptimismConfig(it pairs with the JSON keyoptimism) and the{Validate,Decode,Encode}OptimismExtraDatahelpers (there "Optimism" names the extraData format). Only computed values and wire formats must match other implementations. - Files that need both the go-ethereum and the op-core package import the latter as
optypes,opparams,opfees. - Wire compatibility. JSON tags and binary encodings are those of the OP Stack RPC and
consensus formats (
DepositTx:0x7E || RLP(fields);PostExecTx:0x7D || data, no RLP envelope).
Every OP wire format and hash rule has a second implementation in this repo: rust/op-alloy
defines the OP transaction and receipt types that op-reth and kona consume. Both sides serve one
chain, so a value one produces and the other rejects is a consensus split.
- The specs decide. Any new or changed encoding, hash or accept-set is checked against
rust/op-alloy, and a disagreement is decided from the specs, not from the incumbent. - Pin the agreed value in both languages. A shared golden vector — the same literal asserted
in the Go and the Rust suite — keeps the pair locked together;
TestPostExecTxHashGoldenVector(op-core/types/post_exec_tx_test.go) andrust/op-alloy/crates/consensus/src/post_exec/tests.rspin the post-exec tx hash this way. The op-reth L2 block and receipt fixtures inop-service/sources/testdata/l2pin the RPC wire format and the transactions and receipts roots, but only for values op-reth produces. - Golden vectors pin the Go values. The
op-coretests assert literal encodings, hashes, fees and genesis block hashes (theGoldenVectortests) that the Rust stack computes too. The values for a new fork come from op-reth, not from this code. The only test that compares the Go types with another implementation at runtime is the Go/Rust interop-deposits diff (ops/scripts/test-interop-deposits-diff.sh).
For batcher-controlled bytes (batches, frames, channels) the second implementation is kona's own decoder, and the rule compares accept-sets over a generated corpus; see derivation.md.
A go-ethereum *types.Transaction cannot hold a deposit or post-exec tx: its decoders reject
both types. An L2 block's tx list is [L1-info deposit (0x7E), …user txs…, optional post-exec (0x7D)] (a post-exec tx can end a Lagoon block), so decoding any L2 block body into
go-ethereum types fails, and so does ethclient's BlockByNumber, BlockByHash,
BlockReceipts, TransactionInBlock and TransactionByHash against an L2 endpoint whenever the
result holds an OP tx. The code compiles; only the call fails.
A forbidigo rule in .golangci.yaml rejects those five ethclient.Client methods in the
whole tree. An L1 read carries //nolint:forbidigo // L1: <reason>, and an L2 read that can only
return a user tx carries //nolint:forbidigo // L2 user tx: <reason>. The rule matches the
receiver's static type, so a call through an interface or an embedding type is not seen: don't
wrap an L2 read in one.
- Raw bytes decode into
optypes.DepositTx/optypes.PostExecTx. Code never asks "is this a deposit?" of a go-ethereum transaction; it checks the type byte of the encoding. - Code that needs a whole L2 block's transactions works on their binary encodings, as an
execution payload carries them (
opfees.CalcDAFootprint, op-sync-tester, op-wheel). - Never put a deposit into a
*types.Transactionor*types.Block, including in test fixtures: L2 block fixtures are execution payloads with raw tx bytes.
The op-service/sources clients speak raw JSON-RPC and are the OP-aware client; there is no
"OP ethclient" wrapper. Their apis.EthClient accessors partition a block's txs by class:
InfoAndUserTxsBy*— header and the standard Ethereum txs (OP txs excluded), astypes.Transactions.InfoAndDepositsBy*— deposits asoptypes.DepositTx.InfoAndFirstDepositBy*— header and the L1-info deposit only.PayloadBy*— the block as an execution payload, every tx as raw bytes.HeaderBy*— headers decode fine from any chain.
There is no accessor for a decoded 0x7D tx (PayloadBy* keeps its raw bytes): a test that
counts the txs of a Lagoon block must allow for one. InfoAndTxsBy* and HeaderAndTxsByHash
are for L1: sources.L2Client rejects an L2 block holding an OP tx there with ErrOpTxInBody.
Callers that correlate txs and receipts by index must account for the excluded OP txs:
optypes.Receipts.UserReceipts() pairs index-for-index with InfoAndUserTxs.
op-core/types.Receipt embeds go-ethereum's receipt and adds the complete OP receipt field set
(deposit nonce and receipt version, L1 fee fields, operator fee, DA footprint scalar), with JSON
and consensus codecs. go-ethereum's receipt JSON decoding drops those fields silently, so
anything that reads them — the e2e and acceptance suites — fetches receipts through
op-service/sources as *optypes.Receipt. A relay of L2 receipts either uses optypes.Receipt
or passes the raw JSON through (op-sync-tester).
optypes.FromGethReceipt wraps a go-ethereum receipt (L1, or L2 code that needs only standard
fields) with the OP fields unset. It rejects a deposit receipt, whose consensus encoding needs
the deposit nonce and receipt version. optypes.Receipts.Geth() is a view for code that reads
only standard fields (logs).
op-core/params.ChainConfig is standalone: it does not embed go-ethereum's
params.ChainConfig. Embedding would promote go-ethereum's OP-unaware EIP-1559 methods
(ElasticityMultiplier, BaseFeeChangeDenominator, LatestFork), which would silently return
L1 values for consensus-relevant fee parameters.
GethChainConfig() returns the go-ethereum config with the Ethereum fork schedule derived from
the OP schedule: Shanghai = Canyon, Cancun = Ecotone, Prague = Isthmus, Osaka = Karst (op-geth's
loader lacked Osaka = Karst; the monorepo follows op-reth). It carries nothing else, so
go-ethereum code reading it applies Ethereum rules: it is fit for the genesis state root and
header encoding, not for executing OP blocks or computing OP fees. Chain ID 10 gets OP Mainnet's
legacy Berlin and London blocks.
The JSON encoding of ChainConfig is a go-ethereum chain config with the OP keys added: the
go-ethereum config GethChainConfig() derives and the OP fields, both embedded in one struct.
The two key sets must stay disjoint (TestChainConfigJSONKeysDisjoint): encoding/json drops a
key both embedded structs declare. Decoding keeps only the OP fields; an Ethereum fork key that
contradicts the derived schedule is rejected, absent and unknown keys are accepted.
rollup.Config carries the full OP hardfork schedule itself (ChainOpConfig is an
*opparams.OptimismConfig). The *params.ChainConfig values in op-node are L1 chain configs
and are legitimately go-ethereum's. An OP Stack chain is not supported as L1:
NewL1ChainConfigFromCLI rejects its chain config.
op-devstack splits the same way: stack.L1Network.ChainConfig() returns the go-ethereum config,
stack.L2Network.ChainConfig() an *opparams.ChainConfig. Its Optimism EIP-1559 values are the
genesis values; from Holocene the SystemConfig sets them, so a test that needs the parameters in
effect decodes them from the block's extraData (eip1559.DecodeOptimismExtraData).
Genesis. op-core/genesis.Genesis is the one L2 genesis JSON encoding: the core.Genesis
envelope (header fields, alloc) with a config in opparams.ChainConfig's encoding; the
stateHash key is rejected. Genesis.ToBlock() is go-ethereum's genesis block for the same
header fields, alloc and Ethereum fork schedule plus the one OP rule: from Isthmus the header's WithdrawalsHash is the
storage root of the L2ToL1MessagePasser predeploy instead of the empty withdrawals root.
op-chain-ops/genesis.NewL2Genesis builds it; op-deployer computes the L2 genesis state with
forge (L2Genesis.s.sol).
- L2: op-reth only. op-e2e system tests and op-devstack/sysgo run op-reth as an external
process (
op-e2e/e2eutils/reth.InitL2,op-devstack/sysgo/l2_el_opreth.go), and neither has an EL-kind selector. op-e2e action tests and the kona proof tests run anop-reth-test-enginesubprocess. A suite outside this repo that tests its own EL build points sysgo at a CLI-superset binary of op-reth withDEVSTACK_L2EL_OVERRIDE_BINARY. Never start a go-ethereum node as an L2 EL: it runs the Ethereum state transition and nothing fails. - L1: go-ethereum in-process is right.
op-e2e/e2eutils/geth.InitL1(with its fake-PoS driver) and the op-test-sequencer fake-PoS builder use go-ethereum's own block building. The action tests'L1Miner(op-e2e/actions/helpers/l1_miner.go) assembles blocks by hand through go-ethereum'scorefunctions; it builds no block access lists, so it refuses Amsterdam blocks. - L1 blobs need Osaka. go-ethereum's transaction pool accepts only blob sidecars with cell
proofs, and its block builder includes them only from Osaka on, so a test L1 that carries blob
transactions runs Osaka. The
L1Minerincludes cell-proof blob transactions on any fork. - Scripts: upstream forge. op-deployer runs all deployment and genesis scripts with forge
(the Go script host is gone): keyless
forge scriptdry runs whose transactions op-deployer sends through txmgr, offline forge for genesis-target L1 and L2 genesis, and forge on an ephemeral anvil fork forprepare/continue. - No in-repo Go code executes an OP state transition.
op-sync-testerproxies a real op-reth EL; op-wheel'senginecommands drive a live EL over the Engine API.
Gaps: no test drives an L2 EL through the Engine API in-process; on op-reth,
eth_sendRawTransactionConditional (#24087) and the historical fork-boundary execution rules
(#24088) have no end-to-end test. System tests don't cover pre-Regolith L2 blocks.
op-service/logis the monorepo's logging API. It owns theLoggerinterface (go-ethereum's method set withoutWrite, withWith/NewreturningLogger, plusWithContext,LogAttrsand the…Contextmethods), its slog-backed implementation, the global logger and the package-levelTrace…Crit. ALoggeris immutable:WithContextderives a logger whose records default to that context. Handlers and level helpers are re-exported from go-ethereum;op-service/log/geth.gois the only file importinggo-ethereum/log, which thegeth-logdepguard rule enforces.ToGethconverts aLoggerwhere a go-ethereum API takes one;SetDefaultalso installs it as go-ethereum's global logger.op-service/jsonrpcowns RPC call recording (Recorder,Message,Response,RecordDone) and the JSON-RPCError.op-service/clientrecords calls in its own wrapper around the go-ethereum client; subscriptions are not recorded. Code embeddingop-service/rpccounts and times HTTP requests withWithHTTPRecorder. The<ns>_rpc_client_*metric names and labels are pinned byTestRPCMetricsDescriptors.
A bump can change exported signatures and, more dangerously, semantics. When bumping:
- Gas. EVM calls take a
vm.GasBudget(execution and state gas, EIP-8037) and return the leftover budget;core.GasPoolhas two dimensions from Amsterdam. Code that runs plain L1 calls passesvm.NewGasBudget(gas, 0)before Amsterdam. - Intrinsic and floor gas (
core.IntrinsicGas,core.FloorDataGas) take the fork rules.op-batcher/batcher.maxFloorDataGassets a batch tx's gas limit to the larger floor under the pre-Amsterdam and the Amsterdam rules, so a batch stays valid across L1's Amsterdam activation. - Blob schedule. Upstream has no Osaka or Amsterdam blob-schedule entries: Osaka keeps Prague's parameters and Amsterdam the latest BPO's.
- L1 forks. A new L1 fork can add header fields, system calls or Engine API versions that the
hand-built L1 blocks of
L1Miner, the fake-PoS drivers and op-node's L1 handling must follow.
Other OP Labs Go repos that imported the monorepo pinned op-geth through their own replace.
Decoupling one means dropping the replace and bumping to the latest go-ethereum and the latest
monorepo commit in one change: a repo that drops the replace on an old pin stays on a stale
go-ethereum, and an old monorepo pin does not build against a current go-ethereum. Downstream repos
pin monorepo commits (pseudo-versions), not releases, so a fix is available as soon as it is on
develop.
- A pseudo-versioned fork pin opts a module out of advisory matching: dropping it can surface high-severity advisories against the go-ethereum version the module actually ran. Treat that as a reason to bump, not to keep the pin. Some transitive dependencies arrive through libp2p, independent of go-ethereum, and need their own bumps.
- An edge into
op-core/superchain/bundlecaps a consumer's monorepo version: a package reaching the bundle cannot be built by a downstream module at all (#22678). The packages allowed to reach it are thebundleAllowedlist inop-core/superchain/bundle/deps_test.go; downstream modules importop-core/superchainfor the registry types and loader. - The rules above apply downstream too. Known cases:
infra/op-txproxyused op-geth'srpc.JsonError(the monorepo's counterpart isop-service/jsonrpc.Error) andparams.TransactionConditional*ErrCode, which need a home;infra/proxydimportedcore/types/interoptypes, whose access-list encodingop-core/interop/messagescarries;monitorism/op-monitorismreads L2 blocks withethclient.BlockByNumber, which fails on every L2 block and must move toop-service/sources.