GO — Healthy across the board

• Last commit today
• 23+ active contributors
• Distributed ownership (top contributor 24% of recent commits)
• Apache-2.0 licensed
• CI configured
• Tests present

_{Computed from maintenance signals — commit recency, contributor breadth, bus factor, license, CI, tests}

Foundry is a Rust-native toolkit for Ethereum smart contract development that replaces the typical JavaScript/Hardhat workflow. It comprises four core tools: Forge (contract compiler, test runner, and debugger with fuzzing support), Cast (CLI for interacting with EVM contracts and chain data), Anvil (fast local Ethereum node with fork capabilities), and Chisel (Solidity REPL). It's built entirely in Rust for performance and portability, eliminating Node.js dependencies. Monorepo with 24+ interdependent crates in crates/ directory. Core architecture: crates/forge/ contains the Solidity compiler and test executor, crates/anvil/ is the local node (split into core, RPC, and server subcrates), crates/cast/ wraps contract interaction, crates/evm/evm/ is the EVM interpreter, and crates/cheatcodes/ provides test utilities. crates/cli/ unifies all tools into single forge, cast, anvil, chisel binaries. Shared logic lives in crates/primitives/, crates/common/, crates/config/.

Solidity developers and smart contract engineers who want faster compilation, testing, and deployment cycles. Contributors include protocol developers working on Ethereum tooling, security researchers building fuzzing and debugging infrastructure, and DeFi developers needing performant local development environments. It's for teams tired of Hardhat's JavaScript overhead.

Highly mature and production-ready. The v1.7.1 release and extensive CI setup (24+ GitHub workflows) indicate active maintenance. 8.7M lines of Rust code with comprehensive test coverage, multiple release templates, and benchmarking infrastructure show professional-grade stability. Actively developed with regular contributions and community support channels (Telegram).

Low risk for a mature project, but monitor: (1) Rust version constraint (1.89+) means compiler updates can cause friction; (2) Large monorepo with 24 workspace crates creates coordination overhead for major refactors; (3) Heavy dependency on Ethereum protocol internals (fork handling, EVM simulation) means network upgrades require active response. Breaking changes in Solidity versions or EVM implementations can ripple through the codebase.

Active development on EVM coverage (crates/evm/coverage/), fuzzing improvements (crates/evm/fuzz/), and documentation generation (crates/doc/). CI workflows show focus on benchmark regression testing (benchmarks-nightly.yml), flaky test isolation, and integration testing. The recent addition of Chisel (Solidity REPL) and MPP (multichain protocol) workflows suggest expanding beyond single-chain dev.

git clone https://github.com/foundry-rs/foundry.git
cd foundry
cargo build --release
# or use the curl installer: curl -L https://foundry.paradigm.xyz | bash && foundryup

Then verify: forge --version and anvil --version.

Daily commands: Development: cargo build for debug, cargo build --release for optimized binaries. Testing: cargo test --all (uses nextest config for parallel runs). Run individual tools: ./target/release/forge --help, ./target/release/anvil, ./target/release/cast. Local example: forge init counter && cd counter && forge build && forge test.

• Cargo.toml — Workspace root configuration that defines all 18+ member crates and shared package metadata—essential for understanding build order and dependencies
• crates/forge/Cargo.toml — Core forge testing framework crate; main entry point for contract testing, compilation, and deployment orchestration
• crates/anvil/bin/main.rs — Anvil local Ethereum node entry point; demonstrates the complete CLI initialization and RPC server bootstrap pattern
• crates/evm/evm/src — EVM execution engine core; handles bytecode execution, state transitions, and gas accounting—load-bearing for all testing
• crates/cli/src — CLI argument parsing and routing logic; shows how forge, cast, and anvil commands are dispatched
• crates/config/src — Foundry configuration schema (foundry.toml parsing); all tooling depends on this for project settings
• .github/workflows/ci.yml — Primary CI/CD pipeline defining test matrix, coverage gates, and release triggers

Add a new forge command or subcommand

1. Define a new command struct with clap derive macros in the appropriate module (crates/cli/src/cmd)
2. Add command variant to the main enum in crates/cli/src/lib.rs (crates/cli/src/lib.rs)
3. Implement execute() handler that calls corresponding forge logic (crates/forge/src/lib.rs)
4. Write integration tests in crates/forge/tests (crates/forge/tests)
5. Update CLI markdown docs to keep help text in sync (crates/cli-markdown/src)

Add a new EVM opcode or builtin

