Agent Instructions

Repository Layout

• bin/: thin binary crates (node, builder, consensus, basectl, proposer, challenger, prover services, and others).
• crates/: library crates grouped as batcher, builder, common, consensus, execution, infra, proof, utilities.
• acceptance/, actions/, etc/systems/: real-devnet acceptance scenarios, action tests, and system tests.
• etc/: Docker and Compose files, just modules, CI and local scripts, upstream pins, and tools.
• docs/: cross-cutting guides and specs. Crate and binary docs are READMEs next to their source.
• Run just to list recipes. docs/guides/TESTING.md explains what just ci, just pr, and each check cover.

Crate Architecture and Public API

• All crate names must use the base- prefix, for example base-enclave or base-builder-core.
• Keep lib.rs files minimal and free of logic.
• Group each module declaration with its re-export (mod foo; pub use foo::Bar;) instead of listing all modules and then all re-exports.
• Do not declare modules pub or pub(crate) unless they are test utilities, such as pub mod test_utils.
• Make all structs, types, enums, and functions within modules pub, and re-export them from lib.rs. Do not introduce private or pub(crate) types.
• Prefer methods on a type, including a unit struct when appropriate, over bare functions so the public API exports types rather than loose functions.
• Keep binary crates under bin/ as minimal glue code. Put meaningful logic in library crates.

Cargo Manifests and Features

• Sort Cargo.toml dependencies by line length (waterfall style) and preserve the workspace's logical grouping.
• Put features sections at the bottom of manifests.
• Every crate and binary manifest must inherit workspace lints with [lints] workspace = true.
• Before choosing a new crate's directory, check its dependencies, including dev-dependencies, against etc/scripts/ci/check-crate-deps.sh, and run that script before opening a PR.
• Do not enable dependency features in the workspace root Cargo.toml. Enable them only in the crates or binaries that need them to prevent feature leakage into no_std crates.

Documentation and Lints

• Docs are READMEs next to the code they describe, plus cross-cutting guides in docs/guides/. Open every doc with a short paragraph that says what it covers in plain terms, naming the generic concept alongside any codename (for example, "Azul network upgrade"), so a text search finds it.
• Use #![doc = include_str!("../README.md")] for crate documentation in lib.rs; never use //! comments there.
• Begin every mod.rs file with a //! module doc comment describing its contents.
• Do not suppress Clippy warnings with #![allow(missing_docs)] or other allow-lints. Fix the underlying issue.

Rust Structure and Style

• Put all use imports at the top of the file or at the top of a mod block. Do not place imports inside functions or closures.
  • Conditional imports may live inside their #[cfg(...)]-gated block, such as a #[cfg(test)] mod tests or feature-gated function.
  • Imports inside macro_rules! bodies are allowed when the macro needs them in its expansion context.
• Do not destructure a value merely to read its fields, such as let Self { width, height } = self. Access fields directly, such as self.width and self.height.

// Avoid
fn area(&self) -> u32 {
    let Self { width, height } = self;
    width * height
}

// Prefer
fn area(&self) -> u32 {
    self.width * self.height
}

• Prefer simple call chains over indirection. Inline methods that perform only one internal operation, and call an inner type directly instead of adding a forwarding method.

// Avoid: a wrapper that just forwards to the inner type
impl Wallet {
    fn balance(&self) -> u64 {
        self.account.balance()
    }
}
let bal = wallet.balance();

// Prefer: call the inner type's method directly
let bal = wallet.account.balance();

Tracing

• Use structured tracing with key-value fields for all dynamic data. Keep the message string static.
• Use % for Display values and ? for Debug values.
• Write info!(block = %block_number, "processed block"), not info!("processed block {block_number}").
• Write error!(error = %error, peer = %peer_id, "connection failed"), not error!("connection to {peer_id} failed: {error}").

Testing

• Keep unit tests colocated with their implementation in a #[cfg(test)] mod tests { ... } block. Do not create standalone tests.rs modules for unit tests.
• Place #[cfg(test)] mod tests { ... } at the end of the file, after all non-test code.
• Test observable behavior through public APIs. Do not create tautological or change-detector tests that duplicate production logic or assert incidental implementation details.
  • Tests should fail for behavior regressions and survive behavior-preserving refactors.
  • Interaction assertions are appropriate only when the interaction itself is part of the contract.
• For test doubles of internal traits, default to #[cfg_attr(test, mockall::automock)] rather than hand-rolling a fake. See crates/consensus/service/src/actors/*/client.rs, crates/consensus/service/src/actors/network/gossip.rs, crates/consensus/service/src/follow/local.rs, and crates/consensus/service/src/follow/source.rs.
• Hand-roll a fake only when automock cannot express the required behavior, such as:
  • A trait method returns a non-constructible builder type like Alloy's ProviderCall or EthGetBlock.
  • The double needs one call log ordered across multiple trait methods.
  • Tests must mutate scripted responses while calls are in flight.
• Document the specific reason for a hand-rolled fake in its module doc comment. Examples live in crates/consensus/service/src/test_utils/fake_engine_client.rs and fake_l1.rs.

Recurring Review Expectations

• Keep changes scoped; split unrelated refactors and remove code and dependencies your change makes unused.
• Reuse existing types, APIs, and fixtures; add abstractions or configuration only for concrete supported use cases.
• Prefer domain types and named constants over magic strings and numbers; name values by their meaning and units.
• Keep modules and actor loops focused; put state-specific logic on the type that owns it.
• Document contracts and non-obvious reasons, not code narration or change history; keep docs consistent with behavior.
• Preserve historical fork behavior and parity across execution paths; test both old and new fork behavior.
• Cost hot-path work at its production frequency, not per call. Hot paths and their rates are listed in docs/guides/HOT_PATH_PERFORMANCE_REVIEW.md. Keep allocation, cloning, serialization, I/O, and metric-handle lookups out of per-candidate work, and do not scan pool-sized collections per candidate or rejection.
• Measure default-off features with the feature enabled, and benchmark production code when claiming performance gains.
• Make async lifetimes explicit: bound waits, distinguish retryable from terminal errors, and clean up tasks on failure and shutdown.