node-reth

# Base: Full Context

> Repository map, common commands, and conventions for working in the Base monorepo, followed by the same per-doc index as llms.txt. Paths are relative to the repository root.

<!-- LLMS_EXTRAS_START -->

## How the repository is organized

- `bin/`: thin binary crates (node, builder, consensus, basectl, proposer, challenger, prover services, and others). Logic lives in library crates.
- `crates/`: library crates in eight groups: `batcher`, `builder`, `common`, `consensus`, `execution`, `infra`, `proof`, `utilities`. Crate names use the `base-` prefix.
- `acceptance/`, `actions/`, `etc/systems/`: real-devnet acceptance scenarios, action tests, and system tests.
- `etc/`: Docker and Compose files (`etc/docker`), `just` modules (`etc/just`), CI and local scripts (`etc/scripts`), upstream pins (`etc/upstream-pins`), and tools.
- `docs/`: cross-cutting guides and specs. Crate and binary docs are READMEs next to their source.
- `.agents/skills/`: agent skills. `.depot/workflows/`: CI workflows.

## Common commands

Run `just` to list recipes and `just check` to list static checks.

- `just ci`: full local validation (fix, all checks, full test suite).
- `just pr`: faster variant that tests only crates affected by the change.
- `just fix`: auto-fix formatting, clippy, and feature-flag issues.
- `just test` / `just test-affected`: unit tests for the workspace or the affected crates.
- `just actions test`: action tests. `just devnet tests`: system tests (needs Docker).
- `just check::docs-index`: verify this index.

See [docs/guides/TESTING.md](docs/guides/TESTING.md) for what each check and CI stage covers, and [CONTRIBUTING.md](CONTRIBUTING.md) for the contribution policy.

## Conventions

The full rules are in [CLAUDE.md](CLAUDE.md). The ones most often needed:

- Keep `lib.rs` minimal and free of logic. Document crates with `#![doc = include_str!("../README.md")]`, never `//!` comments.
- Keep unit tests in a trailing `#[cfg(test)] mod tests` block. Prefer `mockall::automock` for test doubles of internal traits.
- Use structured tracing fields with static message strings, not interpolated messages.
- Every manifest inherits workspace lints with `[lints] workspace = true`.

## Finding and maintaining docs

Find a doc through the index below instead of grepping the tree. After adding, moving, deleting, or editing any Markdown doc, follow `.agents/skills/update-docs-index/SKILL.md`. CI fails when the index is stale.

<!-- LLMS_EXTRAS_END -->

<!-- LLMS_AUTOGEN_START -->

## Repository

- [CLAUDE.md](CLAUDE.md): Repo coding conventions for agents: crate naming, lib.rs and module layout, Cargo manifest rules, doc and lint policy, tracing style, testing and mocking rules, review expectations.
- [CONTRIBUTING.md](CONTRIBUTING.md): Contribution policy: open an issue first, work only on assigned issues, no typo or refactor PRs, dev setup (Rust, just, Foundry), run just ci, PR and bug report expectations.
- [README.md](README.md): Top-level Base overview: docs and specs links, installing binaries with baseup, running a node via docker compose, choosing a Docker or snapshot local devnet, and the base-anvil GHCR package.
- [SECURITY.md](SECURITY.md): Security policy: HackerOne and Cantina bug bounty programs, where to report offchain versus smart contract vulnerabilities, and the security contact email.

## Guides and specs

- [docs/guides/BLOCK_PRODUCTION_REVIEW.md](docs/guides/BLOCK_PRODUCTION_REVIEW.md): Review guide for block-production-sensitive PRs: mandatory payload size-limit gate across I/O boundaries, taxonomy of halt/stall scenarios (precompiles, builder, flashblocks), and a checklist.
- [docs/guides/DEVNET.md](docs/guides/DEVNET.md): Chooser for local environments: Docker and HA devnets, Anvil + local Nitro proving, snapshot devnet (base dev), snapshot benchmark harness, with quickstarts, data-reset behavior, and owning docs.
- [docs/guides/GLAMSTERDAM.md](docs/guides/GLAMSTERDAM.md): Scopes Base's Glamsterdam EIPs with BAL and SLOTNUM designs, plus calldata and access-list pricing proposals for transaction costs, P2P block sizes, and storage growth.
- [docs/guides/P2P.md](docs/guides/P2P.md): Explains the Base P2P stack for newcomers: consensus-layer discv5 and libp2p gossipsub versus execution-layer reth networking, how they interact via Engine API, key files, flags, and glossary.
- [docs/guides/RELEASE.md](docs/guides/RELEASE.md): Release process: Start Release creates releases/vX.Y.Z, version sync PR, automatic RC tags and builds per commit, then Publish Release for the final tag, Docker images and binaries.
- [docs/guides/SNAPSHOT_BENCHMARKS.md](docs/guides/SNAPSHOT_BENCHMARKS.md): How to run repeatable base-bench snapshot benchmarks on the snapshot benchmark harness, aggregate selected runs, and publish to base/benchmark. Use when measuring performance on restored datadirs.
- [docs/guides/STANDALONE_PROVING.md](docs/guides/STANDALONE_PROVING.md): Guide to running the prover stack standalone (just prover up) with your own RPCs and a funded Succinct Prover Network key: ZK backends, range sizing, requester key, restart behavior, troubleshooting.
- [docs/guides/TESTING.md](docs/guides/TESTING.md): Testing overview: what just ci and just pr run, the four tiers (unit, action, system, fuzz), other checks, the CI pipeline, and guidelines. Use to decide which command or test tier covers your change.
- [docs/guides/UPGRADES.md](docs/guides/UPGRADES.md): Step-by-step guide to adding a network upgrade (Azul as example): BaseUpgrade enum, RollupConfig activation, timestamps, plus BaseSpecId and precompile routing if EVM rules change, and a checklist.
- [docs/transaction-events/README.md](docs/transaction-events/README.md): Spec for transaction-event/v1, the JSONL business event journal for transaction observability: config fields, envelope, event vocabulary, Vector to audit-archiver ingest, Postgres retention, examples.
- [docs/transaction-events/tips-parity-checklist.md](docs/transaction-events/tips-parity-checklist.md): Checklist for verifying TIPS UI audit-archiver/Postgres responses match the S3-backed routes (block, txn, bundle, rejected) before switching TIPS_UI_QUERY_BACKEND=audit.

