Skip to content

Latest commit

 

History

History
120 lines (88 loc) · 5.29 KB

go-dev.md

File metadata and controls

120 lines (88 loc) · 5.29 KB

Go Service Development

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.

Build System

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-go

The embedded registry bundle (op-core/superchain/bundle)

op-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 command

Because 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.

Running Tests

# 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-tests

Generating Mocks

Some service justfiles have a generate-mocks target:

cd <service> && just generate-mocks

Conventions

Apply 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 nil where absence has domain meaning; supply required dependencies at construction.
  • Let packages provide naming context. Prefer derivation.Trusted over derivation.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.UnmarshalDepositTx for a deposit, optypes.UnmarshalPostExecTx for a post-exec transaction, a go-ethereum types.Transaction for 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 the op-service/sources accessors that follow this rule.
  • Pointers to values: use ptr.New(v) from github.com/ethereum-optimism/optimism/op-service/ptr to take the address of a literal or expression — common for optional *uint64 config fields like fork-activation times (cfg.SomeTime = ptr.New(uint64(123))). Don't define a local ptr/ptrTo helper; the shared one avoids per-package duplicates, and a local func ptr collides with importing the ptr package in the same package.

Linting

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-fix

The linter configuration is in .golangci.yaml — read it when you need specifics on which linters are enabled and how they're scoped.

Before Every Commit

Run these checks before committing Go changes. Fix all issues — CI enforces zero warnings.

  1. Lint — this also verifies the code compiles and modules are tidy:

    just lint-go
  2. Test — run tests for changed packages:

    cd <service> && just test