1. Define opcode enum variant in crates/evm/core/src/opcode.rs (crates/evm/core/src)
2. Implement execution logic in the Interpreter match statement (crates/evm/evm/src/interpreter)
3. Add gas cost calculation to the gas metering module (crates/evm/evm/src/gas.rs)
4. Write unit tests and integration tests in crates/evm/evm/tests (crates/evm/evm/tests)

Add a new RPC method to anvil

1. Define request/response DTO in crates/anvil/rpc/src/request.rs and response.rs (crates/anvil/rpc/src)
2. Add handler to the RpcHandler in crates/anvil/server/src (crates/anvil/server/src)
3. Implement method logic using anvil core types (blocks, txs, wallet state) (crates/anvil/core/src)
4. Add integration test calling the RPC method via HTTP/WS (crates/anvil/tests)

Add a new cheatcode to the testing harness

1. Define cheatcode signature in crates/cheatcodes/spec/src/spec.rs (crates/cheatcodes/spec/src)
2. Implement execution in crates/cheatcodes/src, typically in a module by category (crates/cheatcodes/src)
3. Wire execution into the EVM interpreter during STATICCALL detection (crates/evm/evm/src/interpreter)
4. Write Solidity test demonstrating the cheatcode in tests/ (crates/forge/tests)

• Rust — Memory safety, fearless concurrency, and zero-cost abstractions enable blazing-fast bytecode execution and parallel test runs without GC pauses
• revm (Ethereum Virtual Machine) — Pure-Rust EVM implementation avoids FFI overhead and enables fine-grained control over state, gas accounting, and tracing for testing
• Clap CLI framework — Declarative argument parsing with automatic help generation keeps CLI definition close to implementation
• JSON-RPC over HTTP/WS — Standard Ethereum RPC interface allows anvil to drop in as a local node for any Web3 client without compatibility layers
• Workspace monorepo (Cargo) — Allows incremental compilation of 18+ specialized crates while sharing dependency versions and enabling hermetic builds

• Pure-Rust EVM vs. Ethereum Go or Geth integration

  • Why: Self-contained bytecode execution avoids subprocess overhead and FFI complexity
  • Consequence: Foundry owns opcode conformance testing; new forks/opcodes require manual updates rather than inheriting from Geth

• Monolithic RPC handler in anvil vs. modular plugin architecture

  • Why: Simpler, faster path for local dev node; no serialization boundaries between methods and state
  • Consequence: Harder to extend RPC surface; new methods require core library changes rather than plugins

• Test discovery via naming convention (test) vs. explicit test registry*

  • Why: Minimal ceremony for users; mirrors familiar Hardhat/Truffle patterns
  • Consequence: Cannot run arbitrary subsets without string glob patterns; harder to support parameterized tests

• Solidity parsing via regex/AST walk vs. full compiler plugin

  • Why: Avoids tight coupling to Solc versions; enables forge fmt to work offline
  • Consequence: Custom parser must stay in sync with Solidity syntax; edge cases require manual fixes

• Replace Solidity compiler (foundry uses solc-rs, not custom Solidity parser)
• Provide web-based IDE or GUI (CLI and JSON-RPC server only)
• Support non-EVM chains or protocols
• Automatic smart contract auditing or security scanning (lint is light-weight pattern matching only)
• Production-grade blockchain (anvil state is in-memory, not persistent across restarts)
• Multi-contract deployment orchestration (cast and scripts handle simple sequencing only)

Solidity version management: Foundry uses solc-select to download Solidity compilers; without network access or cache, first compilation is slow. MSRV breakage: Rust 1.89+ requirement means GitHub runners must stay updated; older CI configs will break. EVM fork state: Anvil's --fork-url requires RPC access and caches block state locally; flaky RPC endpoints cause test flakiness. Workspace interdependencies: Changing primitives or evm/core affects all downstream crates; cargo test --all is slow (run cargo test -p <crate> for faster iteration). Chisel REPL interactions: Requires interactive terminal setup; CI/CD integration requires special handling.

