optimism Documentation

op-program has also reached end of support, replaced by kona-client for fault proofs; the same notice covers both migrations.

Legacy Geth Copy Chapter

OP Mainnet blocks and transactions from before the 2023 Bedrock Upgrade can be read from any current execution client, but re-executing them (RPC calls such as eth_call against pre-Bedrock blocks) requires an optional third component, Legacy Geth (l2geth), the client that ran OP Mainnet before the upgrade.
It is typically only needed for complete OP Mainnet archive nodes; see the Legacy Geth configuration guide for setup and request routing, and accessing pre-regenesis history for the even older history that predates the current chain data entirely.

Next steps Copy Chapter

• To get your node up and running, start with the run a node from docker or build and run a node from source tutorial. The source tutorial covers op-reth (primary) and Nethermind execution clients.
• If you've already got your node up and running, check out the Node Metrics and Monitoring Guide to learn how to keep tabs on your node and make sure it keeps running smoothly.
• If you run into any problems, please visit the Node Troubleshooting Guide for help.

Public Docs App Developers Tools Sdks Op Alloy Building Index (`docs/public-docs/app-developers/tools-sdks/op-alloy/building/index.mdx`) Copy Section

title: "Building" diataxis: explanation Copy Chapter

This section offers in-depth documentation into the various op-alloy crates.
Some of the primary crates and their types are listed below.

• op-alloy-consensus provides OpBlock,
  OpTxEnvelope, OpReceiptEnvelope,
  and more.
• op-alloy-rpc-types-engine provides the
  OpPayloadAttributes.

Public Docs Op Stack Fault Proofs Kona Fpp Dev Intro (`docs/public-docs/op-stack/fault-proofs/kona/fpp-dev/intro.mdx`) Copy Section

title: "Fault Proof Program Development" diataxis: explanation Copy Chapter

This chapter provides an overview of Fault Proof Program development
on top of the custom FPVM targets supported by Kona.

At a high level, a Fault Proof Program is not much different from a regular no_std Rust program. A custom entrypoint is provided, and the program
is compiled down to a custom target, which is then executed on the FPVM.

Fault Proof Programs are structured with 3 stages:

1. Prologue: The bootstrapping stage, where the program is loaded into memory and the initial state is set up. During this phase, the program's initial
   state is written to the FPVM's memory, and the program's entrypoint is set.
2. Execution: The main execution stage, where the program is executed on the FPVM. During this phase, the program's entrypoint is called, and the
   program is executed until it exits.
3. Epilogue: The finalization stage, where the program's final state is read from the FPVM's memory. During this phase, the program's final state is
   inspected and properties of the state transition are verified.

The following sections will provide a more in-depth overview of each of these stages, as well as the tools and abstractions provided by Kona for
developing your own Fault Proof Programs.

Public Docs Op Stack Fault Proofs Kona Proof Intro (`docs/public-docs/op-stack/fault-proofs/kona/proof/intro.mdx`) Copy Section

title: "Kona Proof SDK" diataxis: explanation Copy Chapter

Welcome to the Kona Proof SDK, a powerful set of libraries designed
from first principles to build proofs with the OP Stack STF on top
of the OP Stack's FPVMs and other verifiable backends like SP-1,
Risc0, Intel TDX, and AMD SEV-SNP. At its
core, Kona is built on the principles of modularity, extensibility,
and developer empowerment.

A Foundation of Flexibility Copy Chapter

The kona repository is more than a fault proof program for the OP Stack
— it's an ecosystem of interoperable components, each crafted with
reusability and extensibility as primary goals. While we provide
Fault Proof VM and "online" backends
for key components like kona-derive and kona-executor, the true
power of kona lies in its adaptability.

Extend Without Forking Copy Chapter

One of Kona's standout features is its ability to support custom
features and data sources without requiring you to fork the entire
project. Through careful use of Rust's powerful trait system and
abstract interfaces, we've created a framework that allows you to
plug in your own features and ideas seamlessly.

What You'll Learn Copy Chapter

In this section of the developer book, we'll dive deep into the Kona SDK, covering:

• Building on the FPVM Backend: Learn how to leverage the Fault Proof VM tooling to create your own fault proof programs.
• Creating Custom Backends: Discover the process of designing and implementing your own backend to run kona-client or a variation of it on different targets.
• Extending Core Components: Explore techniques for creating new constructs that integrate smoothly with crates like kona-derive and kona-executor.

Whether you're looking to use Kona as-is, extend its functionality, or create entirely new programs based on its libraries,
this guide is intended to provide you with the knowledge and tools you need to succeed.

Public Docs Chain Operators Tools Op Deployer Reference Architecture Overview (`docs/public-docs/chain-operators/tools/op-deployer/reference/architecture/overview.mdx`) Copy Section

title: Architecture Copy Chapter

This section details OP Deployer's architecture and internals. Unless you're contributing directly to OP Deployer,
you don't need to read this.

• Deployment Pipeline: Describes the stages of the deployment pipeline.
• Scripting Engine: Describes the scripting engine that OP Deployer uses to interact
  with the EVM.

Full architecture diagram (source)

Ai Acceptance Tests (`docs/ai/acceptance-tests.md`) Copy Section

Running Acceptance Tests

Guidance for AI agents building and running acceptance tests in the Optimism monorepo. For guidance on writing new tests — DSL patterns, naming, what to avoid — see writing-acceptance-tests.md. See dev-workflow.md for tool versions and general workflow.

What Are Acceptance Tests? Copy Chapter

Acceptance tests live in op-acceptance-tests/tests/ and run full in-process devnet scenarios. They exercise the entire stack — contracts, Go services, and Rust binaries — in a single go test process. This means all dependencies must be built locally before running them.

Running Tests Copy Chapter

The just test target automatically builds dependencies (contracts, cannon prestates, Rust binaries) before running tests. The builds are incremental — re-running is fast when nothing changed.

Prerequisites: mise tools must be installed (see dev-workflow.md), and a working C toolchain (clang or gcc) must be available for Rust builds.

Always set RUST_JIT_BUILD=1 when running locally. This lets the test framework automatically build any Rust binaries it needs (e.g. op-reth) using cargo's rebuild detection, so you don't have to pre-build them separately.

Run from op-acceptance-tests/:

Specific Tests or Packages (recommended) Copy Section

# Run a single test
cd op-acceptance-tests && RUST_JIT_BUILD=1 mise exec -- just test -run TestMyTest ./op-acceptance-tests/tests/base/

# Run a package
cd op-acceptance-tests && RUST_JIT_BUILD=1 mise exec -- just test ./op-acceptance-tests/tests/base/...

The just test target builds deps, then runs go test -count=1 -timeout 30m with your arguments.

All Tests Copy Section

cd op-acceptance-tests && RUST_JIT_BUILD=1 mise exec -- just acceptance-test

Runs all test packages with gotestsum, structured logging, and bounded parallelism.

Selecting the L2 Clients Copy Section

Every run covers the whole ./op-acceptance-tests/tests/... tree; there is no per-package
subset target. Which clients the devstack starts is chosen by two environment variables, read
in op-devstack/sysgo/mixed_runtime.go:

• DEVSTACK_L2CL_KIND — op-node (the default) or kona-node
• DEVSTACK_L2EL_KIND — op-reth (the default) or op-geth

cd op-acceptance-tests && DEVSTACK_L2CL_KIND=kona-node RUST_JIT_BUILD=1 mise exec -- just acceptance-test

CI runs two variants of the op-acceptance-tests job: memory-all-opn-op-reth-<l1_fork>
(op-node + op-reth) and memory-all-kona-op-reth-<l1_fork> (kona-node + op-reth).

A test that cannot run under a given client skips itself in code rather than being left out of
a list — sysgo.SkipOnKonaNode, sysgo.SkipOnOpReth and sysgo.SkipOnOpGeth.

Kona Prestate Copy Section

Some tests (e.g. superfaultproofs, interop fault proofs) require a kona prestate. This is not handled by build-deps or RUST_JIT_BUILD. There are two ways to build it:

Reproducible build (preferred when Docker is available):

mise exec -- just reproducible-prestate-kona

This produces a prestate whose hash matches CI/release builds. It works on any host with Docker installed.

Native build (fallback when Docker is not available):

cd rust && mise exec -- just build-kona-prestates

Only works on Linux with the MIPS cross-compile toolchain installed. The produced hash will not match release builds, so this is only suitable for local test runs where the hash doesn't need to match a deployed release. If neither Docker nor the MIPS toolchain is available, ask the user to build the prestate for you.

What `build-deps` Does Copy Chapter

The just build-deps target (called automatically by just test) runs these steps when not in CI:

1. mise — mise install (ensures gotestsum, forge, etc. are available)
2. Contracts — cd packages/contracts-bedrock && just install && just build-no-tests
3. Cannon prestates — just cannon-prestates (builds the kona prestate artifacts)
4. Rust binaries — just build-rust-release (kona-node, kona-host, and op-reth). SDM
   acceptance fixtures use hidden, default-off testing flags on the normal op-reth binary.

You can also run just build-deps directly to pre-build without running tests.

Tuning Parallelism (`acceptance-test` only) Copy Chapter

When using just acceptance-test, the runner sets:

• ACCEPTANCE_TEST_JOBS — number of packages to test in parallel (default: 12)
• ACCEPTANCE_TEST_PARALLEL — go test -parallel value per package (default: 1)
• ACCEPTANCE_TEST_TIMEOUT — per-package timeout (default: 30m)

Override with environment variables:

cd op-acceptance-tests && ACCEPTANCE_TEST_PARALLEL=2 ACCEPTANCE_TEST_TIMEOUT=1h mise exec -- just acceptance-test

Log Output (`acceptance-test` only) Copy Chapter

When using just acceptance-test, logs are written to op-acceptance-tests/logs/testrun-<timestamp>/:

• all.log — full test output
• raw_go_events.log — JSON test events
• flaky-tests.txt — tests marked with MarkFlaky()

Results XML goes to op-acceptance-tests/results/results.xml.

When using just test, output goes to stdout only.

Common Issues Copy Chapter

• Missing prestates — Run cd op-acceptance-tests && mise exec -- just build-deps or mise exec -- just cannon-prestates from the repo root.
• Stale contracts — Rebuild with cd packages/contracts-bedrock && mise exec -- just build-no-tests.
• Missing Rust binaries — Run mise exec -- just build-rust-release from the repo root.
• gotestsum not found — Run mise install to install all pinned tools.

Ai Ci Config Review (`docs/ai/ci-config-review.md`) Copy Section

CI Config Review

Checklist for reviewing changes to .circleci/ and .github/workflows/. The
repo-specific items are the high-priority ones — they're where the real bugs
hide. For each changed file, walk the relevant items and look for the bad pattern.