## Binaries

- [bin/acceptance/README.md](bin/acceptance/README.md): base-acceptance CLI entry point for the acceptance system: lists subcommands (validate, plan, run, check, report, cleanup) and example cargo invocations, deferring to acceptance/README.md.
- [bin/audit-archiver/README.md](bin/audit-archiver/README.md): audit-archiver service: NDJSON ingest into Postgres, JSON-RPC queries, retention classes and partition maintenance, BRIN summary worker, event_seq extraction split, env vars, S3 removal rollout.
- [bin/base-telemetry/README.md](bin/base-telemetry/README.md): base-telemetry backend: CLI and env config, per-IP rate limiting, and on-demand P2P reachability probes for execution-layer (enode) and consensus-layer (ENR or multiaddr) nodes.
- [bin/base/README.md](bin/base/README.md): Unified base commands and chain selection; execution-only and consensus-only modes over Engine API; native snapshot dev mode, history retention, impersonation, timing limits, and container usage.
- [bin/basectl/README.md](bin/basectl/README.md): basectl operator console reference: global options, TUI and scriptable commands (block, sync-status, p2p, txpool, conductor, sequencer, batcher, doctor, proofs), JSON output and examples.
- [bin/builder/README.md](bin/builder/README.md): Stub README for the base-builder block builder binary, which runs base-builder-core. Minimal, no usage details.
- [bin/challenger-e2e/README.md](bin/challenger-e2e/README.md): Challenger end-to-end test binary: forks L1 into a pod-local Anvil and checks the challenger scans valid games without disputing; intended as a K8s Job.
- [bin/challenger/README.md](bin/challenger/README.md): ZK-proof dispute game challenger binary that parses CLI arguments, builds a validated config, and delegates to base_challenger::ChallengerService::run().
- [bin/consensus/README.md](bin/consensus/README.md): Stub README for base-consensus, the canonical consensus node entrypoint for the Base Stack. Minimal, no usage details.
- [bin/load-tester/README.md](bin/load-tester/README.md): Stub README for the load-testing and benchmarking binary, which delegates to the base-load-tests library.
- [bin/node/README.md](bin/node/README.md): Stub README for the Base Reth node binary, the entry point for running a node with flashblocks, transaction tracing, and metering.
- [bin/proposer/README.md](bin/proposer/README.md): Stub README for the TEE-based output proposer binary, which delegates to base_proposer::ProposerService::run().
- [bin/prover-registrar/README.md](bin/prover-registrar/README.md): base-proof-tee-registrar: discovers TEE prover instances via AWS ALB, validates Nitro attestations, registers signers onchain; documents the instance cache TTL tradeoff.
- [bin/prover/nitro-enclave/README.md](bin/prover/nitro-enclave/README.md): Stub README for the TEE prover binary that runs inside an AWS Nitro Enclave, serving proving requests from the host over vsock; packaged into the EIF.
- [bin/prover/nitro-host/README.md](bin/prover/nitro-host/README.md): Nitro TEE prover host worker: server and local subcommands, worker mode, env setup, readyz and healthz health checks, and the internal-only RPC security model.
- [bin/prover/service/README.md](bin/prover/service/README.md): Prover service binary: Postgres-backed requester and worker JSON-RPC APIs that queue proofs and lease jobs to external workers; covers the security model for the unauthenticated APIs.
- [bin/prover/zk-host/README.md](bin/prover/zk-host/README.md): Stub README for the ZK prover worker host binary, which claims proof jobs from the prover service and runs them on the requested ZK backend.
- [bin/roxy/README.md](bin/roxy/README.md): Stub README for the roxy JSON-RPC reverse proxy binary, a Rust replacement for the ProxyD fork delegating to the base-roxy library.
- [bin/shadow-metrics/README.md](bin/shadow-metrics/README.md): shadow-metrics service: read-only HTTP JSON API over Postgres of reorged-out shadow candidate blocks, health probes, env var configuration table, and security notes.
- [bin/sidecrush/README.md](bin/sidecrush/README.md): Stub README for the block-production health-check sidecar, which polls an EL node's RPC and reports latest-block age via base-sidecrush.
- [bin/snapshotter/README.md](bin/snapshotter/README.md): Stub README for the sidecar that periodically creates Reth snapshots and uploads them to S3-compatible storage, delegating to base-snapshotter.
- [bin/snark-e2e/README.md](bin/snark-e2e/README.md): Stub README for the SNARK PLONK end-to-end verification binary: submits a one-block prove request, polls, and verifies the receipt; meant for K8s CronJobs.
- [bin/websocket-proxy/README.md](bin/websocket-proxy/README.md): Stub README for websocket-proxy, a fan-out proxy that relays upstream WebSocket messages to downstream clients with optional auth, rate limiting, and brotli compression.
- [bin/zk-benchmarks/README.md](bin/zk-benchmarks/README.md): Stub README for the ZK proof benchmarking binary for load-test runs, delegating to the base-zk-benchmarks library.
- [bin/zk-fork-dispute/README.md](bin/zk-fork-dispute/README.md): ZK fork dispute binary for Base Anvil workflows: parses CLI arguments, builds a validated config, and delegates to base_zk_fork_dispute::ZkForkDispute::run(). Very short README.

## Crates: batcher