• EVM Interpreter (Bytecode Execution) — Foundry wraps revm to simulate contract execution; understanding opcodes, gas metering, and stack-based execution is core to debugging test failures and writing fuzz invariants
• Cheatcodes (Test Mocking Primitives) — vm.prank, vm.deal, vm.warp are Foundry-specific injected functions that modify EVM state during tests; they're implemented via revm inspectors and are critical to understanding test isolation
• Fuzzing (Property-Based Testing) — Foundry's fuzzer generates random inputs to test invariants; crates/evm/fuzz/ contains the engine that creates mutation strategies and tracks coverage, a key differentiator from Hardhat
• Solidity Compilation Pipeline (Multi-Version, Multi-Target) — Forge manages solc version selection, remappings, and optimizer settings via foundry.toml; crates/forge/ orchestrates this and outputs both AST and bytecode for further processing
• Forking & Block Cache — Anvil's fork mode caches mainnet state locally via RPC calls and allows local mutation; critical for testing against real protocols without running a full node
• Trace Trees (EVM Call Graphs) — crates/evm/traces/ builds hierarchical execution traces; used for debugging, coverage reporting, and the Chisel REPL to show call stacks
• Contract ABI Encoding/Decoding (Solidity-EVM Type System) — Cast encodes function calls and decodes return values using ABI specs; crates/cast/ relies on type inference and solidity type rules to format CLI arguments correctly

• paradigm-research/revm — Direct upstream dependency: Foundry wraps revm's EVM implementation; understanding revm's inspector/tracer design is essential for custom EVM behavior
• alloy-rs/alloy — Parallel effort to replace ethers-rs: Foundry is gradually migrating to alloy for JSON-RPC and type handling; familiarity with alloy types (Address, U256) is increasingly important
• hardhat/hardhat — Direct competitor and inspiration: Hardhat pioneered local node + test framework pattern; Foundry learned from and improved upon its design (Rust speed, better fuzzing)
• ethereum/solidity — Upstream Solidity compiler: Foundry embeds solc binaries; breaking Solidity changes (new opcodes, IR formats) require Foundry updates
• forge-std/forge-std — Official standard library for Foundry tests: all contracts use it (Test.sol, StdStorage.sol); contributing here affects every Foundry project

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive integration tests for chisel REPL with cheatcodes

The crates/chisel/ and crates/cheatcodes/ directories exist but there's no dedicated integration test suite validating that chisel can properly execute cheatcodes (like vm.prank, vm.expectRevert, etc.) in interactive mode. This is critical since chisel is a unique interactive tool that needs to work seamlessly with the cheatcodes system. Current test coverage likely focuses on individual components rather than their integration.

• [ ] Create crates/chisel/tests/integration_cheatcodes.rs to test chisel REPL with common cheatcodes
• [ ] Add test cases for: vm.prank(), vm.expectRevert(), vm.expectEmit(), vm.startPrank()
• [ ] Validate that cheatcode state persists correctly across multiple REPL inputs
• [ ] Reference existing cheatcodes tests in crates/cheatcodes/spec/ for expected behavior patterns
• [ ] Update .github/workflows/test.yml if needed to ensure integration tests run in CI

Add GitHub workflow for validating Docker build reproducibility

The Dockerfile and .dockerignore exist, and there's a docker-publish.yml workflow, but there's no automated validation that Docker builds are reproducible across different environments. This is important for security and distribution integrity. A new workflow should verify that the same source produces identical Docker images.

• [ ] Create .github/workflows/docker-reproducibility.yml that builds the Docker image twice with SOURCE_DATE_EPOCH set
• [ ] Compare SHA256 digests of both images using 'docker inspect' or similar tooling
• [ ] Fail the workflow if digests don't match, with clear error messaging
• [ ] Reference Dockerfile's base image and build arguments to ensure proper reproducibility setup
• [ ] Add documentation about reproducible builds to CONTRIBUTING.md or a new docs/dev/DOCKER.md

Add missing unit tests for crates/config/ TOML parsing edge cases

The crates/config/ crate is central to foundry's configuration management and handles Cargo.toml, foundry.toml parsing. While basic tests likely exist, there are probably missing edge cases around inheritance, override precedence, and malformed configs that could cause silent failures or unexpected behavior in user projects. This requires deep understanding of the config schema.

• [ ] Audit crates/config/src/ for all public parsing functions and identify untested edge cases
• [ ] Add unit tests in crates/config/tests/ for: nested config inheritance with conflicting values, TOML syntax errors with helpful error messages, empty config files, config files with unknown keys
• [ ] Test precedence: CLI args > foundry.toml > Cargo.toml, with concrete examples
• [ ] Add property-based testing using proptest for fuzzing malformed TOML inputs
• [ ] Document expected config behavior in crates/config/README.md (if missing)

• Add rustdoc examples to crates/primitives/src/lib.rs for core types (Address, U256, TxKind) that are used throughout the codebase but lack usage examples in docstrings.
• Extend crates/evm/coverage/ test suite: currently minimal; add tests for edge cases in line/branch coverage calculation (empty blocks, nested loops, conditional jumps).
• Create helper CLI commands in crates/cast/ for common patterns: add a cast tx-history subcommand that decodes historical transactions from an address without manual ABI lookup, similar to existing cast call and cast send.