How CI is wired here Copy Chapter

• config.yml is a setup pipeline (setup: true). prepare-continuation-config
  detects changed paths, runs the routing policy (compute-workflow-conditions.sh),
  merges the continuation fragments, and continues the pipeline. Only workflows whose
  c-run_* flag the policy set to true execute. It also front-loads the mise
  toolset (utils/install-mise): it always finishes before any continuation job
  starts, so on a cold cache it is the only job that installs over the network —
  continuation jobs restore the mise cache it saved.
• Routing is data + logic split: routing.yml holds the declarative data
  (schedule→workflows, API dispatch flag→workflows, change-detection patterns,
  passthrough params); compute-workflow-conditions.sh holds the conditions that
  decide which entries fire. Add a schedule/dispatch/pattern by editing routing.yml.
• The real config is merged from fragments under .circleci/continue/
  (helpers.yml → main.yml → rust-ci.yml → rust-e2e.yml →
  rust-nightly-bump.yml) by merge-configs.sh. Merge is later-wins: a key
  (job, command, anchor) redefined in a later fragment silently overrides the
  earlier one.
• Change detection: collect-params.sh str/bool turn c-* env vars into
  params; detect/detect_all match the routing.yml change patterns against the
  changed files (detect true if any file matches, detect_all only if every
  file matches). workflow-helpers.sh sets the c-run_* flags;
  test-decision-tree.sh asserts the routing policy.
• The gate: the GitHub enforce-ci-checks-develop ruleset requires exactly
  four checks — ci-gate, required-contracts-ci, required-rust-ci,
  required-rust-e2e. These are fan-in jobs (no work, just requires:). A merge
  is gated only by what they transitively require; anything outside their
  requires: chain can fail without blocking merge. Gates use utils/ci-gate.
• Continuation limits: a setup pipeline continues exactly once, within 6h, no
  setup→setup. A param declared in both config.yml and a fragment with
  different defaults fails with "Conflicting pipeline parameters".

Validating a change locally Copy Chapter

Because the real config is merged from fragments, validate the merged file, not a
single fragment:

# 1. Merge the fragments into /tmp/merged-config.yml (uses mise's yq; resolves anchors).
mise exec -- bash .circleci/scripts/merge-configs.sh

# 2. Validate it. --org-slug is REQUIRED: the private org orb
#    ethereum-optimism/circleci-utils won't resolve without it (and the CLI
#    needs CIRCLECI_CLI_TOKEN set to resolve --org-slug).
export CIRCLECI_CLI_TOKEN="<your token>"
circleci config validate --org-slug gh/ethereum-optimism /tmp/merged-config.yml

# 3. The setup config imports the private orb too, so it needs the same flag.
circleci config validate --org-slug gh/ethereum-optimism .circleci/config.yml

Install the CLI without sudo:
curl -fLSs https://raw.githubusercontent.com/CircleCI-Public/circleci-cli/main/install.sh | DESTDIR="$HOME/.local/bin" bash.

This checks orb resolution and config structure, but not continuation-time param
wiring — a param leak across fragment anchors still only surfaces when the pipeline
actually continues.

Choosing where a new job runs Copy Chapter

When a diff adds a job, the first question is cadence, not correctness. Options
here, fastest-signal/highest-cost first:

• PR-blocking — wired into a gate's requires: chain (items 1–3). Use only for
  checks that are fast, deterministic, and catch a regression class a reviewer
  can't eyeball. Every blocking job is a tax on every PR.
• Non-blocking on PR — runs on the PR but sits outside any gate's requires:.
  Treat as a staging area for a check not yet trusted to block, not a permanent
  home — non-blocking failures get ignored. Have a plan to promote it to blocking
  or move it off the PR.
• develop-only — filters: restricting to the develop/main branch; runs
  post-merge. For checks too slow, flaky, or expensive to block every PR but where
  you still want fast signal on the integration branch.
• Scheduled — a scheduled-* workflow gated on a c-run_scheduled_* param and
  dispatched by the schedule-name mapping in routing.yml (build_four_hours /
  build_daily / build_weekly). For exhaustive/expensive suites (full Cannon,
  heavy fuzz, reproducibility, link checks). A new scheduled job not added to that
  mapping never fires — verify the wiring, not just the workflow definition.

Default heuristic: block if fast + deterministic + guards a real regression;
otherwise push to develop-only or scheduled by cost and how quickly the signal is
needed.

Repo-specific checklist (high priority) Copy Chapter

Each item produces a silently-green-but-untested merge — the worst failure mode
here. Treat items 1–4 as blocking.

1. Gate coverage. Any job that should gate merge must appear (by exact name,
   incl. matrix suffix like contracts-bedrock-tests main) in the requires: of
   its gate. Renaming a job silently drops it. Wire merge-queue-only jobs
   (gh-readonly-queue) too. Beware intermediate fan-in helpers that aren't
   themselves a required check — they look like they gate but don't.

2. Skip paths must still emit every required check. Required checks match by
   name; if a fast path skips the workflow that produces one, the check never
   reports and the PR is permanently unmergeable. A skip path must run the same
   gate job with always-succeed: true. Check every required check name is
   produced on every alternate path the diff adds/changes.

3. always-succeed semantics. utils/ci-gate defaults to
   always-succeed: false → it queries the API for upstream job IDs and verifies
   them. A gate with no requires: and no always-succeed: true errors out
   (no dependency IDs found). So: empty requires: ⇒ must set
   always-succeed: true; real requires: ⇒ must not set it (would green the
   check without verifying deps).

4. Path filtering must be all-match, not exclusion. Detect a limited change
   set (e.g. docs-only) with detect_all (true iff every file matches the
   narrow pattern), never by excluding known categories (docs && !contracts && !rust) — unenumerated paths (new dirs, Go files) would slip through and skip
   real tests. Be suspicious of negative lookaheads (^(?!...)). Confirm
   test-decision-tree.sh covers the "undetected code" case.

5. No duplicate command/anchor defs across fragments. Later-wins merge means
   a redefinition in a later fragment silently shadows the canonical one, dropping
   its behavior with no error. helpers.yml is the home for shared commands. If a
   diff adds a commands:/executors:/anchor, grep the other fragments for the
   same key.

6. Cache keys. CircleCI caches are write-once: once a key is saved it is
   immutable, and a later save_cache with the same key is a silent no-op — the
   stale content is served forever. So a key must hash every input that affects
   the cached content; if any such input can change without the key changing, the
   cache poisons. The classic mistake is keying build output (compiled artifacts)
   on the lockfile alone: Cargo.lock/go.sum covers dependency downloads, but
   the compiled output also depends on the source, the toolchain, and the build
   profile/features — keying it on the lockfile alone serves a stale build whenever
   source changes but deps don't. Verify the key for each cache covers all of its
   real inputs:

   • dependency downloads → lockfile (Cargo.lock, go.sum, etc.) is enough,
     since the lockfile fully determines what's downloaded;
   • build output → lockfile plus something that changes with the source
     (e.g. a hash of the source tree / git rev) plus toolchain pin and
     profile/features.
     Shared content (dependency downloads) → one shared key, not a per-job prefix
     (avoids each job storing/re-downloading its own copy). Separate caches by
     invalidation cadence (toolchain keyed on toolchain pins, deps on lockfile, build
     output on lockfile+source+profile+features). Fallback restore keys are
     deliberate: a chain restores a near-match and recompiles the delta; no fallback
     forces a full refresh (right for download caches, so they can't accrete stale
     versions). Keys carry a version buster (rust-cache-version, go-cache-version)
     for manual invalidation when the key formula itself is wrong. Check save and
     restore keys stay consistent.

   Also check cache coverage: every job that builds or compiles should restore
   the relevant dependency cache, at minimum — a Go job should restore the Go
   module/build cache, a Rust job the cargo registry/git (and ideally build) cache,
   a Node job the package cache. A job that skips the restore step does a cold build
   every run: it inflates PR-path time and cost (ties into item 8), and — just as
   importantly — it re-downloads every dependency over the network on each run,
   turning transient network failures into CI flakes that a warm cache would have
   avoided. When a diff adds a new build job or a new build step to an existing job,
   confirm it restores the appropriate cache rather than relying on another job to
   have warmed it.

7. Resource class / concurrency / timeouts. Right-size resource_class with a
   stated reason; bound parallelism and shard memory-hungry suites rather than
   over-subscribing one runner. Set no_output_timeout above healthy runtime but
   tight enough to catch hangs.

8. CI time. Weigh what a change does to PR-path wall-clock and cost: a new
   heavy job added to a gate's requires:, reduced parallelism, a larger
   resource_class, or a removed/narrowed cache all add up. Don't eyeball it —
   capture actual before/after numbers. The reliable way is a draft PR: push the
   change, then compare job durations (and the critical-path total) against the
   base. Cite the real numbers in review rather than guessing.