- [crates/batcher/admin/README.md](crates/batcher/admin/README.md): Batcher admin JSON-RPC API: start, stop, flush, status, and DA throttle controller methods (admin_*), their behavior and error codes. Use when operating the batcher.
- [crates/batcher/blobs/README.md](crates/batcher/blobs/README.md): base-blobs: EIP-4844 blob encoder and decoder for the batcher wire format (130,044 payload bytes per blob); excludes KZG commitments and submission.
- [crates/batcher/cli/README.md](crates/batcher/cli/README.md): base-batcher-cli: base batcher flags and startup, with sequencer endpoints and leader search, channel and DA config, and shadow mode posting to the inbox a parity validator derives its chain from.
- [crates/batcher/comp/README.md](crates/batcher/comp/README.md): base-comp: incremental Brotli channel compression (CompressionStream, BrotliLevel) producing protocol-compatible channels; batch encoding and framing live in batcher-encoder.
- [crates/batcher/core/README.md](crates/batcher/core/README.md): base-batcher-core: async BatchDriver, SubmissionQueue for L1 transactions, and the DA throttle (Off, Step, Linear, Quadratic strategies) that publishes the DA limits the block builders apply.
- [crates/batcher/encoder/README.md](crates/batcher/encoder/README.md): base-batcher-encoder: synchronous, no-I/O encoder from L2 blocks to L1 submissions. Covers channel closing rules, blob framing, metric labels, and BatchEncoder usage.
- [crates/batcher/service/README.md](crates/batcher/service/README.md): base-batcher-service: BatcherConfig and BatcherService, which wire the encoder, block source, tx manager, and driver into a running batcher process.
- [crates/batcher/source/README.md](crates/batcher/source/README.md): base-batcher-source: L2 unsafe block source for the batcher with ordered polling, reorg detection, and L1 head tracking; lists the traits and components.

## Crates: builder

- [crates/builder/cli/README.md](crates/builder/cli/README.md): One-line README for base-builder-cli: reusable CLI arguments and config conversion helpers for Base builder nodes.
- [crates/builder/core/README.md](crates/builder/core/README.md): base-builder-core: flashblocks payload builder library producing sub-second block chunks, with launcher and metering trait modules, cargo features, and usage.
- [crates/builder/metering/README.md](crates/builder/metering/README.md): base-builder-metering covers MeteringStore's moka cache with a configured max capacity, LRU eviction policy, and TTL, its MeteringProvider implementation, JSON-RPC extensions, and a wiring example.
- [crates/builder/multiplex/README.md](crates/builder/multiplex/README.md): Runs flashblocks and basic payload builders in parallel behind one handle, selecting basic at Denim; cutover mode is off by default and a separate basic-only mode runs just the basic builder.
- [crates/builder/publish/README.md](crates/builder/publish/README.md): WebSocket broadcast publisher for the block builder (WebSocketPublisher, Listener, BroadcastLoop, metrics traits). Use when changing how serialized payloads are pushed to connected subscribers.

## Crates: common

- [crates/common/bundles/README.md](crates/common/bundles/README.md): Types for transaction bundles used in resource metering (Bundle, ParsedBundle, AcceptedBundle, MeterBundleResponse). Use when working on base_meterBundle or bundle hashing and DA size helpers.
- [crates/common/chains/README.md](crates/common/chains/README.md): Base chain parameters and upgrade timestamps via ChainConfig, upgrade schedules via ChainUpgrades and Upgrades, and the BaseUpgrade re-export with BaseUpgradeExt execution helpers.
- [crates/common/consensus/README.md](crates/common/consensus/README.md): Base EL consensus types that differ from alloy-consensus, notably BaseTxEnvelope with deposit txs and receipts with deposit_nonce. Use when handling Base transactions and receipts.
- [crates/common/eip8130/README.md](crates/common/eip8130/README.md): Engine-neutral no_std EIP-8130 primitives (intrinsic gas schedule, nonce manager slot derivation) shared by revm and EVM2 paths. Use when changing EIP-8130 gas pricing or nonce slots.
- [crates/common/evm/README.md](crates/common/evm/README.md): Base revm-based EVM support: upgrade-to-SpecId mapping, BaseEvmFactory, block executors, receipt builders, and create2 deployer handling. Use when changing per-upgrade execution rules.
- [crates/common/evm2/README.md](crates/common/evm2/README.md): Scaffold for Base's EVM2 integration (BaseEvmTypes, currently mirroring stock Ethereum), not wired into the node, for differential testing against revm. Use when working on EVM2 groundwork.
- [crates/common/flashblocks/README.md](crates/common/flashblocks/README.md): Types for parsing flashblock messages: FlashblocksPayloadV1, ExecutionPayloadFlashblockDeltaV1, and the typed Metadata used by Flashblock.
- [crates/common/flz/README.md](crates/common/flz/README.md): FastLZ compressed-length estimation and Fjord L1 data gas calculation (data_gas_fjord, tx_estimated_size_fjord). Use when computing L1 data fees or transaction size estimates.
- [crates/common/genesis/README.md](crates/common/genesis/README.md): Genesis types for Base, chiefly RollupConfig (upgrade timestamps, L1/L2 genesis, batch inbox, system config); no_std capable. Use when configuring or reading rollup parameters.
- [crates/common/l1-fees/README.md](crates/common/l1-fees/README.md): Engine-neutral OP-stack L1 fee math (L1FeeParams, Bedrock/Ecotone/Fjord data cost, Isthmus operator fee) shared by revm and EVM2 engines. Use when changing L1 fee computation.
- [crates/common/network/README.md](crates/common/network/README.md): Defines the alloy Network implementation for Base (Base type with Base tx and receipt types) and the BaseEngineApi extension trait. Use when building alloy providers or signers for Base.
- [crates/common/observability-events/README.md](crates/common/observability-events/README.md): Producer-side transaction-event/v1 JSONL envelope and non-blocking writer for transaction audit journals, with field and privacy rules. Use when emitting transaction lifecycle events.
- [crates/common/precompile-macros/README.md](crates/common/precompile-macros/README.md): Proc macros for native precompile storage: #[contract], #[namespace], #[derive(Storable)], and primitive/array impl generators. Use when defining precompile storage layouts (adapted from Tempo).
- [crates/common/precompile-storage/README.md](crates/common/precompile-storage/README.md): Storage traits and slot rules for native precompiles: Solidity-style packing, slot/base_slot/namespace overrides, mapping hashing, append-only upgrades. Use when laying out precompile storage.
- [crates/common/precompiles/README.md](crates/common/precompiles/README.md): Per-upgrade Base precompile tables plus Beryl native precompiles (activation registry, policy registry, B-20 factory and token variants) with addresses. Use when changing precompiles or B-20 behavior.
- [crates/common/rpc-types-engine/README.md](crates/common/rpc-types-engine/README.md): Engine API payload types for Base: BasePayloadAttributes, execution payload envelopes, BaseExecutionPayloadV4, and sidecars. Use when exchanging payloads between consensus and execution clients.
- [crates/common/rpc-types/README.md](crates/common/rpc-types/README.md): Base-specific JSON-RPC types: genesis/chain info, BaseTransactionRequest and Transaction, BaseTransactionReceipt, and L1BlockInfo. Use when (de)serializing Base RPC payloads.
- [crates/common/signer/README.md](crates/common/signer/README.md): RemoteSigner implementing alloy TxSigner by forwarding eth_signTransaction to an external signer sidecar over HTTP. Use when signing transactions without local keys.

