{"owner":"ethereum-optimism","repo":"optimism","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md"],"skills":{"AGENTS.md":"# Optimism Monorepo\n\nThis is the primary monorepo for the OP Stack, maintained by the Optimism Collective. The OP Stack is a decentralized software stack that powers Optimism and forms the backbone of blockchains like OP Mainnet and Base.\n\n## Improving This Documentation\n\nIf during a session you learn something that would have helped you from the start, suggest updating these docs. Examples:\n\n- User corrects an outdated or wrong command you tried\n- User shows a better way to run tests, build, or debug\n- User explains a pattern or convention not documented here\n- Something you assumed from the docs turns out to be incorrect\n\nWhen this happens, offer to submit the improvement to the relevant file in `docs/ai/` or to this file. If the topic doesn't fit existing docs (e.g., CI workflows, debugging techniques), suggest creating a new focused document. Keep these docs tight and well-scoped rather than sprawling. Small, incremental improvements compound over time.\n\n## Repository Overview\n\n- **Default branch**: `develop` (not `main`)\n- **Commit messages and PR titles**: use the [Scoped Commits](https://scopedcommits.com) format — `<scope>: <description>`, where the scope names the component or area changed (e.g. `op-node: handle unsafe head reorgs`). Do not use Conventional Commits type prefixes (`feat:`, `fix:`, `chore(scope):`, ...). See [CONTRIBUTING.md](CONTRIBUTING.md#commit-messages)\n- **Build system**: migrating from Make to [Just](https://github.com/casey/just) — shared justfile infra lives in `justfiles/`\n\nThis repository contains multiple components spanning different technologies:\n\n### Go Services\n\nThe rollup node software and associated services, including:\n\n- **op-node**: Rollup consensus-layer client\n- **op-batcher**: L2 batch submitter\n- **op-proposer**: L2 output submitter\n- **op-challenger**: Dispute game challenge agent\n- **op-conductor**: High-availability sequencer service\n- **op-supernode**: Multi-chain consensus-layer host that runs multiple OP Stack chains in a single process and performs in-process cross-chain safety verification\n\n### Smart Contracts (`packages/contracts-bedrock`)\n\nSolidity smart contracts for the OP Stack, including the core protocol contracts deployed on L1 and L2.\n\n### Rust Components\n\nThe OP Stack includes significant Rust implementations:\n\n- **kona**: Rust implementation of the OP Stack rollup state transition, including fault proof program and rollup node\n- **op-reth**: OP Stack execution client built on reth\n- **op-alloy**: Rust crates providing OP Stack types and providers for the alloy ecosystem\n- **alloy-op-hardforks** / **alloy-op-evm**: OP Stack hardfork and EVM support for alloy\n\n### Fault Proof System\n\n- **cannon**: Onchain MIPS instruction emulator (in Go)\n- **rust/kona**: Fault proof program — client and host (in Rust)\n\n### Development and Testing Infrastructure\n\n- **op-e2e**: End-to-end testing framework\n- **op-acceptance-tests**: Acceptance test suite\n\n## Subdirectory Instructions\n\nSome subdirectories have their own CLAUDE.md with domain-specific conventions. Read the relevant file before working in that area — do not read them all upfront.\n\n- `rust/kona/CLAUDE.md` — Kona Rust workspace: build commands (`just b/t/l/f`), code style, architecture overview\n- `rust/` — read before working in that area; links to [docs/ai/rust-dev.md](docs/ai/rust-dev.md)\n- `packages/contracts-bedrock/` — read before working in that area; links to [docs/ai/contract-dev.md](docs/ai/contract-dev.md)\n- `op-acceptance-tests/` — read before working in that area; links to [docs/ai/acceptance-tests.md](docs/ai/acceptance-tests.md)\n- `op-node/rollup/derive/` — read before working in that area; links to [docs/ai/derivation.md](docs/ai/derivation.md)\n- `rust/kona/crates/protocol/` — read before working in that area; links to [docs/ai/derivation.md](docs/ai/derivation.md)\n- `.circleci/` and `.github/` — read before editing CI config; links to [docs/ai/ci-config-review.md](docs/ai/ci-config-review.md)\n\n## Additional Documentation\n\nMore detailed guidance for AI agents can be found in:\n\n- [docs/ai/ci-ops.md](docs/ai/ci-ops.md) - CI/CD operations\n- [docs/ai/ci-config-review.md](docs/ai/ci-config-review.md) - Reviewing changes to CI config (`.circleci/`, `.github/workflows/`): gate coverage, required checks, path filtering, caching, plus general CircleCI/GHA best practices\n- [docs/ai/docker.md](docs/ai/docker.md) - Docker image builds: making every external fetch (apt/apk/curl/wget) retry so registry/CDN blips don't flake CI\n- [docs/ai/contract-dev.md](docs/ai/contract-dev.md) - Smart contract development\n- [docs/ai/dispute-game-investigation.md](docs/ai/dispute-game-investigation.md) - Investigating fault dispute games: challenger disagreements, excessive moves, self-contradiction, proposal validity, diagnosing the responsible op-node, and the bond outcome (read-only)\n- [docs/ai/flake-prevention.md](docs/ai/flake-prevention.md) - Guidance for preventing flaky tests\n- [docs/ai/dev-workflow.md](docs/ai/dev-workflow.md) - General development workflow: pinned tools via mise, Just usage, pre-PR checks, and CI caveats\n- [docs/ai/go-dev.md](docs/ai/go-dev.md) - Go service development\n- [docs/ai/rust-dev.md](docs/ai/rust-dev.md) - Rust development (kona, op-reth, alloy crates)\n- [docs/ai/reth-update-review.md](docs/ai/reth-update-review.md) - Reviewing reth/revm/alloy dependency bumps: the risk guide for upstream changes that should force a change in our in-tree op- forks but produce no diff (silent overrides, new defaults/variants, sync drift, consensus-critical math). Pairs with the `reth-update-reviewer` agent\n- [docs/ai/derivation.md](docs/ai/derivation.md) - Derivation pipeline development (op-node, kona-node)\n- [docs/ai/execution-layer.md](docs/ai/execution-layer.md) - Execution layer development (op-reth / EVM, fees, deposits)\n- [docs/ai/fault-proofs.md](docs/ai/fault-proofs.md) - Fault proof system (Cannon, kona-client, dispute games)\n- [docs/ai/devfeatures.md](docs/ai/devfeatures.md) - The `DevFeatures` bitmap system gating in-development smart contract features: where the bitmap is supplied, composed, propagated, and read. Only relevant for contract development and op-deployer — not needed for client (op-node / op-reth / kona) work\n- [docs/ai/acceptance-tests.md](docs/ai/acceptance-tests.md) - Building and running acceptance tests locally\n- [docs/ai/writing-acceptance-tests.md](docs/ai/writing-acceptance-tests.md) - Writing new acceptance tests: DSL patterns, naming, what to avoid\n- [docs/ai/opgeth-decoupling.md](docs/ai/opgeth-decoupling.md) - op-geth decoupling plan: consult when doing any op-geth decoupling work — migrating OP Stack–specific code out of op-geth into `op-core/*`, retiring op-geth-backed execution in tests/tooling, or removing fork-only API uses — so the monorepo can depend on upstream go-ethereum (scope: the whole monorepo — single go.mod; tracking issue #20257)\n\n## External References\n\n- [Optimism Documentation](https://docs.optimism.io)\n- [OP Stack Specifications](https://github.com/ethereum-optimism/specs)\n- [Contributing Guide](CONTRIBUTING.md)\n"},"files":{"AGENTS.md":"# Optimism Monorepo\n\nThis is the primary monorepo for the OP Stack, maintained by the Optimism Collective. The OP Stack is a decentralized software stack that powers Optimism and forms the backbone of blockchains like OP Mainnet and Base.\n\n## Improving This Documentation\n\nIf during a session you learn something that would have helped you from the start, suggest updating these docs. Examples:\n\n- User corrects an outdated or wrong command you tried\n- User shows a better way to run tests, build, or debug\n- User explains a pattern or convention not documented here\n- Something you assumed from the docs turns out to be incorrect\n\nWhen this happens, offer to submit the improvement to the relevant file in `docs/ai/` or to this file. If the topic doesn't fit existing docs (e.g., CI workflows, debugging techniques), suggest creating a new focused document. Keep these docs tight and well-scoped rather than sprawling. Small, incremental improvements compound over time.\n\n## Repository Overview\n\n- **Default branch**: `develop` (not `main`)\n- **Commit messages and PR titles**: use the [Scoped Commits](https://scopedcommits.com) format — `<scope>: <description>`, where the scope names the component or area changed (e.g. `op-node: handle unsafe head reorgs`). Do not use Conventional Commits type prefixes (`feat:`, `fix:`, `chore(scope):`, ...). See [CONTRIBUTING.md](CONTRIBUTING.md#commit-messages)\n- **Build system**: migrating from Make to [Just](https://github.com/casey/just) — shared justfile infra lives in `justfiles/`\n\nThis repository contains multiple components spanning different technologies:\n\n### Go Services\n\nThe rollup node software and associated services, including:\n\n- **op-node**: Rollup consensus-layer client\n- **op-batcher**: L2 batch submitter\n- **op-proposer**: L2 output submitter\n- **op-challenger**: Dispute game challenge agent\n- **op-conductor**: High-availability sequencer service\n- **op-supernode**: Multi-chain consensus-layer host that runs multiple OP Stack chains in a single process and performs in-process cross-chain safety verification\n\n### Smart Contracts (`packages/contracts-bedrock`)\n\nSolidity smart contracts for the OP Stack, including the core protocol contracts deployed on L1 and L2.\n\n### Rust Components\n\nThe OP Stack includes significant Rust implementations:\n\n- **kona**: Rust implementation of the OP Stack rollup state transition, including fault proof program and rollup node\n- **op-reth**: OP Stack execution client built on reth\n- **op-alloy**: Rust crates providing OP Stack types and providers for the alloy ecosystem\n- **alloy-op-hardforks** / **alloy-op-evm**: OP Stack hardfork and EVM support for alloy\n\n### Fault Proof System\n\n- **cannon**: Onchain MIPS instruction emulator (in Go)\n- **rust/kona**: Fault proof program — client and host (in Rust)\n\n### Development and Testing Infrastructure\n\n- **op-e2e**: End-to-end testing framework\n- **op-acceptance-tests**: Acceptance test suite\n\n## Subdirectory Instructions\n\nSome subdirectories have their own CLAUDE.md with domain-specific conventions. Read the relevant file before working in that area — do not read them all upfront.\n\n- `rust/kona/CLAUDE.md` — Kona Rust workspace: build commands (`just b/t/l/f`), code style, architecture overview\n- `rust/` — read before working in that area; links to [docs/ai/rust-dev.md](docs/ai/rust-dev.md)\n- `packages/contracts-bedrock/` — read before working in that area; links to [docs/ai/contract-dev.md](docs/ai/contract-dev.md)\n- `op-acceptance-tests/` — read before working in that area; links to [docs/ai/acceptance-tests.md](docs/ai/acceptance-tests.md)\n- `op-node/rollup/derive/` — read before working in that area; links to [docs/ai/derivation.md](docs/ai/derivation.md)\n- `rust/kona/crates/protocol/` — read before working in that area; links to [docs/ai/derivation.md](docs/ai/derivation.md)\n- `.circleci/` and `.github/` — read before editing CI config; links to [docs/ai/ci-config-review.md](docs/ai/ci-config-review.md)\n\n## Additional Documentation\n\nMore detailed guidance for AI agents can be found in:\n\n- [docs/ai/ci-ops.md](docs/ai/ci-ops.md) - CI/CD operations\n- [docs/ai/ci-config-review.md](docs/ai/ci-config-review.md) - Reviewing changes to CI config (`.circleci/`, `.github/workflows/`): gate coverage, required checks, path filtering, caching, plus general CircleCI/GHA best practices\n- [docs/ai/docker.md](docs/ai/docker.md) - Docker image builds: making every external fetch (apt/apk/curl/wget) retry so registry/CDN blips don't flake CI\n- [docs/ai/contract-dev.md](docs/ai/contract-dev.md) - Smart contract development\n- [docs/ai/dispute-game-investigation.md](docs/ai/dispute-game-investigation.md) - Investigating fault dispute games: challenger disagreements, excessive moves, self-contradiction, proposal validity, diagnosing the responsible op-node, and the bond outcome (read-only)\n- [docs/ai/flake-prevention.md](docs/ai/flake-prevention.md) - Guidance for preventing flaky tests\n- [docs/ai/dev-workflow.md](docs/ai/dev-workflow.md) - General development workflow: pinned tools via mise, Just usage, pre-PR checks, and CI caveats\n- [docs/ai/go-dev.md](docs/ai/go-dev.md) - Go service development\n- [docs/ai/rust-dev.md](docs/ai/rust-dev.md) - Rust development (kona, op-reth, alloy crates)\n- [docs/ai/reth-update-review.md](docs/ai/reth-update-review.md) - Reviewing reth/revm/alloy dependency bumps: the risk guide for upstream changes that should force a change in our in-tree op- forks but produce no diff (silent overrides, new defaults/variants, sync drift, consensus-critical math). Pairs with the `reth-update-reviewer` agent\n- [docs/ai/derivation.md](docs/ai/derivation.md) - Derivation pipeline development (op-node, kona-node)\n- [docs/ai/execution-layer.md](docs/ai/execution-layer.md) - Execution layer development (op-reth / EVM, fees, deposits)\n- [docs/ai/fault-proofs.md](docs/ai/fault-proofs.md) - Fault proof system (Cannon, kona-client, dispute games)\n- [docs/ai/devfeatures.md](docs/ai/devfeatures.md) - The `DevFeatures` bitmap system gating in-development smart contract features: where the bitmap is supplied, composed, propagated, and read. Only relevant for contract development and op-deployer — not needed for client (op-node / op-reth / kona) work\n- [docs/ai/acceptance-tests.md](docs/ai/acceptance-tests.md) - Building and running acceptance tests locally\n- [docs/ai/writing-acceptance-tests.md](docs/ai/writing-acceptance-tests.md) - Writing new acceptance tests: DSL patterns, naming, what to avoid\n- [docs/ai/opgeth-decoupling.md](docs/ai/opgeth-decoupling.md) - op-geth decoupling plan: consult when doing any op-geth decoupling work — migrating OP Stack–specific code out of op-geth into `op-core/*`, retiring op-geth-backed execution in tests/tooling, or removing fork-only API uses — so the monorepo can depend on upstream go-ethereum (scope: the whole monorepo — single go.mod; tracking issue #20257)\n\n## External References\n\n- [Optimism Documentation](https://docs.optimism.io)\n- [OP Stack Specifications](https://github.com/ethereum-optimism/specs)\n- [Contributing Guide](CONTRIBUTING.md)\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"# Optimism Monorepo\n\nThis is the primary monorepo for the OP Stack, maintained by the Optimism Collective. The OP Stack is a decentralized software stack that powers Optimism and forms the backbone of blockchains like OP Mainnet and Base.\n\n## Improving This Documentation\n\nIf during a session you learn something that would have helped you from the start, suggest updating these docs. Examples:\n\n- User corrects an outdated or wrong command you tried\n- User shows a better way to run tests, build, or debug\n- User explains a pattern or convention not documented here\n- Something you assumed from the docs turns out to be incorrect\n\nWhen this happens, offer to submit the improvement to the relevant file in `docs/ai/` or to this file. If the topic doesn't fit existing docs (e.g., CI workflows, debugging techniques), suggest creating a new focused document. Keep these docs tight and well-scoped rather than sprawling. Small, incremental improvements compound over time.\n\n## Repository Overview\n\n- **Default branch**: `develop` (not `main`)\n- **Commit messages and PR titles**: use the [Scoped Commits](https://scopedcommits.com) format — `<scope>: <description>`, where the scope names the component or area changed (e.g. `op-node: handle unsafe head reorgs`). Do not use Conventional Commits type prefixes (`feat:`, `fix:`, `chore(scope):`, ...). See [CONTRIBUTING.md](CONTRIBUTING.md#commit-messages)\n- **Build system**: migrating from Make to [Just](https://github.com/casey/just) — shared justfile infra lives in `justfiles/`\n\nThis repository contains multiple components spanning different technologies:\n\n### Go Services\n\nThe rollup node software and associated services, including:\n\n- **op-node**: Rollup consensus-layer client\n- **op-batcher**: L2 batch submitter\n- **op-proposer**: L2 output submitter\n- **op-challenger**: Dispute game challenge agent\n- **op-conductor**: High-availability sequencer service\n- **op-supernode**: Multi-chain consensus-layer host that runs multiple OP Stack chains in a single process and performs in-process cross-chain safety verification\n\n### Smart Contracts (`packages/contracts-bedrock`)\n\nSolidity smart contracts for the OP Stack, including the core protocol contracts deployed on L1 and L2.\n\n### Rust Components\n\nThe OP Stack includes significant Rust implementations:\n\n- **kona**: Rust implementation of the OP Stack rollup state transition, including fault proof program and rollup node\n- **op-reth**: OP Stack execution client built on reth\n- **op-alloy**: Rust crates providing OP Stack types and providers for the alloy ecosystem\n- **alloy-op-hardforks** / **alloy-op-evm**: OP Stack hardfork and EVM support for alloy\n\n### Fault Proof System\n\n- **cannon**: Onchain MIPS instruction emulator (in Go)\n- **rust/kona**: Fault proof program — client and host (in Rust)\n\n### Development and Testing Infrastructure\n\n- **op-e2e**: End-to-end testing framework\n- **op-acceptance-tests**: Acceptance test suite\n\n## Subdirectory Instructions\n\nSome subdirectories have their own CLAUDE.md with domain-specific conventions. Read the relevant file before working in that area — do not read them all upfront.\n\n- `rust/kona/CLAUDE.md` — Kona Rust workspace: build commands (`just b/t/l/f`), code style, architecture overview\n- `rust/` — read before working in that area; links to [docs/ai/rust-dev.md](docs/ai/rust-dev.md)\n- `packages/contracts-bedrock/` — read before working in that area; links to [docs/ai/contract-dev.md](docs/ai/contract-dev.md)\n- `op-acceptance-tests/` — read before working in that area; links to [docs/ai/acceptance-tests.md](docs/ai/acceptance-tests.md)\n- `op-node/rollup/derive/` — read before working in that area; links to [docs/ai/derivation.md](docs/ai/derivation.md)\n- `rust/kona/crates/protocol/` — read before working in that area; links to [docs/ai/derivation.md](docs/ai/derivation.md)\n- `.circleci/` and `.github/` — read before editing CI config; links to [docs/ai/ci-config-review.md](docs/ai/ci-config-review.md)\n\n## Additional Documentation\n\nMore detailed guidance for AI agents can be found in:\n\n- [docs/ai/ci-ops.md](docs/ai/ci-ops.md) - CI/CD operations\n- [docs/ai/ci-config-review.md](docs/ai/ci-config-review.md) - Reviewing changes to CI config (`.circleci/`, `.github/workflows/`): gate coverage, required checks, path filtering, caching, plus general CircleCI/GHA best practices\n- [docs/ai/docker.md](docs/ai/docker.md) - Docker image builds: making every external fetch (apt/apk/curl/wget) retry so registry/CDN blips don't flake CI\n- [docs/ai/contract-dev.md](docs/ai/contract-dev.md) - Smart contract development\n- [docs/ai/dispute-game-investigation.md](docs/ai/dispute-game-investigation.md) - Investigating fault dispute games: challenger disagreements, excessive moves, self-contradiction, proposal validity, diagnosing the responsible op-node, and the bond outcome (read-only)\n- [docs/ai/flake-prevention.md](docs/ai/flake-prevention.md) - Guidance for preventing flaky tests\n- [docs/ai/dev-workflow.md](docs/ai/dev-workflow.md) - General development workflow: pinned tools via mise, Just usage, pre-PR checks, and CI caveats\n- [docs/ai/go-dev.md](docs/ai/go-dev.md) - Go service development\n- [docs/ai/rust-dev.md](docs/ai/rust-dev.md) - Rust development (kona, op-reth, alloy crates)\n- [docs/ai/reth-update-review.md](docs/ai/reth-update-review.md) - Reviewing reth/revm/alloy dependency bumps: the risk guide for upstream changes that should force a change in our in-tree op- forks but produce no diff (silent overrides, new defaults/variants, sync drift, consensus-critical math). Pairs with the `reth-update-reviewer` agent\n- [docs/ai/derivation.md](docs/ai/derivation.md) - Derivation pipeline development (op-node, kona-node)\n- [docs/ai/execution-layer.md](docs/ai/execution-layer.md) - Execution layer development (op-reth / EVM, fees, deposits)\n- [docs/ai/fault-proofs.md](docs/ai/fault-proofs.md) - Fault proof system (Cannon, kona-client, dispute games)\n- [docs/ai/devfeatures.md](docs/ai/devfeatures.md) - The `DevFeatures` bitmap system gating in-development smart contract features: where the bitmap is supplied, composed, propagated, and read. Only relevant for contract development and op-deployer — not needed for client (op-node / op-reth / kona) work\n- [docs/ai/acceptance-tests.md](docs/ai/acceptance-tests.md) - Building and running acceptance tests locally\n- [docs/ai/writing-acceptance-tests.md](docs/ai/writing-acceptance-tests.md) - Writing new acceptance tests: DSL patterns, naming, what to avoid\n- [docs/ai/opgeth-decoupling.md](docs/ai/opgeth-decoupling.md) - op-geth decoupling plan: consult when doing any op-geth decoupling work — migrating OP Stack–specific code out of op-geth into `op-core/*`, retiring op-geth-backed execution in tests/tooling, or removing fork-only API uses — so the monorepo can depend on upstream go-ethereum (scope: the whole monorepo — single go.mod; tracking issue #20257)\n\n## External References\n\n- [Optimism Documentation](https://docs.optimism.io)\n- [OP Stack Specifications](https://github.com/ethereum-optimism/specs)\n- [Contributing Guide](CONTRIBUTING.md)\n","category":"root","tokens":1780}]}