9. Validate locally. Never circleci config validate a single fragment (fails
   on duplicate keys). Always produce the merged output by running the repo's own
   script — bash .circleci/scripts/merge-configs.sh, which writes
   /tmp/merged-config.yml — so you validate exactly what CI builds; don't
   re-run the yq merge by hand. Then validate /tmp/merged-config.yml, first
   stubbing the private ethereum-optimism/circleci-utils orb (inline orb with
   checkout-with-mise, ci-gate, github-event-handler-setup, github-stale;
   name is reserved). Also run bash .circleci/scripts/test-decision-tree.sh.
   Validation catches schema and missing-requires:-target errors, not semantics
   (items 1–6).

   validate is not enough — use process with pipeline parameters. Jobs
   reachable only from a when: << pipeline.parameters.c-run_* >> workflow are
   skipped when the parameter is false, which is the default, so a job that fails
   to compile validates clean. Process the merged config with the gated params
   turned on:

   sh Copy

   printf '{"c-run_release":true,"c-run_kona_publish_prestates":true}' > /tmp/pp.json
   circleci config process --pipeline-parameters /tmp/pp.json /tmp/merged-config.yml

   Never write << inside a command:. CircleCI 2.1 treats << as a
   parameter-tag opener before any shell sees it, so bash here-strings (<<<) and
   heredocs (<<EOF) fail the whole continuation with Unclosed '<<' tag — and a
   continuation that fails to compile produces no workflows at all, so every
   check silently disappears from the PR instead of going red. This bites shell
   comments too: a comment merely mentioning the token fails compilation.
   Escape as \<< if you truly need the literal, or restructure to avoid it —
   but mind what the restructure costs:

   sh Copy

   ARR=(); while IFS= read -r L; do ARR+=("$L"); done < <(cmd)
                                    # no '<<', but swallows cmd's exit status:
                                    # a failing cmd reads as an empty array
   TMP=$(mktemp); cmd > "$TMP"      # keeps set -e, and keeps the stream off the
   ARR=(); while IFS= read -r L; do ARR+=("$L"); done < "$TMP"   # Prefer this.
   rm -f "$TMP"
   (( ${#ARR[@]} > 0 )) || { echo "empty" >&2; exit 1; }

   Process substitution trades the << bug for a swallowed-exit-status bug, so
   assert on the result either way. For a heredoc, write the body to a temp file.

   Read the lines with while read, not mapfile: mapfile is a bash 4
   builtin, and macOS ships bash 3.2, so any snippet copied from a CI command
   into a justfile recipe would break local runs. Same for the rest of bash 4
   (declare -A, ${var^^}, local -n).

General best practices Copy Chapter

Repo is CircleCI-primary; GitHub Actions footprint is small but these apply there.

Security

• [GHA] Pin third-party actions/reusable workflows to a full commit SHA, not a
  tag/branch — tags are mutable.
• [GHA] Never interpolate untrusted ${{ github.event.* }} (PR title/body,
  branch, commit msg) into run: — script injection. Pass via env:, use "$VAR".
• [GHA] pull_request_target/workflow_run run privileged (write token +
  secrets); never check out and run PR-head code under them. Build fork code under
  plain pull_request.
• [GHA] Least-privilege permissions: — contents: read at top, widen per-job.
  Prefer OIDC over long-lived cloud secrets.
• [CCI] Secrets in restricted contexts, not org-wide project vars; pin orbs to an
  exact version (never @volatile).
• [both] Never echo/CLI-pass secrets; auto-redaction misses transformed values.

Correctness

• [both] Caches are write-once/immutable per key — a re-save under an existing key
  is a no-op, so the key must hash every input affecting the content (lockfile for
  downloads; lockfile+source+toolchain+profile for build output) or it serves stale
  content forever. Use broader fallback restore-keys; a key with no hashed input
  never invalidates.
• [GHA] Required check + paths-ignore deadlocks the PR (check stays Pending) —
  same class as items 2–4; use an always-passing companion with the required name.
• [both] Set explicit timeouts — GHA's default job timeout is 6h.
• [GHA] concurrency group must include github.workflow; cancel-in-progress
  for CI, not for prod deploys.
• [GHA] Matrix fail-fast defaults to true; set false for full results, cap
  max-parallel.
• [both] Retry only genuine transients; "passes on retry" is a flake to fix.

Maintainability

• [both] DRY via reusable workflows/composites [GHA] or orbs/anchors [CCI].
  secrets: inherit passes everything — prefer explicit per-secret.
• [both] Pin runner images (ubuntu-latest drifts) and Docker base images by
  @sha256: digest.
• [GHA] continue-on-error / set +e mark steps green — branch on
  steps..outcome; set shell: bash so piped failures aren't swallowed.

Ai Ci Ops (`docs/ai/ci-ops.md`) Copy Section

CI/CD Operations

This document provides guidance for AI agents working with CI/CD operational tasks in the Optimism monorepo.

For Docker image build failures — especially flaky apt/apk/curl downloads from package registries and CDNs — see docker.md.

Watching CI after a push Copy Chapter

Watch every push to a terminal state — AGENTS.md requires it. Most jobs run on
CircleCI and report as commit statuses, so gh sees them alongside the GitHub Actions
and Wiz checks:

gh pr checks <pr> --watch --fail-fast   # blocks until done, exits on the first failure
gh pr checks <pr> --required            # only the merge-gating checks
gh pr checks <pr> --json name,bucket,link --jq '.[]|select(.bucket=="fail")'

--watch blocks until every reported check settles — the main workflow alone runs
~25 minutes, past most agent command timeouts — so background it or re-invoke it
instead of running it as a blocking call.

Notes that matter in practice:

• Wait for the gates the ruleset requires, not the individual jobs: the four
  CircleCI fan-in gates (ci-gate, required-contracts-ci, required-rust-ci,
  required-rust-e2e) plus the dependency-review GitHub Actions check. A gate reports
  last, so it can still be pending while every job you were watching is green. On skip
  paths the gate is produced by an always-succeed companion, so a gate that never
  reports at all is a config bug (see ci-config-review.md item 2),
  not something to wait out.
• A first push is not the only push to watch. Rebases, review fixups, and
  merge-queue rebases each start a new pipeline against a different merge base.
• Triage before rerunning. Rule out an inherited failure (next section), then check
  whether the test is a known flake. The generate-flaky-tests-report job publishes a
  flaky-test-reports artifact, but it covers op-acceptance-tests only, is scoped to
  the pipeline's own branch (use a develop pipeline's copy, not your PR's) and does not
  run on fast paths; for every other suite, look for an open flake issue instead. A rerun
  that hides a real regression costs more than the minutes it saved, and a confirmed
  flake needs an issue, not a silent retry. Reruns through the CircleCI v2 API need a
  personal API token in CIRCLE_TOKEN — not the CIRCLECI_CLI_TOKEN the CLI reads for
  ci-config-review.md's circleci config validate --org-slug, and
  not the CIRCLE_API_TOKEN in .circleci/, which is the in-job context token. For
  flakes in op-acceptance-tests//op-devstack/,
  flake-prevention.md catalogues the recurring causes.

Diagnosing a CI failure on a feature branch Copy Chapter

Before assuming a red check is caused by your change, rule out a failure the branch
inherited — especially a long-lived branch that has drifted from develop:

1. Check the diff scope: git diff origin/develop...HEAD --name-only (three dots).
   If the failing test exercises code your branch never touches, it almost certainly
   isn't your regression.
2. Check develop: the failure may be a known flake, or a real bug a later
   develop commit already fixed — your branch just predates the fix. Look for an open
   flake issue or a recent fix PR touching the failing area.
3. Rebase onto latest develop before deeper debugging — stale branches miss
   upstream fixes, and a rebase often clears failures that were never about your change.

Worked example (#21356): go-tests-short failed on op-deployer integration tests on a
branch that only added a new op-core/types package. The diff touched nothing in
op-deployer; the failures were a data-dependent flake already fixed on develop by
#21396. Rebasing made CI green with no change to the branch's own work.

Missing `op-core/superchain` bundle (`superchain-configs.zip`) Copy Chapter

A CI-only compile error like:

op-core/superchain/chain.go:NN: pattern superchain-configs.zip: no matching files found

means the job builds Go that transitively links op-core/superchain without the bundle
it //go:embeds. The zip is gitignored and built only by the prep-superchain job
(or just build-superchain-go locally), so every job that compiles an
op-core/superchain linker must provision it. The linker set is large — op-node and
several other binaries, but also op-e2e, op-acceptance-tests, op-deployer, and the
kona/op-reth Go tests (TestBundleReachability in op-core/superchain/deps_test.go
pins the full set) — so a Go-only change can red-wash unrelated-looking jobs
(rust-e2e) all at compile time. It passes locally and in review because the
developer already has the zip on disk (see go-dev.md).

Provision the bundle in the failing job:

• main.yml jobs (the prep-superchain job lives in that workflow): add
  prep-superchain to the job's requires and attach its workspace
  (attach_workspace) — the same pattern go-tests uses.
• Other workflows (rust-ci.yml, rust-e2e.yml — no prep-superchain job there):
  add an in-job just build-superchain-go step (verify mode: regenerates from the
  superchain-registry submodule and asserts the committed .sha256).
• just recipes that compile such Go: have the recipe run
  just build-superchain-go first.

When adding a new op-core/superchain consumer, audit every CI job that compiles it.

TODO Checker Failures Copy Chapter

The repo runs a scheduled CircleCI job every 4 hours that validates TODO comments don't reference closed GitHub issues. When this job fails, issues need to be reopened.

Quick Instructions Copy Section

1. Find the failed TODO checker job in CircleCI (scheduled workflow named scheduled-todo-issues)
2. Identify which issues were closed but still have active TODOs in the codebase
3. For each issue:
   • Determine who closed it (using GitHub timeline API)
   • Read the actual TODO comment from the code
   • Reopen with proper attribution and context
   • Include file location and CircleCI job link

Detailed Workflow Copy Section

For complete step-by-step instructions with all commands and error handling, see:
.claude/skills/fix-todo/SKILL.md

The skill includes:

• Detailed commands for querying CircleCI and GitHub APIs
• How to find who closed an issue
• Comment template for reopening
• Error handling for edge cases
• Output format and requirements

Ai Contract Dev (`docs/ai/contract-dev.md`) Copy Section

Smart Contract Development

This document provides guidance for AI agents working with smart contracts in the OP Stack.

Non-Idempotent Initializers Copy Chapter

When reviewing initialize() or reinitializer functions, check whether the function is idempotent — calling it multiple times with the same arguments should produce the same end state as calling it once.

The Risk Copy Section

Proxied contracts in the OP Stack can be re-initialized during upgrades (via reinitializer(version)). Orchestrators like OPContractsManagerV2._apply() call initialize() on contracts that may already hold state from a previous initialization. If the initializer is not idempotent, re-initialization can corrupt state.

Example: ETHLockbox.initialize() calls _authorizePortal() for each portal passed in. Currently safe because _authorizePortal() is idempotent — setting authorizedPortals[portal] = true twice has the same effect as once. But if someone later added a portal count that increments on each authorization, re-initialization would double-count portals.

What Makes an Initializer Non-Idempotent Copy Section

• Incrementing counters or nonces
• Appending to arrays (creates duplicates on re-init)
• External calls with lasting side-effects (e.g., minting tokens, sending ETH)
• Operations that depend on prior state (e.g., "add 10 to balance" vs "set balance to 10")

Other Reasons an Initializer may be Unsafe to Re-Run Copy Section

• Emitting events that trigger off-chain actions (e.g., indexers that process each event exactly once)
• Overwriting a variable that other contracts or off-chain systems already depend on (e.g., resetting a registry address that live contracts are pointing to, or changing a config value that should be immutable after first init)

Rule Copy Section

Non-idempotent or unsafe-to-rerun behavior in initialize() / reinitializer functions is disallowed unless the consequences are explicitly acknowledged in a @notice comment on the function. The comment must explain why the non-idempotent behavior is safe given how callers use the function.

Without this comment, the code must not be approved.

Review Checklist Copy Section

When reviewing changes to initialize() or its callers:

1. Is every operation in this initializer idempotent? Assigning a variable to a fixed value is idempotent. Incrementing, appending, or calling external contracts may not be.
2. Could overwriting any variable be unsafe? Some values should only be set once — overwriting them during re-initialization could break other contracts or systems that depend on the original value.
3. Can this contract be re-initialized? Check for reinitializer modifier. If it only uses initializer (one-shot), the risk does not apply.
4. If non-idempotent or unsafe behavior exists, is there a @notice comment acknowledging it? The comment must explain why it's safe. If the comment is missing, flag it as a blocking issue.

Scope and Architecture Copy Chapter

L1 and L2 smart contracts in the OP Stack live primarily in packages/contracts-bedrock/.
These contracts secure real value — OP Mainnet, Base, and other Superchain members — so every
change carries risk, especially changes to the implementations in
packages/contracts-bedrock/src/. The canonical Solidity style guide is at
packages/contracts-bedrock/book/src/contributing/style-guide.md, the interface policy at
packages/contracts-bedrock/book/src/contributing/interfaces.md, and the versioning and upgrade
policies under packages/contracts-bedrock/book/src/policies/.

Proxy System Copy Section

All protocol contracts live behind EIP-1967 transparent proxies. The proxy implementation is
custom (not OpenZeppelin), located at src/universal/Proxy.sol. A ProxyAdmin contract manages
upgrades for all proxies in a system.

Key properties:

• Admin calls are blocked from being proxied (transparent proxy pattern).
• msg.sender == address(0) check allows eth_call simulation.
• Atomic upgrade-and-call via upgradeToAndCall().
• Legacy support for CHUGSPLASH and RESOLVED proxy types.

Cross-Chain Messaging Copy Section

Two messaging systems:

• L1<>L2: CrossDomainMessenger (abstract base) with L1 and L2 specializations.
• L2<>L2: L2ToL2CrossDomainMessenger (predeploy at 0x4200...0023).

The message nonce encodes a version in the upper 16 bits (lower 240 bits are the nonce). V1
messages include sender, target, value, gasLimit, and data. Gas overhead constants account for
EIP-150 63/64 forwarding.

Key Invariants Copy Section

• Proxy upgrade safety: storage layout must never change incompatibly.
• Initializer guards: contracts must not be re-initializable without the StorageSetter flow.
• Bridge message integrity: cross-domain messages must be provably relayed.
• Deposit transaction ordering: deposits are processed in L1 inclusion order.
• No duplicate message relay: the successfulMessages mapping prevents replays.
• Reentrancy safety: transient storage guards on all message relay paths.

Key Contracts Copy Section

Utility Libraries Copy Section

Source Directory Structure Copy Section

src/
├── L1/           # L1 protocol contracts (OptimismPortal2, SystemConfig, bridges)
│   └── opcm/     # OPContractsManager implementations
├── L2/           # L2 predeploy contracts (GasPriceOracle, messengers, bridges)
├── universal/    # Shared by L1 and L2 (Proxy, ProxyAdmin, StandardBridge, CrossDomainMessenger)
├── libraries/    # Pure utility libraries (Hashing, Encoding, SafeCall, Constants, Predeploys)
├── dispute/      # Fault proof dispute game contracts
├── governance/   # Governance contracts
├── safe/         # Safe multisig extensions
├── cannon/       # Cannon VM contracts
├── periphery/    # Peripheral contracts
├── integration/  # Integration utilities
├── vendor/       # External vendored code
└── legacy/       # Deprecated contracts

Proxy and Upgradeability Copy Chapter

Every new implementation contract must follow this pattern:

1. Extend OpenZeppelin's Initializable.
2. Include initialize() with the reinitializer(initVersion()) modifier.
3. In the constructor: call _disableInitializers() and set immutables only.
4. Extend ReinitializableBase(N) with the current init version.
5. Never pass a hardcoded literal version to reinitializer(...) — always initVersion().

Upgrade Process (Atomic 3-Step) Copy Section

1. Upgrade implementation to StorageSetter.
2. Use StorageSetter to zero the initialized slot (typically slot 0).
3. Upgrade to the new implementation and call initialize().

This is done atomically via ProxyAdmin.upgradeAndCall().

Storage Layout Copy Section

• Never modify existing storage slot assignments.
• Use private spacer variables for removed fields: spacer_<slot>_<offset>_<length>.
• Tag spacers with @custom:legacy and @custom:spacer.
• Storage gaps for inheritance: uint256[N] private __gap.
• CI validates storage layout via snapshots in snapshots/storageLayout/.
• Deterministic storage slots are used in SystemConfig (via keccak256("systemconfig.fieldname")).

Access Control Copy Section

• ProxyAdminOwnedBase for proxy admin ownership checks.
• CrossDomainOwnable3 for L2 contracts with cross-domain ownership.
• onlyEOA() modifier to prevent smart contract wallet calls.
• onlyOtherBridge() for bridge message validation.
• Use ICrossDomainMessenger.xDomainMessageSender() for cross-chain caller verification.

Reentrancy Protection Copy Chapter

• Transient storage-based guards (EIP-1153) via TransientReentrancyAware.
• nonReentrant modifier on message relay functions.
• Call depth tracking via TransientContext.increment() / decrement().
• The successfulMessages mapping prevents duplicate message relay.

Cross-Chain Messages Copy Chapter

• Message versioning embedded in nonce (upper 16 bits = version, lower 240 = nonce).
• V1 encoding: abi.encode(nonce, sender, target, value, gasLimit, data).
• V1 hash: keccak256(abi.encode(nonce, sender, target, value, gasLimit, data)).
• Gas overhead constants defined in CrossDomainMessenger (200k relay constant, 5k check buffer).
• 63/64 gas forwarding rule (EIP-150) handled by the SafeCall library.

Contract Organization Copy Chapter

Reference implementations: SystemConfig.sol and OptimismPortal2.sol.

// SPDX-License-Identifier: MIT
pragma solidity 0.8.15;

// Contracts
import { ProxyAdminOwnedBase } from "src/universal/ProxyAdminOwnedBase.sol";
import { Initializable } from "@openzeppelin/contracts/proxy/utils/Initializable.sol";

// Libraries
import { SafeCall } from "src/libraries/SafeCall.sol";

// Interfaces
import { ISemver } from "interfaces/universal/ISemver.sol";

/// @custom:proxied true
/// @title ContractName
/// @notice Description
contract ContractName is Initializable, ProxyAdminOwnedBase, ReinitializableBase, ISemver {
    // Constants and immutables
    // Custom errors
    // Events
    // State variables (with @custom:network-specific where appropriate)
    // Spacers (with @custom:legacy and @custom:spacer)
    // Constructor (call _disableInitializers())
    // Initializer
    // External functions
    // Internal functions
}

Solidity Standards Copy Chapter

Tooling Copy Section

• Foundry under the hood, but always drive it through the just recipes in
  packages/contracts-bedrock/justfile — never call forge directly. The recipes wire up
  go-ffi, profiles, and the script cache for you.
• just build builds the contracts; just build-dev is the faster variant
  (FOUNDRY_PROFILE=lite) for local iteration. Builds must produce zero warnings
  (deny = "warnings" in foundry.toml).
• just test runs the suite; just test-dev is the faster lite-profile variant for local
  iteration. Default 64 fuzz runs; CI uses 128.
• just lint formats and checks (forge fmt under the hood: 120-char line length, bracket
  spacing, multiline func headers).
• Semgrep for security linting (custom rules in .semgrep/rules/, via just semgrep).
• Slither for static analysis.

In packages/contracts-bedrock, run every recipe through mise so it uses the pinned toolchain
(see Build and Test Commands below): e.g. mise x -- just build-dev.

Pragma Copy Section

• Unified Solidity version across the codebase (currently 0.8.15 for most contracts).
• Pin the final derived contracts and scripts — concrete (non-abstract) production contracts
  and deploy scripts must use an exact pragma (pragma solidity 0.8.15;). The strict-pragma
  CI check enforces this on files containing a concrete contract.
• Floating pragmas are fine for reusable libraries — a ^0.8.0 pragma is common and
  acceptable for src/libraries/, abstract base contracts, and interfaces. These are not pinned
  because they're consumed by the pinned contracts that derive from them, and CI deliberately
  exempts libraries, interfaces, and abstract contracts from the strict-pragma check.
• Never introduce a new Solidity version without a formal design-doc proposal.
• New versions must be at least 6 months old before adoption.

Naming Conventions Copy Section

Immutables Copy Section

• Must be internal (never public).
• Must have a handwritten getter returning the lowercase name.
• This decouples the ABI from whether a value is stored or immutable.

address internal immutable OWNER_ADDRESS;
function ownerAddress() public view returns (address) { return OWNER_ADDRESS; }

Struct Storage Variables Copy Section

• Must be internal with a _ prefix.
• Must have a handwritten getter returning the struct type (not a tuple).
• Solidity auto-generated getters return tuples, which breaks ergonomics.

Config internal _config;
function config() public view returns (Config memory) { return _config; }

Errors Copy Section

• Custom Solidity errors for all new code.
• Format: error ContractName_ErrorDescription().
• Revert with revert ContractName_ErrorDescription().
• No require(condition, "string") or revert("string") in new code.

NatSpec Comments Copy Section

• Triple-slash /// style.
• Use @notice exclusively (never @dev).
• Newline between @notice and the first @param.
• Newline between @param and the first @return.
• 100-character line length for comments.

Custom tags:

• @custom:proxied — contract lives behind a proxy.
• @custom:upgradeable — contract meant to be inherited by upgradeable implementations.
• @custom:semver — version variable (semver format).
• @custom:legacy — function/event exists only for backwards compatibility.
• @custom:network-specific — state variables that vary between OP Chains.
• @custom:spacer — spacer variables for removed storage.

Import Order Copy Section

Imports must be grouped and ordered — contracts first, libraries second, interfaces last:

// Contracts (first)
import { StandardBridge } from "src/universal/StandardBridge.sol";

// Libraries (second)
import { SafeCall } from "src/libraries/SafeCall.sol";

// Interfaces (last)
import { ISemver } from "interfaces/universal/ISemver.sol";

Interface Policy Copy Section

• Source contracts must NOT inherit from their own interfaces.
• Contracts CAN import interfaces for OTHER contracts.
• Every source contract must have a corresponding interface in interfaces/.
• Interfaces must include a __constructor__() pseudo-constructor.
• CI enforces a 1:1 ABI match between source and interface.

Versioning Copy Section

• All non-library, non-abstract contracts must implement ISemver.
• Expose string public constant version = "X.Y.Z"; with the @custom:semver tag.
• Patch: comment-only changes (no bytecode change except the version string).
• Minor: bytecode or ABI expansion (non-breaking).
• Major: breaking interface or security model changes.
• version >= 1.0.0 required for production readiness.
• Bump once per PR, not per commit — PRs are squash-merged, so only one commit appears in
  history. The final version should reflect the total change from the PR's base branch.

Events Copy Section

• All state-changing functions must emit a corresponding event.
• Events enable transparent monitoring and log reconstruction.

Testing Conventions Copy Chapter

Function Naming Copy Section

Format: [method]_[FunctionName]_[reason]_[status]

• [method]: test, testFuzz, or testDiff.
• [FunctionName]: function or behavior being tested.
• [reason]: optional description (required for reverts / fails).
• [status]: succeeds, reverts, works, fails, or benchmark.

Rules: camelCase per part, no double underscores, exactly 3 or 4 parts.

// Valid
function test_transfer_succeeds() external { }
function test_transfer_insufficientBalance_reverts() external { }
function testFuzz_balanceOf_randomAccount_succeeds(address _account) external { }

// Invalid
function test_transfer_reverts() external { }         // Missing reason
function test_TRANSFER_succeeds() external { }        // Not camelCase
function testTransferSucceeds() external { }          // No underscores

Contract Naming Copy Section

• <ContractName>_<FunctionName>_Test — tests for a specific function.
• <ContractName>_TestInit — reusable initialization/setup.
• <ContractName>_Harness — expose internal functions for testing.
• <ContractName>_Uncategorized_Test — miscellaneous tests.

Test File Organization Copy Section

• Files in test/ with the .t.sol extension.
• Mirror the src/ directory structure.
• One test contract per function being tested.
• All tests inherit from CommonTest (provides a full OP Stack deployment).

Testing Infrastructure Copy Section

• CommonTest base class deploys the full OP Stack (L1 + L2).
• Pre-configured actors: alice and bob with 10,000 ETH each.
• Feature flags for testing variants: altDA, interop, custom gas token.
• Fork test support: automatic detection via the FORK_TEST env var.
• Invariant tests in test/invariants/ with guided and unguided fuzz modes.
• Kontrol formal verification in test/kontrol/.
• Go FFI for off-chain computation in tests.

Foundry Configuration Highlights Copy Chapter

• Default optimizer: 999,999 runs.
• Dispute/OPCM contracts: 5,000 runs (bytecode size management).
• EVM version: cancun.
• Extra output: devdoc, userdoc, metadata, storageLayout.
• FFI enabled for scripts/tests.
• Gas limit: max int64 (for large tests).
• Fuzz runs: 64 (default), 128 (CI), 20,000 (ciheavy).

Dispute games, OPCM, OptimismPortal2, StorageSetter and L2ContractsManager compile with
5,000 optimizer runs for bytecode size management (compilation_restrictions in
foundry.toml; OPContractsManagerV2 and OPContractsManagerStandardValidator are the
outliers at 200).

TODO(optimism-private#779): Restore OPContractsManagerV2 to 5,000 optimizer runs.

Build and Test Commands Copy Chapter

All commands in packages/contracts-bedrock must run through mise so they use the pinned
versions of forge, solc, go, etc. Never run a bare just <target> or forge <cmd> — these
bypass the pinned toolchain.

mise x -- just build-dev          # Fast dev build (preferred for local work)
mise x -- just test-dev           # Fast dev tests (preferred for local work)
mise x -- just lint               # Format fix + check
mise x -- just pr                 # Full pre-PR suite: build, lint, all checks
mise x -- just test-upgrade       # Fork tests against mainnet state (needs ETH_RPC_URL)
mise x -- just semver-lock        # Regenerate semver-lock.json
mise x -- just snapshots          # Regenerate all snapshots
mise x -- just semver-lock-no-build  # Regenerate from existing artifacts (faster)

just build and just test run production builds with full optimization — slower. Use
just build-dev and just test-dev for day-to-day iteration. Recipes forward extra args to
forge, so pare a run down to what you're working on with --match-contract / --match-test
(e.g. mise x -- just test-dev --match-contract OptimismPortal2_Test) — much faster than the
whole suite. Run the full just test before opening a PR, since that's what CI runs.

just test-upgrade forks mainnet (or Sepolia) at a daily-pinned block, applies the upgrade
path, and runs tests in test/{L1,dispute,cannon}/. It verifies that upgrades work against
real deployed state — the actual upgrade path, not just a clean deployment. Requires
ETH_RPC_URL. Run it when modifying upgradeable contracts or the upgrade flow itself.

CI Checks Copy Chapter

All of these must pass:

• forge fmt --check — formatting.
• Semgrep scan — security rules.
• Snapshot generation — ABI + storage layout + semver lock.
• Semver diff — version bump required when bytecode changes.
• Unused imports — no dead imports.
• Strict pragma — no floating pragmas.
• Storage spacers — spacer naming and placement.
• Reinitializer modifiers — proper upgrade guards.
• Interface correctness — 1:1 ABI match.
• Contract size — within the EIP-170 limit.
• Test naming — conventions enforced by the validation script.

Rebase Conflicts in Generated Snapshot Files Copy Chapter

snapshots/semver-lock.json is generated — both sides of a conflict are wrong. The hashes
must be recomputed from the actual compiled artifacts after the rebase lands. Even hashes the
branch author pre-computed may be stale.

1. Accept either side to clear the conflict markers.
2. Run mise x -- just semver-lock in packages/contracts-bedrock/ to regenerate.
3. Stage the regenerated file and amend the commit (or continue the rebase).

The same rule applies to any other generated snapshot file (snapshots/storageLayout/, etc.).
If the build fails (no network/solc), the rebase cannot be completed correctly — say so rather
than leaving any manually-chosen hashes in place.

Before Committing Contract Changes Copy Chapter

1. just test-dev — zero test failures (fast lite-profile iteration). While iterating on a
   specific change, narrow the run with forge's filters to avoid the whole suite, e.g.
   just test-dev --match-contract OptimismPortal2_Test or
   just test-dev --match-test test_finalizeWithdrawalTransaction_succeeds. Run the unfiltered
   just test-dev (and just test, the full-optimization variant CI runs) before opening the PR.
2. just pr — full pre-PR suite: build, lint, all checks.
3. Bump the contract version if bytecode changed (once per PR, not per commit — PRs are
   squash-merged).
4. Review with a security focus — these contracts secure real value.

Ai Deletion Review (`docs/ai/deletion-review.md`) Copy Section

Deletion Review

Method for reviewing a diff that deletes externally observable names or state
writes. Pairs with the deletion-reviewer agent (.claude/agents/deletion-reviewer.md);
under a harness without that agent, work through this guide directly.

When this review applies Copy Chapter

The diff removes any of:

• a public symbol: type, function, event, enum variant, interface method, parameter
• a wire name: RPC method, JSON response field, WS subscription
• a metric name or a metric label value
• a config key, CLI flag, or env var
• a test or subtest name

Deletions fail differently from additions: the compiler proves that no code still
needs the removed thing, and generic code review then stops there. The two checks below
cover what neither proves.

Check 1: the reference sweep goes beyond code Copy Chapter

Build a deletion inventory in both code form and string form (JSON keys, metric
label values, method names, subtest names), then sweep the whole tree. Reference sites
that no compiler sees, in rough order of how often they are missed:

1. Public docs (docs/public-docs/): field lists and example payloads — a JSON
   example embeds a wire field a second time, inside a code fence.
2. Grafana dashboards and monitoring config (**/grafana/**/*.json): a removed
   metric or label value leaves a panel charting a permanently empty series. When
   dashboards exist in duplicated variants, keep them byte-identical.
3. CI config, justfiles, workflows: test names, binary names, package lists —
   these are enumerated strings that silently skip or break when a name changes.
4. READMEs, compose files, scripts.

Classify every hit into exactly one of:

• must-update — fix in the same PR;
• deliberate survivor — e.g. a shared Go type another service still populates, or
  an enum value kept for wire compatibility; state the reason in the PR;
• same-name, different concept — verify the boundary and leave it alone. Names are
  overloaded: the same word can label a chain head in one subsystem and a per-message
  validation threshold in another. The sweep must not overreach into live functionality
  that shares the name; when the boundary is subtle, record it in the PR description.

Check 2: deleted writes — prove *when* the survivors fire, not *whether* they exist Copy Chapter

The subtlest deletion bug: removed code was one of several writers to state that
survives (a status field, tracker, metric, head label), and review "confirms" safety by
observing that other writers exist. Existence is not coverage.

For each deleted write:

1. Enumerate the surviving writers of the same state.
2. For each, establish the exact firing conditions — triggering event, guards, mode.
3. Prove the union covers every window the deleted writer covered. The windows that get
   missed: startup/initialization, sync modes (EL/snap sync, before derivation
   runs and forkchoice updates are gated), resets, reorgs (writers that must
   move a value backward), and error/halt paths.

An uncovered window means the value goes silently stale exactly when operators or
downstream services (health monitors, dashboards) are watching it. If the old coupling
was incidental, make the new coupling explicit rather than restoring the deleted path.

Tests for the fix must pin the semantics, not just the happy case: if the write must
also move a value backward, assert that, or a later "hardening" to advances-only
reintroduces the staleness.

Consequential cleanups Copy Chapter

• Now-unproducible code: error variants or branches whose only producer was
  deleted. Delete them with the producer.
• Dead parameters: values threaded through interfaces that nothing reads after the
  removal — shrink the signatures in the same PR.
• Orphaned duplicates: the deleted code may have been the only reason a local
  duplicate of an upstream type or helper existed (a re-declared error type, a copied
  parser). Symbol greps for the deleted names miss these; ask what the deleted code
  justified, not just what it referenced.
• Vacuous tests: an assertion on a removed field can start comparing zero-to-zero
  and pass forever. Prefer making the removed concept an explicit error over returning
  a zero value. When a removed assertion is replaced, prove the replacement can fail:
  temporarily invert the property it guards (e.g. add deny_unknown_fields to test a
  lenient-parse contract) and watch it go red — a test that cannot fail by construction
  (asserting what the type system already guarantees) protects nothing.
• Wire compatibility: removed RPC/JSON fields parse as zero values in lenient
  clients — trace what each in-repo consumer does with that zero, and disclose the
  removal (breaking-change marker + migration note) for out-of-repo readers.

Dependency and workspace fallout Copy Chapter

Deletions reach build metadata in ways no compiler or clippy run flags — every green
check stays silent on all of the following:

• Orphaned dependencies: deleting a file or module can strip a crate's last use of
  a dependency. Grep for every symbol the deleted file imported — all of them, no
  "certainly still used" shortcuts — and run the unused-dependency gate
  (cargo +nightly udeps --release --workspace --all-features --all-targets, the CI
  command) locally; it is the only check that catches this class.
• Feature-forwarding removal: when the removed dependency carried entries in the
  crate's [features] lists ("dep/feature" forwards), verify each downstream
  consumer enables the forwarded features itself — the one that silently relied on the
  transitive enable is the finding.
• Stale feature-list strings: "dep/feature" entries whose enabling code was
  deleted survive symbol greps (they name the dependency, not the symbol) and no
  tooling flags them. Sweep [features] sections for the deleted crate and feature
  names explicitly.
• Separate-workspace lockfiles: workspaces that path-depend on a changed crate
  (e.g. the SP1 guest programs workspace) resolve independently. Regenerate their
  lockfiles (CI gates on freshness — just lock-sp1-guest /
  just check-sp1-guest-lock) and compile the affected consumers under that
  workspace's own resolution (--manifest-path), not the root workspace's; a crate
  that relied on a now-gone transitive feature enable only fails there.

False-positive traps Copy Chapter

• Shared types: a field removed from one implementation's output may legitimately
  remain in a shared struct that another service still populates. Removing it there is
  a separate, wider change — do not flag the survivor as a leftover.
• Overloaded names: see "same-name, different concept" above; a grep hit is a
  question, not a finding.
• Duplicated artifacts: paired dashboards or mirrored configs must be updated
  together; flagging only one file is an incomplete finding.

Ai Deposit Review (`docs/ai/deposit-review.md`) Copy Section

Reviewing deposit derivation and execution

This area guide covers deposit transactions from the L1 deposit contract to the L2 receipt.
It pairs with the deposit-reviewer agent.

Read spec-driven-review.md in full before this guide.
Read execution-layer.md for the execution-layer model.

This guide owns deposit scope, code navigation, and domain checks.
The shared guide owns the review process, evidence contract, output, and mapping validation.
Neither guide defines protocol behavior.

Scope Copy Chapter

Review these behaviors:

• TransactionDeposited log decoding and the derived deposit fields.
• Source-hash computation for every deposit domain.
• Deposit transaction encoding and decoding, including the 0x7E typed envelope.
• L1 attributes deposit construction and its calldata for each fork.
• Network upgrade transactions that derivation generates as deposits.
• The unconditional mint and its position relative to execution rollback. The mint is the only path that creates L2 ETH with no L2 source.
• Deposit execution rules that differ from a type-2 transaction.
• Nonce handling, including the increment on failure.
• Gas limits, intrinsic gas, the block gas pool, and fork gas caps.
• Fee exemptions, including base fee, priority fee, L1 cost, operator fee, and refunds.
• Deposit receipt fields and their fork-gated presence.
• OptimismPortal deposit creation, address aliasing, and guaranteed gas.

Do not review these areas unless changed behavior crosses their boundary:

• Batch decoding and validation.
• Channel and frame handling.
• Non-deposit transaction execution.
• Withdrawal proving and finalization.
• Dispute game logic.

Specification sources Copy Chapter

Start from Deposits.
The base page states the wire format, source hashes, execution rules, receipt fields, and the deposit contract.

Fork documents amend these rules.
Search every applicable specs/protocol/<fork>/ directory for touched concepts.
Do not limit the search to deposits.md.

At minimum, check these amendments:

Each fork that adds a network upgrade transaction adds deposit rules.
Read the full upgrade-transaction section of that fork, including every field value and the intent string.

Upgrade-deposit rules do not always live under specs/protocol/<fork>/.
Recent forks build their upgrade deposits from a shared bundle format instead of per-fork constants.
Read these two pages as well, for every fork from Karst onward:

• L2 upgrades, execution for the bundle format, the intent prefix rule, the sender rule, and the gas allocation.
• Interop derivation for the Lagoon activation deposits and the dependency-set conditional deposits.

Guaranteed gas market states the L1 gas purchase and the per-block gas bound.

One upgrade deposit carries a non-zero mint.
Treat the bundle data as a mint source, not as static configuration.

Specification-to-code map Copy Chapter

This mapping belongs in the monorepo because implementation names change independently from protocol behavior.
Each entry names a Go package, a Rust crate, or a contract, plus one or more anchor symbols in it.
Find each anchor with a repository grep, then follow affected callers and callees.
The anchors are entry points, not a complete list of relevant files.

Go packages are paths relative to the repository root.
Rust entries use crate names. Contract entries use contract names.

This repository owns the canonical Rust deposit types.
It does not vendor them. op-alloy-consensus holds the wire format and the source-hash rules, and Kona imports both.

The fault-proof executor holds no separate deposit execution rules.
It uses alloy-op-evm and op-revm, so an execution finding usually affects both clients.

The receipts-root encoding is the exception.
Three implementations reproduce it: op-node in Go, reth-optimism-consensus, and kona-executor.
Each one applies the Regolith-to-Canyon nonce strip with its own fork predicate.
Compare all three when a change touches the deposit receipt.

Fork gates live in alloy-op-hardforks and in op-node/rollup.
op-revm maps each OP fork onto an L1 specification identifier.

Methods in op-revm carry UPSTREAM-MIRROR comments.
Each comment names the upstream revm function that the override copies.
Use those names to compare an override with its upstream source.

Existing parity tests Copy Chapter

Check whether a change needs a new case in one of these:

Inherited rules Copy Chapter

The specification defines deposit execution by difference.
It states that a deposit is processed "exactly like a type-2 (EIP-1559) transaction, with the exception of" a listed set.

This form has produced real consensus bugs.
An upstream L1 change can be behavior-preserving on L1 and unsafe on the OP Stack, because an OP exception removes the L1 invariant that made the change safe.

Apply this rule when the specification inherits L1 behavior:

• Name the exact upstream rule set and its version.
• Enumerate the stated OP differences.
• For each difference, ask which L1 invariant it removes.
• Check whether the implementation still relies on that removed invariant.

Do not treat model knowledge of L1 behavior as the inherited rule set.
Read the upstream rule or its implementation at the reviewed revision.

When to run this reviewer Copy Chapter

Run this reviewer when a change can alter a behavior in the scope above.
A change in a mapped path or its dependencies is a strong signal.
Also run it for these changes:

• A new network upgrade transaction, or a change to an existing one.
• A change to the L1 attributes transaction or its calldata.
• A fork that changes gas caps, intrinsic gas, or the gas pool.
• A change to transaction type dispatch, RLP decoding, or the typed envelope.
• A change to receipt encoding, decoding, or hashing.
• A change to OptimismPortal, address aliasing, or resource metering.
• An upstream revm, alloy, or reth bump that touches transaction execution, gas, or receipts. See reth-update-review.md for the drift method.
• A Kona client release or a prestate change that contains mapped changes.

Deposit analysis Copy Chapter

Trace a deposit from the L1 log through the L2 receipt.
Follow the shared guide to prove each implementation's behavior.
Add one output to the list it gives: the receipt fields that the path writes.

Cross-component values Copy Section

A deposit crosses derivation, execution, and the receipt.
A value that agrees inside one component can still disagree across the boundary.

Check that these values agree end to end:

• The derived gas and the gas the execution layer applies.
• The derived mint and the balance increase.
• The nonce used for contract address derivation and the depositNonce in the receipt.
• The gas the execution output reports and the gas the block pool subtracts.
• The transaction hash that each implementation computes for the same deposit.

Domain checks Copy Chapter

Apply these checks to any changed deposit behavior.

Mint and value Copy Section

• mint is uint256 in the wire format. Check every narrower internal type.
• The mint applies before execution and survives a failed deposit.
• The rollback point is after the mint, not before it.
• A failed value transfer produces a failed receipt, not a dropped deposit.

Nonce Copy Section

• The from nonce increments once, including on failure.
• The receipt records the nonce from before execution.
• A rollback must not leave a second increment or lose the first.
• Contract creation uses the recorded nonce, not zero.

Gas Copy Section

• Deposits buy gas on L1 and never refund it.
• The deposit gas limit is exempt from the EIP-7825 transaction gas cap after Karst.
• Intrinsic gas still applies.
• The block gas pool still applies.
• Pre-Regolith gas accounting differs, and isSystemTx changes it again.
• Check the cap arithmetic order. min(limit - intrinsic, cap) and min(limit, cap) - intrinsic differ only when the cap binds.

Fees Copy Section

• No base fee, priority fee, L1 cost, or operator fee applies to a deposit.
• The fee recipient receives nothing from a deposit.
• Total base fee accounting does not change.
• A deposit is not eligible for a Lagoon post-exec refund.
• A post-exec payload entry that targets a deposit makes the block invalid.

Receipt Copy Section

• depositNonce and depositReceiptVersion presence is fork-gated, and the version must be 1.
• The consensus receipt encoding and the receipt hash must match the fork rule.
• The deposit receipt RLP carries the status, cumulativeGasUsed, the bloom, the logs, depositNonce and depositReceiptVersion. The Go receipt struct also holds the L1 fee fields, which never reach it. A client difference in those fields misses the receipts root but is still a cross-client divergence.
• cumulativeGasUsed reflects metered gas after Regolith.

Decoding and dispatch Copy Section

• The 0x7E prefix identifies a deposit. No other prefix may produce one.
• A prefixless or untyped body must not reach the deposit decoder through a fallback path.
• Field count, field order, and to as null against zero are distinct cases.
• Non-canonical RLP, truncation, and trailing bytes each need a defined outcome.
• Network, pooled, and consensus decode paths can differ. Check each one.

Derivation Copy Section

• Each source-hash domain uses the stated constant and the stated preimage.
• The log index is the index in the whole block, not in the transaction.
• The L1 attributes deposit is always first, and user deposits follow.
• User deposits appear only in the first L2 block of an epoch.
• Upgrade deposits appear only on the activation block, in the stated order.
• The intent string of each upgrade deposit must match the specification byte for byte.

Contracts Copy Section

• Address aliasing adds the constant with uint160 overflow.
• A contract creation deposit with a non-zero to must revert.
• Guaranteed gas must bound the total deposit gas in one L1 block.

Sibling paths in deposits Copy Chapter

The shared guide requires a rule-list diff against sibling paths.
In this area the sibling pairs are:

• The L1 attributes deposit against a user deposit, in the same client.
• An upgrade deposit against a user deposit, in the same client.
• The derivation-side field construction against the execution-side field use.
• The consensus decode path against any network or pooled decode path.
• The same rule list in op-node against the matching list in Kona.
• The execution rule set in op-reth against the rule set in the fault-proof executor.

Adversarial boundaries Copy Chapter

A deposit is permissionless. Any L1 account can create one.
The attacker controls to, value, mint, gas, data, and the creation flag, within the portal limits.

Check these boundaries:

• Zero, maximum, and one-past-maximum gas, including the guaranteed gas bound.
• A gas limit above and below the EIP-7825 cap.
• mint and value at uint256 maximum, and at every internal type boundary.
• Empty data, and data at the L1 size bound.
• Contract creation with empty init code.
• A deposit that targets a precompile.
• A deposit that reverts, runs out of gas, or fails the value transfer.
• A deposit in the first and in a later block of an epoch.
• A deposit in the fork activation block itself.

Dismissal checks Copy Chapter

Apply the shared dismissal checks first.
These deposit cases extend them:

• The portal already bounds the value, so the L2 path cannot reach it.
• The difference appears only before the fork that activates the rule.
• A later guard rejects the input before the suspected operation.

Ai Derivation Batch Review (`docs/ai/derivation-batch-review.md`) Copy Section

Reviewing derivation batch decoding and validation

This area guide covers batcher-controlled data between complete channel bytes and accepted L2 batch inputs.
It pairs with the derivation-batch-reviewer agent.

Read spec-driven-review.md in full before this guide.
Read derivation.md for the pipeline model and general derivation rules.

This guide owns derivation scope, code navigation, and domain checks.
The shared guide owns the review process, evidence contract, output, and mapping validation.
Neither guide defines protocol behavior.

Scope Copy Chapter

Review these behaviors:

• Decompression of complete channel data and enforcement of decompressed size limits.
• Batch type dispatch and singular-batch RLP decoding.
• Span-batch prefix, payload, bitlist, transaction, and varint decoding.
• Conversion from a raw span batch into derived block inputs.
• Holocene span decomposition and singular-batch streaming.
• Singular and span semantic validation.
• Fork-gated transaction types, compression formats, limits, and validation rules.
• Batch overlap checks against the safe chain.
• The resulting accept, drop, past, future, undecided, or error outcome.

Do not review these areas unless changed behavior crosses their boundary:

• Batcher transaction retrieval, frame parsing, or channel assembly.
• Deposit derivation and payload-attributes construction.
• Execution-layer transaction processing.
• General safe-head advancement or pipeline resets.
• Batcher encoding policy and compression efficiency.

Encoding code remains useful for round-trip and canonicality checks.
Do not report encoder-only findings unless they change data that a verifier accepts.

Specification-to-code map Copy Chapter

This mapping belongs in the monorepo because repository paths change independently from protocol behavior.
Treat each path as a starting point, then follow affected callers and callees.

Kona paths are relative to rust/kona/crates/protocol/ unless they start with rust/kona/.
All other paths are relative to the repository root.

Fork documents amend the base rules.
Search all files under each applicable specs/protocol/<fork>/ directory for touched concepts.
Do not limit this search to derivation.md.
For example, Delta uses span-batches.md, and Lagoon uses post-exec.md for transaction acceptance.
At minimum, check Delta, Fjord, Holocene, and any later fork that changes transaction acceptance.

When to run this reviewer Copy Chapter

Run this reviewer when a change can alter a behavior in the scope above.
A change in a mapped path or its dependencies is a strong signal.
Also run it for these changes:

• A Kona client release that contains mapped changes.
• A rollup configuration field used by mapped code.
• A new batch format, compression format, transaction type, or derivation fork gate.
• A protocol change that modifies a mapped specification section.
• A fix for malformed batch data, decoder panics, or cross-client disagreement.

Derivation analysis Copy Chapter

Trace complete channel bytes through the final batch outcome.
Trace op-node and Kona independently.
For each affected path, determine:

• Which byte strings it accepts.
• Which decoded values it produces.
• Which limit it applies before allocation or iteration.
• Which fork condition it uses.
• Which semantic validity outcome it returns.
• Whether partial state survives an error.

Compare both implementations with the specification first.
Then compare their accept sets and outputs with each other.
Follow derivation.md for wire-format parity and codec-testing guidance. For specification-driven reviews, the shared authority policy takes precedence over that section's op-node tie-breaker: report unresolved divergences with a specification-gap finding rather than selecting a client as correct.

Report the input class that a difference covers, not one example input.
Name the first byte range, the field, or the failure mode that produces the same outcome.
A single example hides the reach of the difference from the reader.

Known derivation issues Copy Chapter

When applying the shared triage process, also check ethereum-optimism/optimism#22854 and its sub-issues.

Sibling paths in derivation Copy Chapter

The shared guide requires a rule-list diff against sibling paths.
In this area the sibling pairs are:

• Singular-batch validity against span-batch validity, in the same client.
• Pre-Holocene stage behavior against Holocene stage behavior, for the same wire format.
• The same rule list in op-node against the matching list in Kona.

The shared guide also requires the rejection stage for each input.
A structural decode failure can discard a whole channel.
A later derivation failure can discard one batch and keep the channel.

Shared decoder limits Copy Chapter

Both clients depend on third-party decoders for compression and RLP.
A static trace compares the calling code, not the library behind it.
Two libraries can disagree about which byte strings are valid.

Name the library on each side when a review touches these paths.
State in the review receipt that the library accept sets were not compared.
Differential testing owns that comparison.

Adversarial boundaries Copy Chapter

Batcher-provided bytes are adversarial input.
Check zero, one, maximum, and one-past-maximum values where the format permits them.

Also check:

• Truncation before every fixed-width and variable-width field ends.
• Declared counts larger than the remaining input.
• Integer conversion, addition, subtraction, and multiplication boundaries.
• Empty batches and zero transaction counts.
• Bitlists whose byte length does not match their element count.
• Non-minimal but valid protobuf uvarint encodings.
• Unknown batch and transaction type bytes.
• Transaction type prefixes through decode and reassembly.
• Trailing bytes when the surrounding format permits another batch.
• Span batches that cross a fork boundary.
• Spans that overlap the safe chain partially or completely.
• Legacy and Holocene processing of the same wire format.

Defensive decoder guidance Copy Chapter

This guidance helps the reviewer assess an implementation.
It does not add a protocol invariant to the specification.

The specification normally defines valid results and invalid-input outcomes.
It need not name language failures such as Rust panics or Go slice-bound faults.
An implementation cannot produce its required outcome if adversarial input terminates that path first.

Treat these operations as review leads:

• Unchecked indexing, slicing, split_at, cursor advances, or fixed-width conversions.
• unwrap, expect, panic, or assertions reachable from batcher-controlled data.
• Length-derived allocation or loops before the relevant protocol limit is enforced.
• Arithmetic on decoded counts before checked conversion and bounds validation.

Do not report the operation alone.
Show concrete input, reachability, the failing operation, and the missing guard.

Classify the result from its evidence:

• If the specification defines an outcome, premature termination is a specification violation.
• If the specification is silent, report an implementation-safety finding.
• Report a specification gap only when two consensus outcomes remain plausible.

Do not demand a specification sentence that says an implementation must not panic.

Derivation dismissal checks Copy Chapter

Apply the shared dismissal checks first.
These decoder cases extend them:

• A decoded count is bounded before conversion or allocation.
• Callers prove the internal invariant behind a suspected panic.
• The path is encoder-only.

Ai Derivation (`docs/ai/derivation.md`) Copy Section

Derivation Pipeline Development

This document provides guidance for AI agents working with the derivation pipeline
in the Optimism monorepo — the logic that reconstructs L2 state from L1 data.
See go-dev.md for general Go build, test, and lint workflow and
rust-dev.md for the Rust workflow.

The same derivation logic is implemented twice:

• Go (op-node): the reference consensus-layer node, under op-node/rollup/.
• Rust (kona): kona-node (rust/kona/bin/node) is the Rust consensus-layer node;
  kona-client (rust/kona/bin/client) is the Rust fault proof program. Both drive the
  same derivation pipeline, implemented in the kona-derive crate
  (rust/kona/crates/protocol/derive).

Scope Copy Chapter

The derivation pipeline lives primarily under op-node/rollup/ (Go) and
rust/kona/crates/protocol/derive (Rust). It reads deposits, batches, and channel data from
L1 and applies them to produce the L2 chain.

Key Concepts Copy Chapter

The pipeline is a series of stages, each pulling from the one below it. From L1 data to L2
blocks:

1. L1 block traversal: for each L1 block, read the deposit transaction logs and the
   SystemConfig update logs (from the receipts), and collect the batcher transactions
   addressed to the batch inbox — their payload is either calldata or blobs depending on the
   chain's data-availability mode.
2. Frame extraction: parse the batcher transactions into frames.
3. Channel assembly: assemble frames into channels (a channel may span multiple frames and
   multiple L1 blocks).
4. Channel decompression: decompress each complete channel into a stream of batches.
5. Payload-attributes derivation: derive L2 payload attributes from the batches, prepending
   the deposit transactions and the L1-info/system-config deposit for the block.
6. Consolidation vs. execution: if the existing unsafe chain already matches the derived
   payload attributes (consolidation), the block is promoted to safe and derivation
   progresses to the next batch / L1 block without re-executing. Otherwise the payload
   attributes are sent to the execution layer to build and execute the block. In Go this
   matching lives in op-node/rollup/attributes/ (AttributesMatchBlock).

Other recurring concerns:

• Safe head advancement: updating the safe L2 head as derivation progresses.
• Reorg handling: rewinding derivation state on L1 reorgs.

Rollup config Copy Chapter

Both clients' derivation rules are configured by consensus parameters in rollup.Config (Go) /
RollupConfig (Rust), which can be loaded from the
superchain-registry. Adding a
field that comes from the registry means wiring it through every ingestion enumeration on
both clients — not just the config struct and the op-deployer/deploy-config
(DeployConfig.RollupConfig) path:

• op-node (Go): the TOML-decoded superchain.HardforkConfig (op-core/superchain) and
  the superchain.ChainConfig → rollup.Config conversion in op-node/superchain/superchain.go
  (applyHardforks / rollupConfigFromRegistry).
• kona (Rust): HardForkConfig / ChainConfig::as_rollup_config
  (rust/kona/crates/protocol/genesis).

Two guards fail loudly on a field left unwired:

• Strict decoding rejects registry keys that no struct field models —
  jsonutil.DecodeTOMLStrict (Go, used by op-core/superchain) and
  #[serde(deny_unknown_fields)] (kona's ChainConfig / HardForkConfig). A registry bump that
  adds an unmodeled field fails to load until the struct consumes it.
• A reflection completeness test (TestRollupConfigFromRegistry_AllFieldsSet) asserts every
  rollup.Config field is populated from a fully-populated ChainConfig, catching a field that
  is modeled but never copied in the conversion.

Invariants Copy Chapter

• Deterministic derivation: the same L1 data always produces the same L2 chain.
  No randomness, no time-dependent behavior.
• Safe head bound: the safe head never advances past finalized L1 data. Safe head
  advancement must verify L1 finality status.
• Deposit ordering: all deposits are processed in their L1 inclusion order. Batch
  processing must preserve this ordering.
• Channel timeout: channel timeout is enforced to prevent memory exhaustion. Channel
  timeout values must not be modified without protocol review.
• Reorg unwinding: reorg handling must correctly unwind all derived state.

Validate transactions after span decomposition Copy Section

For post-Holocene derivation, transaction-list validation belongs to the batch stage, after a span
batch has been decomposed and its singular batches are streamed one at a time. In particular,
activation-gated transaction rules must use the streamed singular batch's timestamp. Do not inspect
transactions while decoding or constructing a SpanBatch, and keep post-Holocene whole-span
processing limited to prefix and extraction checks. A span may cross a fork boundary; only singular
batches emitted after the safe head are candidates for validation.

Add new per-block transaction rules to checkSingularBatch (op-node) and
SingleBatch::check_batch (kona), where singular batches from both wire formats converge. Rejecting
during DeriveSpanBatch can discard valid later elements before the batch stage has selected the
singular batches that actually apply. The legacy pre-Holocene batch queue has no singular-streaming
batch stage, so it still performs its historical full-span transaction checks. Keep those legacy
checks aligned between op-node and Kona.

Cross-client wire-format parity Copy Chapter

Both clients decode the same batcher-controlled bytes, so their decoders must accept exactly
the same byte set. A byte string that one client decodes and the other rejects splits derivation on
identical L1 data.

• The spec is the reference; op-node is the incumbent. Decide what is correct from the
  specs. op-node additionally defines what OP Mainnet currently does,
  so where the spec is silent or ambiguous its behavior is the tie-breaker — but a decoder that
  contradicts the spec, or looks outright buggy, is a finding to raise rather than something to
  mirror into kona. Either way, take a spec/op-node disagreement to the user before encoding a
  choice in either client.
• Verify a codec's accept-set, don't infer it from the format name. Wire formats come in
  families that differ on exactly the inputs a batcher controls. Span-batch uvarint is a protobuf
  Base128 varint, whose non-minimal encodings are valid; the unsigned-varint crate implements the
  minimal-only multiformats variant instead and rejects them. Span-batch fields go through
  read_uvarint (rust/kona/crates/protocol/protocol/src/batch/varint.rs), a port of Go's
  binary.ReadUvarint. Before trusting any decoder on this path, diff its accept-set against
  op-node's over a generated corpus — a spec citation does not distinguish two families.
• Pin every decision in both suites. When changing either decoder, add the same byte vector to
  the kona and op-node tests so the pair stays locked together.

Testing Requirements Copy Chapter

• Unit tests for every pipeline stage.
• Reorg simulation tests for any change to reorg handling.
• End-to-end derivation tests with synthetic L1 data.
• Benchmark tests for batch-processing throughput.

Ai Dev Workflow (`docs/ai/dev-workflow.md`) Copy Section

Development Workflow

Common workflow guidance for AI agents working in the Optimism monorepo. Language-specific details are in go-dev.md and rust-dev.md. For running acceptance tests, see acceptance-tests.md; for writing new ones, see writing-acceptance-tests.md.

Tool Versions Copy Chapter

All tool versions are pinned in mise.toml at the repo root. Always access tools through mise — never install or invoke system-global versions directly. Check mise.toml for current pinned versions when you need to know what's available.

If mise reports the repo isn't trusted, ask the user to run mise trust — never trust it automatically.

Setup Copy Section

Run mise install to install all pinned tools (just, gotestsum, forge, etc.). AI agent shells typically do not have mise activated, so prefix commands with mise exec -- to ensure tools are on PATH:

mise exec -- just <target>

Then install the git hooks (once per clone — the setting is shared across all of a
clone's worktrees):

mise exec -- just install-git-hooks

This points core.hooksPath at .githooks/. The pre-push hook blocks pushing
unformatted Rust (mirroring CI's rust-fmt gate), so run it before you push any
Rust change.

Build System Copy Chapter

The repo uses Just as its build system. Shared justfile infrastructure lives in justfiles/. Each component has its own justfile — run just --list in any directory to see available targets.

Before Every PR Copy Chapter

After the language-specific commit checks (lint, test), use
pr-guidelines.md: the review agents that apply to the diff,
tests, the rebase on develop, and the content of the PR description.

CI Copy Chapter

Some tests require CI-only environment variables and are skipped locally. Check the test code for environment variable guards if a test behaves differently than expected.

Ai Devfeatures (`docs/ai/devfeatures.md`) Copy Section

DevFeatures System

Reference for the DevFeatures bitmap system. The bitmap is transitional infrastructure that lets in-development features ride alongside production code without a full hardfork. It is expected to disappear once each feature it gates either ships as a real hardfork or is abandoned.

A. What it is Copy Chapter

A 32-byte bitmap (bytes32 on chain, common.Hash in Go) where each feature occupies its own nibble — 0x...01, 0x...10, 0x...100, etc. — giving 64 concurrent feature slots. Defined identically on both sides:

• Go: op-core/devfeatures/devfeatures.go — flag constants, IsDevFeatureEnabled(bitmap, flag), EnableDevFeature(bitmap, flag)
• Solidity: packages/contracts-bedrock/src/libraries/DevFeatures.sol — same constants, same predicate

The two sides are independent literals with no compile-time sync check — a mismatch silently diverges Go and Solidity behavior. The constant values are canonical in those two files; don't trust copies elsewhere.

Active flags:

The predicate is a bitwise AND ((bitmap & flag) == flag && flag != 0) — except that IsDevFeatureEnabled short-circuits to true for SuperRootGamesMigration, which is enabled by default on both the Go and Solidity sides. The bitmap no longer acts as a circuit breaker for it; removal is tracked in #21662.

Adding a new dev feature: the full checklist lives in the DevFeatures.sol natspec — both constant files, the env-var reader in scripts/libraries/Config.sol, the test assembler in test/setup/FeatureFlags.sol, and the CI &features_matrix anchor in .circleci/continue/main.yml all need updating; there is no compile-time link between them.

B. Inputs — where operators supply the bitmap Copy Chapter

The bitmap has two operator-facing input surfaces, both in op-deployer:

1. CLI flag on op-deployer bootstrap implementations

   • --dev-feature-bitmap (env: DEPLOYER_DEV_FEATURE_BITMAP), defined in op-deployer/pkg/deployer/bootstrap/flags.go
   • Raw 32-byte hex; default empty
   • Flows into ImplementationsConfig.DevFeatureBitmap and on into DeployImplementationsInput for L1 implementation deployment.
   • When the ZK bit is enabled, Ethereum mainnet and Sepolia default to Succinct's v6.1.0 PLONK verifier, resolved by standard.SP1VerifierFor. --sp1-verifier-address (env: DEPLOYER_SP1_VERIFIER_ADDRESS) overrides that release input and is required on other L1 networks.

2. Intent file (globalDeployOverrides.devFeatureBitmap)

   • Schema field on Intent, op-deployer/pkg/deployer/state/intent.go
   • Lives in the operator's intent TOML/JSON
   • Read by the L2 genesis pipeline.
   • All of the following applies only when apply deploys new implementations. With a predeployed OPCM (opcmAddress set), the implementations already exist and ValidateInputs rejects sp1Verifier outright, so those operators must not set the override.
   • A live ZK-enabled apply selects the same release-approved verifier as bootstrap on Ethereum mainnet and Sepolia; other L1 networks must set globalDeployOverrides.sp1Verifier, which always wins where it is set. Enabling ZK stays an explicit operator choice — the default only picks the verifier, never the feature.
   • Both surfaces read the mapping from standard.SP1VerifierFor, so bootstrap and apply can never drift.
   • op-deployer/pkg/deployer/standard/sp1-verifier.json records, per chain, the VERIFIER_HASH() of that verifier, the PLONK circuit it accepts proofs for; standard.SP1VerifierHashFor reads it. TestApplyDefaultsSP1VerifierOnSepolia holds it to the chain, VerifyOPCM re-checks it at release, and op-zk-proposer's release-pin test holds the linked sp1-sdk to it, so bumping sp1-sdk to a new circuit fails CI until the address and the file move together. The proposer also derives the hash from its SDK at runtime and pauses creation and skips proving for any adapter whose verifier hash differs.
   • The selected raw verifier is recorded in deployment state (State.SP1Verifier) and never written back into intent. A resumed deployment reuses the recorded address rather than re-resolving the default, so upgrading op-deployer mid-deployment cannot swap the verifier under a chain.
   • Genesis deployments never select the release verifier: it does not exist in a generated genesis. They must set sp1Verifier explicitly, or the op-devstack builder can opt into deploying a test raw verifier during genesis.

There is no other production operator-facing surface. op-node, kona, and rollup config do not take a bitmap at runtime.

Developer-only: `op-node/rollup/toggles.go` Copy Section

A third input mechanism, distinct from the bitmap, lives in op-node/rollup/toggles.go. It is a source-code-edit-only developer toggle — not exposed via config, CLI, or env var. The file holds ephemeral Is<Feature>(time) methods on *Config that map an in-development feature to its eventual hardfork timestamp:

func (c *Config) IsL2CM(time uint64) bool {
    return c.IsKarst(time)
}

The file's comment instructs developers to "replace with return false to disable NUT bundle execution during development." This is a temporary scaffold for the active fork scope; entries are removed after the fork is locked.

What it gates is runtime activation timing in op-node (when NUT bundle deposit transactions are emitted at the activation block), which is orthogonal to what the bitmap gates (whether the supporting predeploys and contracts exist on a given chain at all).

Test-only: per-feature controls Copy Section

A separate, test-only assembler exists for Foundry tests and fork scripts. It reads env vars for opt-in features and hardcodes default-on features. It is isolated from the production path — no src/ contract and no production deploy script reads these controls.

• DEV_FEATURE__OPTIMISM_PORTAL_INTEROP
• DEV_FEATURE__ZK_DISPUTE_GAME

Interop and ZK are read via vm.envOr(..., false) in packages/contracts-bedrock/scripts/libraries/Config.sol; devFeatureSuperRootGamesMigration() returns true unconditionally. The only callers are under test/:

• test/setup/FeatureFlags.sol — resolveFeaturesFromEnv() OR-s each enabled flag into devFeatureBitmap
• test/setup/ForkL1Live.s.sol — branches on individual Config.devFeature* returns
• test/L1/OPContractsManagerStandardValidator.t.sol — vm.skip() based on flag state

The env vars and default-on helper exist purely to set up local test fixtures and to skip or branch tests. They never reach a deployed chain. To exercise an opt-in feature in production you must set the bitmap via op-deployer.

C. Composition — how those inputs become a single bitmap Copy Chapter