## Crates: consensus

- [crates/consensus/cli/README.md](crates/consensus/cli/README.md): Reusable clap argument structs for consensus clients: L1ClientArgs, L2ClientArgs (engine API with JWT), RpcArgs, and SequencerArgs. Use when adding or flattening node CLI flags.
- [crates/consensus/derive/README.md](crates/consensus/derive/README.md): no_std L2 derivation pipeline that turns L1 data into BasePayloadAttributes (DerivationPipeline, PipelineBuilder, EthereumDataSource). Use when working on or constructing derivation.
- [crates/consensus/disc/README.md](crates/consensus/disc/README.md): Discv5-based peer discovery for Base (Discv5Builder, Discv5Driver, ENR management, persistent bootstore). Use when working on node discovery, bootnodes, or ENR behavior.
- [crates/consensus/engine/README.md](crates/consensus/engine/README.md): Task-queue Engine API client for the rollup node (Engine, EngineClient, Insert/Consolidate/Finalize/Synchronize tasks, version selection). Use when changing engine state or forkchoice handling.
- [crates/consensus/gossip/README.md](crates/consensus/gossip/README.md): libp2p GossipSub networking for unsafe blocks (GossipDriver, BlockHandler, ConnectionGater), including block topic retirement by fork and its metrics. Use when debugging P2P gossip.
- [crates/consensus/peers/README.md](crates/consensus/peers/README.md): Peer identity types ported from reth (PeerId, NodeRecord, AnyNode, discv5 Enr) and how they relate. Use when parsing or converting node records for discovery or admin RPC.
- [crates/consensus/protocol/README.md](crates/consensus/protocol/README.md): Shared protocol types (batches, frames, channels, BlockInfo, L1 info per upgrade, output roots) and the Denim L1 origin rule for 200ms blocks. Use when touching batch or origin logic.
- [crates/consensus/providers/README.md](crates/consensus/providers/README.md): Alloy-backed data providers for derivation (AlloyChainProvider, AlloyL2ChainProvider, beacon client, blob provider) and OnlinePipeline. Use when wiring derivation to live L1/L2 nodes.
- [crates/consensus/rpc/README.md](crates/consensus/rpc/README.md): jsonrpsee trait definitions for the rollup node RPC, chiefly optimism_syncStatus, with a security note that the endpoint is internal-only. Use when implementing or calling consensus RPC.
- [crates/consensus/safedb/README.md](crates/consensus/safedb/README.md): redb-backed persistent safe head tracking (SafeDB, SafeHeadListener, SafeDBReader) serving optimism_safeHeadAtL1; not multi-process safe. Use when working on safe head history.
- [crates/consensus/service/README.md](crates/consensus/service/README.md): Consensus node composition layer: actor model, RollupNode vs FollowNode, startup sequence, and each actor (engine, derivation, sequencer, network, L1 watcher, RPC). Read to understand node wiring.
- [crates/consensus/service/src/actors/network/README.md](crates/consensus/service/src/actors/network/README.md): Overview and example of the network actor, which owns libp2p gossip and discv5 discovery, built via NetworkBuilder or with_transport for tests. Use when wiring or testing the P2P actor.
- [crates/consensus/sources/README.md](crates/consensus/sources/README.md): Block signing interfaces for the consensus node: BlockSigner for local or remote signing, RemoteSigner with mTLS client certs. Use when configuring or changing how blocks are signed.
- [crates/consensus/upgrades/README.md](crates/consensus/upgrades/README.md): Upgrade trait and Upgrades registry for Ecotone, Fjord, Isthmus, and Jovian network transactions. Use when collecting transactions for upgrade activation blocks.

## Crates: execution

