whackur 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 (prefervm.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
--verifywith--etherscan-api-keyfor 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: Useforge-std/console.solfor 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 controlrun_single_test: Target specific test functions for fast iteration
Artifacts & Inspection:
get_abi: Extract ABI from compiled contractsget_bytecode: Get deployment or runtime bytecodeinspect_storage: Inspect storage layout for optimization or debugginggas_snapshot: Generate and compare gas reports across test runsestimate_gas: Estimate gas for specific function calls
Deployment:
dry_run_deploy: Simulate deployment to catch errors before broadcastingcheck_deployment_status: Verify deployment transaction status
Security (Pre-commit):
run_slither: Static analysis before pushing coderun_aderyn: Fast Rust-based vulnerability scanmatch_vulnerability_patterns: Quick pattern check on changed files
References
Detailed command references and patterns can be found in Foundry Cheatsheet.