The Foundry codebase demonstrates a reasonable security posture with several positive indicators including release signing via Sigstore, pinned Docker base image SHAs, and comprehensive Clippy linting. However, there are opportunities for improvement: the security contact email points to an external domain (Tempo) rather than Foundry-specific contact, Docker configuration lacks explicit security hardening (non-root user, version pinning), and automated dependency scanning appears incomplete in the visible CI/CD configuration. The most critical gap is the potential confusion around the security vulnerability reporting channel. Overall, this is a mature Rust project with good foundations but could benefit from enhanced container security and clarified security policies.

• Medium · Insecure Docker Base Image SHA256 — Dockerfile, line 3. The Dockerfile uses a pinned SHA256 for the rust:1-bookworm base image, which is good practice. However, the image is pulled from Docker Hub without explicit registry verification. Additionally, the cargo-binstall download uses HTTPS but relies on SHA256 verification which could be vulnerable to supply chain attacks if the hash is compromised. Fix: Consider using a more recent base image with security patches. Implement additional verification mechanisms such as cosign signatures for the base image. For cargo-binstall, consider building from source or using a verified package manager.
• Low · Broad Clippy Linter Warnings Configuration — Cargo.toml, workspace.lints.clippy section. The workspace.lints.clippy configuration enables many warnings but appears to be incomplete (truncated at 'opt'). This could lead to inconsistent code quality checks across the project and potentially mask security-relevant linting issues if some warnings are not properly configured. Fix: Complete the clippy linter configuration. Ensure all security-relevant lints (e.g., unsafe_code, missing_safety_docs) are explicitly configured at appropriate warning levels.
• Low · Security Contact Email Redirect — SECURITY.md. The SECURITY.md file directs security reports to security@tempo.xyz instead of security@foundry.sh or a foundry-specific domain. This creates potential confusion about the correct reporting channel and could be exploited for social engineering or misdirection of vulnerability reports. Fix: Use a foundry-specific security contact email address (security@foundry-rs.com or similar). If Tempo is the maintainer, clearly document this relationship and ensure the email address is widely recognized as the official security contact.
• Low · Missing SBOM/Dependency Lock Management — .github/workflows/. While Cargo.lock is present, there is no visible Software Bill of Materials (SBOM) generation or automated dependency vulnerability scanning configured in the CI/CD workflows shown in the file structure. Fix: Implement automated SBOM generation (SPDX format) and integrate dependency scanning tools such as cargo-audit or Dependabot scanning into CI/CD pipelines. The partially visible .spdx.json artifact suggests this may already be in progress.
• Low · Incomplete Docker Build Security Context — Dockerfile. The Dockerfile does not explicitly define security contexts (no USER directive to drop root privileges, no security_opt settings visible). The Dockerfile also installs packages without specifying versions, which could introduce vulnerabilities from newer package versions. Fix: Add a non-root USER directive at the end of the Dockerfile. Pin package versions in apt install commands. Add security options like --security-opt=no-new-privileges if using compose. Consider using distroless base images for production.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/foundry-rs/foundry shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live foundry-rs/foundry repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/foundry-rs/foundry.

What it runs against: a local clone of foundry-rs/foundry — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in foundry-rs/foundry | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of foundry-rs/foundry. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/foundry-rs/foundry.git
#   cd foundry
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of foundry-rs/foundry and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "foundry-rs/foundry(\\.git)?\\b" \\
  && ok "origin remote is foundry-rs/foundry" \\
  || miss "origin remote is not foundry-rs/foundry (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "Cargo.toml" \\
  && ok "Cargo.toml" \\
  || miss "missing critical file: Cargo.toml"
test -f "crates/forge/Cargo.toml" \\
  && ok "crates/forge/Cargo.toml" \\
  || miss "missing critical file: crates/forge/Cargo.toml"
test -f "crates/anvil/bin/main.rs" \\
  && ok "crates/anvil/bin/main.rs" \\
  || miss "missing critical file: crates/anvil/bin/main.rs"
test -f "crates/evm/evm/src" \\
  && ok "crates/evm/evm/src" \\
  || miss "missing critical file: crates/evm/evm/src"
test -f "crates/cli/src" \\
  && ok "crates/cli/src" \\
  || miss "missing critical file: crates/cli/src"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/foundry-rs/foundry"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.