- [crates/execution/chainspec/README.md](crates/execution/chainspec/README.md): BaseChainSpec and SUPPORTED_CHAINS CLI resolution, Holocene/Jovian base fee helpers, and Denim timestamp validation rules (custom genesis needs nonzero config.blockTime). Use for chain/fork config.
- [crates/execution/cli/README.md](crates/execution/cli/README.md): base-execution-cli: Base execution node CLI wrapper with BaseChainSpecParser and a Cli type that drives node startup. Use when changing node argument parsing or chain selection.
- [crates/execution/consensus/README.md](crates/execution/consensus/README.md): BaseBeaconConsensus for execution-layer block header/body validation (blob gas, deposits, Canyon EIP-1559, Isthmus) plus receipt root helpers. Use when touching block validation rules.
- [crates/execution/eip8130-rpc-node/README.md](crates/execution/eip8130-rpc-node/README.md): Node extension wiring the standalone EIP-8130 eth_getTransactionCount override; self-gates via Eip8130RpcMode (Defer when flashblocks already overrides, else Register). Use for RPC override conflicts.
- [crates/execution/eip8130-rpc/README.md](crates/execution/eip8130-rpc/README.md): EIP-8130 RPC helpers: ChannelNonceReader for 2D nonce reads by nonce_key and Eip8130GasEstimator, one simulation for eth_estimateGas and eth_call. Use when debugging AA nonce, call or gas RPCs.
- [crates/execution/eip8130/README.md](crates/execution/eip8130/README.md): Native EIP-8130 account abstraction validation: enshrined authenticators (not precompiles) needing parity with contracts, validation layers, intrinsic gas formula, EIP-7623 floor, fee checks.
- [crates/execution/evm/README.md](crates/execution/evm/README.md): BaseEvmConfig setup, block assembly, L1 info parsing and data-fee calculation, receipt building, and error types. Use when changing Base EVM setup or fork specs.
- [crates/execution/exex/README.md](crates/execution/exex/README.md): Proofs-history ExEx: versioned MDBX trie store serving historical eth_getProof without OOM, with pruner, debug_proofsSyncStatus, prune/unwind commands, metrics. Use to operate or debug proofs history.
- [crates/execution/flashblocks-node/README.md](crates/execution/flashblocks-node/README.md): FlashblocksExtension for the Base node: install_ext usage (install last), CLI flags (--flashblocks-url, --max-pending-blocks-depth, cached-execution), and the state, subscriber, RPC components.
- [crates/execution/flashblocks-node/tests/README.md](crates/execution/flashblocks-node/tests/README.md): Explains why flashblocks-node integration tests live in tests/ (public API only, single compilation unit with test utils) versus private-internals unit tests in src/. Read before adding tests.
- [crates/execution/flashblocks/README.md](crates/execution/flashblocks/README.md): Flashblocks pending-state management: StateProcessor, subscriber, reconciler, the staleness invariant and depth limit, canonical reconciliation, and pending-aware RPC methods and subscriptions.
- [crates/execution/metering/README.md](crates/execution/metering/README.md): Metering RPC: base_meterBundle, base_meterBlockByHash and base_meterBlockByNumber, plus the pseudo-opcode vocabulary for meteredOpcodes filters. Use to profile tx or block execution timing and gas.
- [crates/execution/node/README.md](crates/execution/node/README.md): base-node-core: core Base execution node types and builders (BaseEngineTypes, BaseEngineApiBuilder) wiring engine, RPC and payload subsystems. Use when assembling or modifying the node.
- [crates/execution/payload/README.md](crates/execution/payload/README.md): Payload builder crate: BasePayloadBuilder assembles payloads from pool and CL attributes, BaseExecutionPayloadValidator checks them, BaseDAConfig provides DA config for fee calculation.
- [crates/execution/proofs/README.md](crates/execution/proofs/README.md): base-proofs-extension: node extension storing historical Merkle proofs in MDBX with retention window, pruning, verification and eth_getProof RPC; lists the RollupArgs proofs_history config flags.
- [crates/execution/rpc/README.md](crates/execution/rpc/README.md): base-execution-rpc: BaseEthApi, BaseEngineApi, debug, miner, sequencer and witness RPC implementations plus SequencerClient for tx forwarding. Use when changing Base JSON-RPC behavior.
- [crates/execution/runner/README.md](crates/execution/runner/README.md): base-node-runner: BaseNodeExtension and FromExtensionConfig traits plus the NodeHooks accumulator for modular node extensions, with an example custom extension. Use to add node extensions.
- [crates/execution/shadow-indexer-db/README.md](crates/execution/shadow-indexer-db/README.md): One-line stub: database access layer for shadow indexer block persistence. Little detail beyond that.
- [crates/execution/shadow-indexer/README.md](crates/execution/shadow-indexer/README.md): Shadow indexer ExEx persisting only reorged-out or reverted blocks; shadow_blocks keyed by number, with later commits backfilling canonical_hash. Use to understand how discarded blocks are stored.
- [crates/execution/trie/README.md](crates/execution/trie/README.md): base-execution-trie: BaseProofsStore traits and backends (e.g. RocksdbProofsStorage) holding per-block trie diffs for fault-proof generation, with cursors, pruner and startup init job.
- [crates/execution/trie/src/db/schema.md](crates/execution/trie/src/db/schema.md): MDBX proof-history DB schema: versioned DupSort tables, tombstones, BlockChangeSet reverse index, proof window keys, cursor reads, append-only writes, block 0 backfill. For eth_getProof storage.
- [crates/execution/tx-forwarding/README.md](crates/execution/tx-forwarding/README.md): base-tx-forwarding: forwards mempool txs to builder RPCs via per-destination queues fed by FIFO and tip-priority lanes; dedup, batching, resend; spawn_requests for custom ForwardRequest; CLI flags.
- [crates/execution/txpool-rpc/README.md](crates/execution/txpool-rpc/README.md): Txpool RPC admin/status APIs and validity submissions; shared staged signature modes, signature rejection metrics, predicate forwarding and sequencer proxy behavior.
- [crates/execution/txpool-tracing/README.md](crates/execution/txpool-tracing/README.md): Txpool tracing extension: tracks mempool lifecycle events, txpool_transactionStatus RPC, enabling CLI flags, and reth_transaction_tracing_tx_event histogram. Use to debug tx latency or drops.
- [crates/execution/txpool/PROPAGATION_PIPELINE.md](crates/execution/txpool/PROPAGATION_PIPELINE.md): Plan to forward mempool txs to builders via base_insertValidatedTransaction in 4 PRs (consumer, forwarder, builder endpoint, node integration). Only PR 1 is marked done. Names a crates/txpool/ path.
- [crates/execution/txpool/README.md](crates/execution/txpool/README.md): Base txpool validation/ordering, builder wire extensions, staged EIP-712 predicate authorization, wallet signing contract, rejection metrics, and rollout/security limits.

