Foundry Development Guide

When to Apply

Apply this skill when working on Solidity projects using the Foundry toolkit. This includes setting up new projects, writing unit and integration tests, performing fuzz and invariant testing, simulating mainnet conditions via fork testing, and managing deployments using Solidity scripts.

Project Setup

Initialize a project with forge init. Manage dependencies using forge install <author>/<repo>. Configure foundry.toml for remappings, optimizer settings, and EVM versions. Use remappings.txt to simplify imports (e.g., @openzeppelin/=lib/openzeppelin-contracts/contracts/).

Testing Best Practices

Test Structure

Tests should inherit from forge-std/Test.sol. Use setUp() for state initialization.

• test_Xxx: Standard test case.
• testFuzz_Xxx: Fuzz test case.
• testFail_Xxx: Test expected to fail (prefer vm.expectRevert).

Fuzz Testing

Foundry automatically provides random inputs for function arguments in testFuzz functions. Use vm.assume() to filter inputs or bound(uint256 x, uint256 min, uint256 max) to constrain values.

Invariant Testing

Stateful fuzzing that ensures properties hold across multiple transactions.

• targetContract(address): Define the contract to test.
• handler: Use a dedicated contract to manage complex call sequences and state transitions.

Fork Testing

Simulate mainnet state by providing a RPC URL.

• vm.createFork(url): Create a fork.
• vm.selectFork(id): Switch to a fork.
• vm.rollFork(blockNumber): Pin the fork to a specific block.

Essential Cheatcodes

Cheatcode	Description
vm.prank(addr)	Sets msg.sender for the next call.
vm.startPrank(addr)	Sets msg.sender for all subsequent calls until stopPrank.
vm.deal(addr, amt)	Sets the balance of an address.
vm.expectRevert(bytes)	Expects the next call to revert with a specific error.
vm.expectEmit(bool,bool,bool,bool)	Expects the next call to emit a specific event.
vm.warp(timestamp)	Sets the block timestamp.
vm.roll(blockNumber)	Sets the block number.
vm.sign(pk, digest)	Generates an ECDSA signature.
vm.label(addr, name)	Labels an address for better trace readability.
vm.record()	Starts recording all storage reads and writes.
vm.getCode(path)	Returns the creation bytecode of a contract.

Deployment Workflow

Use forge script for Solidity-based deployments.

• Dry-run: forge script script/Deploy.s.sol --rpc-url $RPC_URL
• Broadcast: forge script script/Deploy.s.sol --rpc-url $RPC_URL --broadcast --verify
• Use --verify with --etherscan-api-key for automatic source verification.

Debugging

• Verbosity: -v (logs), -vv (traces for failed tests), -vvv (traces for all tests), -vvvv (setup traces), -vvvvv (full stack traces).
• forge debug: Interactive debugger for a specific transaction.
• console.log: Use forge-std/console.sol for print debugging.

Configuration Profiles

Use profiles in foundry.toml to manage different build configurations.

[profile.via_ir]
via_ir = true
test = 'src'
out = 'via_ir-out'

[profile.deterministic]
block_number = 17722462
block_timestamp = 1689711647
bytecode_hash = 'none'
cbor_metadata = false

Enhanced with MCP

When the solidity-agent-toolkit is available, leverage these tools in your Foundry workflow:

Build & Test:

• compile_contract: Compile contracts and get artifact output (ABI, bytecode, errors)
• run_tests: Execute the full Foundry test suite with verbosity control
• run_single_test: Target specific test functions for fast iteration

Artifacts & Inspection:

• get_abi: Extract ABI from compiled contracts
• get_bytecode: Get deployment or runtime bytecode
• inspect_storage: Inspect storage layout for optimization or debugging
• gas_snapshot: Generate and compare gas reports across test runs
• estimate_gas: Estimate gas for specific function calls

Deployment:

• dry_run_deploy: Simulate deployment to catch errors before broadcasting
• check_deployment_status: Verify deployment transaction status

Security (Pre-commit):

• run_slither: Static analysis before pushing code
• run_aderyn: Fast Rust-based vulnerability scan
• match_vulnerability_patterns: Quick pattern check on changed files

References

Detailed command references and patterns can be found in Foundry Cheatsheet.