Guidance for AI agents working with Go code in the Optimism monorepo. See dev-workflow.md for shared code simplicity principles, tool versions, and PR workflow.
Each Go service has its own justfile — run just --list in any service directory to see available targets.
# Build a single service (pattern: just ./<service>/<binary>)
just ./op-node/op-node
# Build all Go components
just build-goop-core/superchain/bundle //go:embeds superchain-configs.zip, which is gitignored
(only its .sha256 is committed). Any package that transitively imports it — op-node and
several binaries, plus op-e2e, op-acceptance-tests, op-deployer, and the kona/op-reth Go
tests — won't compile until the bundle is built:
op-core/superchain/bundle/bundle.go:NN: pattern superchain-configs.zip: no matching files found
op-core/superchain itself embeds nothing: it holds the registry's config types and a loader
for a bundle's bytes. Import bundle only for the registry built into the monorepo.
The just targets handle this: just build-go, just go-tests, and just lint-go all
depend on build-superchain-go, which builds the bundle from the superchain-registry
submodule and verifies it against the committed .sha256. You only hit the embed error on
a bare go build/go test or a fresh checkout. To prep it manually:
just build-superchain-go # Go bundle only (fast; verify mode)
just sync-superchain # all superchain bundles (Go + kona/op-reth Rust) — the registry-bump commandBecause the zip is usually already on disk, a missing-bundle problem is invisible locally and only surfaces in CI's clean checkout (see ci-ops.md).
The set of packages allowed to reach the bundle is pinned by TestBundleReachability
(op-core/superchain/bundle/deps_test.go): a new transitive edge into
op-core/superchain/bundle from a package outside its bundleAllowed allowlist fails that
test. Each allowlist entry is a package downstream Go modules cannot import, so extend the
list only for genuine registry consumers.
# Test a single service
cd <service> && just test
# Test specific packages
go test ./op-node/rollup/derive/...
# Run the full test suite from the repo root
just go-testsSome service justfiles have a generate-mocks target:
cd <service> && just generate-mocksApply the shared code simplicity principles with these Go-specific conventions:
- Prefer concrete dependencies. Introduce an interface when a real boundary requires it, rather
than wrapping a single implementation only to forward its methods. Keep
nilwhere absence has domain meaning; supply required dependencies at construction. - Let packages provide naming context. Prefer
derivation.Trustedoverderivation.TrustedDerivation. - OP type encodings: a change to an OP type's wire format, hash rule, or codec accept-set has to agree with
rust/op-alloy(the types op-reth and kona consume) — see Cross-implementation parity. - L2 blocks are payloads, transactions are bytes: handle an L2 block as an execution payload
and its transactions as their binary encodings (
hexutil.Bytes). Hash, measure, compare and forward the bytes, and classify a transaction by its type byte (optypes.IsDepositTxBytes,optypes.IsPostExecTxBytes). Decode a transaction only where a field of it is needed, and then into the type of its class:optypes.UnmarshalDepositTxfor a deposit,optypes.UnmarshalPostExecTxfor a post-exec transaction, a go-ethereumtypes.Transactionfor a user transaction. The transaction hash, the transactions root and the DA size are functions of the encoding, and go-ethereum cannot decode the OP Stack transaction types — see Reading L2 data for theop-service/sourcesaccessors that follow this rule. - Pointers to values: use
ptr.New(v)fromgithub.com/ethereum-optimism/optimism/op-service/ptrto take the address of a literal or expression — common for optional*uint64config fields like fork-activation times (cfg.SomeTime = ptr.New(uint64(123))). Don't define a localptr/ptrTohelper; the shared one avoids per-package duplicates, and a localfunc ptrcollides with importing theptrpackage in the same package.
The repo uses a custom golangci-lint build with additional analyzer plugins. The standard golangci-lint binary will not catch all issues — always lint through just.
# Lint (also verifies compilation and module tidiness)
just lint-go
# Lint with auto-fix
just lint-go-fixThe linter configuration is in .golangci.yaml — read it when you need specifics on which linters are enabled and how they're scoped.
Run these checks before committing Go changes. Fix all issues — CI enforces zero warnings.
-
Lint — this also verifies the code compiles and modules are tidy:
just lint-go
-
Test — run tests for changed packages:
cd <service> && just test