## Crates: infra

- [crates/infra/audit/README.md](crates/infra/audit/README.md): audit-archiver-lib: ingests Vector transaction-event/v1 batches into Postgres idempotently and serves JSON-RPC queries; covers the migrations and schema snapshot regeneration.
- [crates/infra/basectl/README.md](crates/infra/basectl/README.md): basectl-cli: the basectl clap parser and commands (blocks, sync, txpool, peers, proofs, conductor), interactive monitor, flashblocks JSON-lines stream, Denim readiness checks, and pods view config.
- [crates/infra/challenger-e2e/README.md](crates/infra/challenger-e2e/README.md): Behavioural e2e test of the challenger: forks L1 into Anvil, patches real games; the default `all` scenario covers Paths 1-4 on one fork by reviving nullified verifiers. Lists scenarios and env vars.
- [crates/infra/fee-jobs/README.md](crates/infra/fee-jobs/README.md): Run disburse, process, and sweep fee jobs with per-command environment variables, preconditions, and transaction manager settings.
- [crates/infra/load-tests/README.md](crates/infra/load-tests/README.md): Load testing: devnet/sepolia profiles, YAML workloads, calibration, adaptive or proactive validity signing, resource pacing, benchmark/report tools, and rollout limitations.
- [crates/infra/roxy/README.md](crates/infra/roxy/README.md): Scaffold-only Rust JSON-RPC reverse proxy meant to replace the ProxyD fork; currently just a listen-address flag plus /healthz and /readyz probes, no proxying yet.
- [crates/infra/shadow-metrics/README.md](crates/infra/shadow-metrics/README.md): base-shadow-metrics: read-only HTTP JSON API (api_router) and Postgres ShadowMetricsStore over reorged-out shadow blocks for the block explorer. Use for shadow block endpoints or readiness probes.
- [crates/infra/sidecrush/README.md](crates/infra/sidecrush/README.md): base-sidecrush library: polls an EL node RPC, classifies block-production health (Healthy/Delayed/Unhealthy/Error) and emits StatsD heartbeat counters to Datadog. Use when changing node health checks.
- [crates/infra/snapshotter/README.md](crates/infra/snapshotter/README.md): base-snapshotter sidecar: at-tip check, stops EL/CL Docker containers, builds reth snapshot manifest and chunks, uploads to S3/R2, restarts nodes. Use when working on snapshot generation or upload.
- [crates/infra/snark-e2e/README.md](crates/infra/snark-e2e/README.md): base-snark-e2e library: submits a one-block SNARK PLONK prove request, verifies the receipt, and checks its vkeys match the on-chain verifier. Lists env vars and the integration test command.
- [crates/infra/telemetry/README.md](crates/infra/telemetry/README.md): base-telemetry-service Axum API with EL (devp2p) and CL (libp2p) P2P reachability probe endpoints: request/response shapes, limits, rate limiting, trusted proxies, IPv4 target rules.
- [crates/infra/websocket-proxy/README.md](crates/infra/websocket-proxy/README.md): Alpha WebSocket proxy fanning out Flashblocks from rollup-boost to downstream RPC nodes, with optional Brotli and trusted-proxy CIDR client IP handling. Use for its CLI flags and deployment.
- [crates/infra/withdrawer/README.md](crates/infra/withdrawer/README.md): Withdrawer configuration, signers, retrying RPC clients, capped L1 transaction preparation and signing, withdrawal extraction, and inclusion proof verification against onchain output claims.
- [crates/infra/zk-benchmarks/README.md](crates/infra/zk-benchmarks/README.md): One-line stub: ZK proof benchmarking utilities for Base load-test runs; no usage or detail beyond that.
- [crates/infra/zk-fork-dispute/README.md](crates/infra/zk-fork-dispute/README.md): base-zk-fork-dispute: Anvil fork workflow that patches an invalid dispute-game root, gets a SNARK PLONK proof from prover-service, and submits challenge()/nullify(). Needs a running prover-service.

## Crates: proof

- [crates/proof/challenge/README.md](crates/proof/challenge/README.md): base-challenger: ZK-proof dispute game challenger; module tour covering scanner, validator, pending proof phases, submitter, bond lifecycle, and config. Use to find where challenger logic lives.
- [crates/proof/client/README.md](crates/proof/client/README.md): base-proof-client: runtime-agnostic prologue/driver/epilogue orchestration of a fault or ZK proof run with injected oracle, hint writer and EVM factory; InvalidClaim on root mismatch.
- [crates/proof/contracts/README.md](crates/proof/contracts/README.md): base-proof-contracts: Alloy-backed clients and encoders for DisputeGameFactory, AnchorStateRegistry and AggregateVerifier (nullify, create calldata), shared by proposer and challenger.
- [crates/proof/driver/README.md](crates/proof/driver/README.md): base-proof-driver: no_std derivation pipeline Driver that steps the pipeline, handles resets/reorgs and drives an Executor; PipelineCursor/TipCursor track state. Use for FPVM or hosted proof loops.
- [crates/proof/executor/README.md](crates/proof/executor/README.md): base-proof-executor: no_std stateless L2 block executor (StatelessL2Builder) running revm over a base-proof-mpt TrieDB from Merkle witnesses, returning sealed header, receipts and state root.
- [crates/proof/host/README.md](crates/proof/host/README.md): base-proof-host: host side of the preimage oracle protocol; Host orchestrator serves FPVM clients, with memory/disk KV stores, online and offline modes, and RecordingOracle for access traces.
- [crates/proof/mpt/README.md](crates/proof/mpt/README.md): base-proof-mpt: in-memory recursive Ethereum Merkle Patricia Trie that lazily fetches node preimages via TrieProvider for stateless execution; the trie backend for base-proof-executor.
- [crates/proof/preimage/README.md](crates/proof/preimage/README.md): base-proof-preimage: no_std client traits (PreimageOracleClient, HintWriterClient) and async host traits for the fault proof preimage oracle protocol. Use when wiring FPVM clients to hosts.
- [crates/proof/primitives/README.md](crates/proof/primitives/README.md): base-proof-primitives: shared proof wire types (Proposal, ProofBundle, ProofResult with Tee and Zk variants) exchanged among proposer, enclave, provers and on-chain verifiers.
- [crates/proof/proof/README.md](crates/proof/proof/README.md): base-proof SDK: oracle-backed derivation and execution pieces (OraclePipeline, Oracle L1/L2 providers, CachingOracle, BaseExecutor), boot info and EIP-2935 lookups for fault proof generation.
- [crates/proof/proposer/README.md](crates/proof/proposer/README.md): base-proposer: TEE-based output proposer; requests a TEE-signed proposal, verifies locally, submits via DisputeGameFactory. Explains stateless on-chain parent game recovery each tick.
- [crates/proof/prover-service/README.md](crates/proof/prover-service/README.md): base-prover-service: JSON-RPC contract and service for proof requests, status polling and worker-claimed ZK/TEE jobs via the proof_requests queue; backends live in worker hosts.
- [crates/proof/prover-service/client/README.md](crates/proof/prover-service/client/README.md): base-prover-service-client: separate requester and worker JSON-RPC client types for the prover service, built on base-prover-service-protocol.
- [crates/proof/prover-service/db/README.md](crates/proof/prover-service/db/README.md): base-prover-service-db: Postgres layer where proof_requests is the canonical queue (status vs job_status, lock fencing, heartbeats) and proof_sessions tracks ZK backend sessions.
- [crates/proof/prover-service/protocol/README.md](crates/proof/prover-service/protocol/README.md): One-line stub: protocol types and role-specific JSON-RPC traits for the Base prover service (wire contract used by client and service crates).
- [crates/proof/rpc/README.md](crates/proof/rpc/README.md): base-proof-rpc: Alloy-backed L1Client, L2Client and RollupClient traits with MeteredCache, retry/backoff and RpcError, shared by proposer and challenger. Use for chain data access in proof services.
- [crates/proof/submission/README.md](crates/proof/submission/README.md): base-proof-submission: shared helpers to submit verifyProposalProof, proof-bearing challenge() and nullify() txs and classify non-retryable reverts; leaves game-selection policy to callers.
- [crates/proof/tee/nitro-enclave/README.md](crates/proof/tee/nitro-enclave/README.md): base-proof-tee-nitro-enclave: code that runs inside the AWS Nitro Enclave (vsock listener, proof client pipeline, ECDSA signing, NSM access, attestation verification).
- [crates/proof/tee/nitro-host/README.md](crates/proof/tee/nitro-host/README.md): base-proof-tee-nitro-host: parent-instance TEE proving backend for Nitro with JSON-RPC server, enclave pool, vsock or in-process transport, proof generator. Includes a module table.
- [crates/proof/tee/nitro-verifier/README.md](crates/proof/tee/nitro-verifier/README.md): base-proof-tee-nitro-verifier: pure verification of AWS Nitro attestation documents (COSE_Sign1 parsing, VerifierError, Solidity-aligned types) for registrar and native verification flows.
- [crates/proof/tee/registrar/README.md](crates/proof/tee/registrar/README.md): base-proof-tee-registrar: discovers Nitro enclaves via ALB target groups, fetches attestations, builds P-384 hints, registers TEE signer keys in TEEProverRegistry on L1; covers cache TTL, modules.
- [crates/proof/worker/README.md](crates/proof/worker/README.md): base-proof-worker: backend-neutral shared worker loop (polling, heartbeat, job discovery, proof submission) for prover-service hosts that claim jobs and submit proofs via the worker API.
- [crates/proof/zk/backend/README.md](crates/proof/zk/backend/README.md): base-proof-zk-backend: ZkProver implementations (DryRun, SP1 Cluster, SP1 Network) for prover-service workers, with SP1 setup under src/succinct and guest programs in zk/programs/succinct.
- [crates/proof/zk/host/README.md](crates/proof/zk/host/README.md): Host-side ZK proving worker: ZkHost and ProofGenerator claim ZK jobs, run the backend named by zk_backend on the request, and submit proofs. Use when working on the prover service's ZK worker path.
- [crates/proof/zk/programs/succinct/range/README.md](crates/proof/zk/programs/succinct/range/README.md): Client program (binary) that executes the Base rollup state transition over a block range for an on-chain validity proof, in native mode (RPC data) or zkVM mode (host-supplied data).
- [crates/proof/zk/utils/README.md](crates/proof/zk/utils/README.md): Guest-side STF helpers shared by zkVM range programs; must stay zkVM-buildable (no RPC, tokio, or proving-backend deps). Use to see what belongs in this crate rather than the witness crate.
- [crates/proof/zk/witness/README.md](crates/proof/zk/witness/README.md): Host-side witness capture for ZK proving: fetches L1/L2 data over RPC, runs the preimage server, and collects DefaultWitnessData (preimages plus blobs) for a range. Not a guest dependency.

## Crates: utilities

- [crates/utilities/balance-monitor/README.md](crates/utilities/balance-monitor/README.md): Describes BalanceMonitorLayer, an alloy ProviderLayer that polls an account balance at a fixed interval and publishes it through a tokio watch channel for onchain balance monitoring in services.
- [crates/utilities/cli/README.md](crates/utilities/cli/README.md): Overview of base-cli-utils: parse_cli!, register_version_metrics!, define_log_args!, define_metrics_args! macros and RuntimeManager (tokio runtime, signal shutdown). Use when building Base binaries.
- [crates/utilities/health/README.md](crates/utilities/health/README.md): Health utilities: a healthz JSON-RPC method (HealthzRpc) for jsonrpsee, plus an axum-server feature serving Kubernetes-style /healthz and /readyz probes via HealthServer. Use to add health endpoints.
- [crates/utilities/jwt/README.md](crates/utilities/jwt/README.md): JwtSecretReader reads, writes, generates and resolves JWT secrets for Base nodes. JwtValidator optionally validates secrets against an Engine API with the engine-validation feature.
- [crates/utilities/l1-head/README.md](crates/utilities/l1-head/README.md): One-line crate description: shared L1 head calculation helpers for proof services. No usage details in the README.
- [crates/utilities/metrics/README.md](crates/utilities/metrics/README.md): Metrics helpers: define_metrics! for standardized Prometheus registration (optional custom struct), timed! for durations, inflight! for in-flight tracking. Use when instrumenting crates.
- [crates/utilities/optimism-rpc/README.md](crates/utilities/optimism-rpc/README.md): One-line crate description: typed Optimism rollup JSON-RPC provider extensions and response types. No usage details in the README.
- [crates/utilities/reth-cli/README.md](crates/utilities/reth-cli/README.md): Reth-specific CLI utilities for Base EL binaries: init_reth! for version metadata, and the snapshot manifest archive generator shared by snapshot-manifest and the snapshotter sidecar.
- [crates/utilities/retry/README.md](crates/utilities/retry/README.md): Shared RetryConfig wrapper over backon exponential retry builders, giving services common delay normalization, jitter, and bounded or unbounded retry limits. Use when adding retry logic.
- [crates/utilities/ring-buffer/README.md](crates/utilities/ring-buffer/README.md): Generic fixed-capacity ring buffer (VecDeque of (I, V) entries) for position-keyed replay; the oldest entry is evicted on push when full.
- [crates/utilities/runtime/README.md](crates/utilities/runtime/README.md): Async runtime abstraction (Clock, Spawner, Cancellation, Runtime traits) with TokioRuntime for production and a seeded deterministic executor with virtual time for reproducible tests.
- [crates/utilities/test-utils/README.md](crates/utilities/test-utils/README.md): Shared integration-test utilities: build_test_genesis, pre-funded test Accounts, and Solidity contract bindings (MockERC20, proxies, etc.). Use as a dev-dependency in Base integration tests.
- [crates/utilities/test-utils/contracts/README.md](crates/utilities/test-utils/contracts/README.md): Upstream Foundry boilerplate README for the test contracts project, plus one Base-specific section on deploying the WETH/USDC real-token swap devnet harness used by the load-test Justfile.
- [crates/utilities/trusted-proxy/README.md](crates/utilities/trusted-proxy/README.md): Explains TrustedProxyConfig client IP resolution: X-Forwarded-For style headers are honored only from trusted proxy CIDRs, scanned right to left. Use for rate limiting or client IP logic.
- [crates/utilities/tx-manager/README.md](crates/utilities/tx-manager/README.md): Transaction lifecycle manager for EIP-1559/4844 txs: TxManager, fee bumping, nonce management, send state, error classification, blob sidecars, CLI config macros. Use when sending onchain txs.
- [crates/utilities/upgrade-signal/README.md](crates/utilities/upgrade-signal/README.md): Reads upgrade activation timestamps and minimum protocol version from the L1 ProtocolVersions contract; covers modes (metrics-only, startup-apply, runtime-admin), CLI flags, defaults, metrics.

## Tooling, testing and infrastructure

- [.depot/README.md](.depot/README.md): Depot CI setup: required variables and secrets, cache behavior (sccache WebDAV), and which workflows stay on GitHub Actions. Use when changing CI or debugging Depot builds.
- [acceptance/README.md](acceptance/README.md): Acceptance runner that provisions the real Docker Compose devnet and checks RPC behavior from TOML scenarios. Covers CLI workflows, JSON results, reports, and safety limits.
- [actions/README.md](actions/README.md): Action test framework: simulated rollup actors (L1 miner, batcher, sequencer, verifier) driven step by step against real derivation logic. Use when writing or understanding action tests.
- [actions/harness/README.md](actions/harness/README.md): base-action-harness design: which parts use production components versus test-only synthetic boundaries, known production gaps, and a roadmap for making action tests more production-like.
- [audits/azul/README.md](audits/azul/README.md): Pointer to the Immunefi audit competition for the Azul hardfork (21 April to 4 May 2026) and where the public reports are hosted.
- [baseup/README.md](baseup/README.md): baseup installer for Base release binaries: install commands and flags, binaries installed, checksum, GPG and SLSA verification, verify-release, and supported targets.
- [etc/docker/README.md](etc/docker/README.md): Dockerfiles, Bake targets, published images (ghcr.io/base/node and single-binary images), and Compose setup for the local devnet and Rust services, including batcher topology and build profiles.
- [etc/systems/README.md](etc/systems/README.md): Docs for base-system-tests: running the snapshot benchmark harness (builder and follow client), snapshot and transfer benchmarks, workload suite, 2s vs 200ms comparison, cleanup.
- [etc/tools/witness-diff/README.md](etc/tools/witness-diff/README.md): witness-diff tool that compares two execution witnesses (from debug_executionWitness) to find differing trie nodes, bytecodes, or preimages. Use when debugging state root mismatches between nodes.
- [etc/upstream-pins/README.md](etc/upstream-pins/README.md): Reth workspace pin: reth.toml is the source of truth for reth-* git deps. Covers pin-reth, check-reth-pin, pin-reth-test, reth-prepare-release, patch PR handling, and backport tag protection.

## Optional

- [llms.txt](llms.txt): This index without the repository map and conventions
- [Base documentation (llms.txt)](https://docs.base.org/llms.txt): Index of the public docs site for builders and node operators
- [Base specs](https://specs.base.org): Protocol overview, including past and upcoming upgrades

<!-- LLMS_AUTOGEN_END -->