Detailed Instructions

Begin by installing the Foundry toolkit using the foundryup installer. This provides the forge, cast, anvil, and chisel command-line tools. Open a terminal and run the installation command. Once installed, create a new directory for your project and initialize it with forge init. This command generates the standard Foundry project structure, including src/ for your contracts, test/ for your test files, script/ for deployment scripts, and a foundry.toml configuration file.

• Sub-step 1: Run curl -L https://foundry.paradigm.xyz | bash and then foundryup.
• Sub-step 2: Create a project directory: mkdir my-fuzz-project && cd my-fuzz-project.
• Sub-step 3: Initialize the project: forge init --force to generate all necessary folders and files.

bashCopy
# Example installation and initialization commands
curl -L https://foundry.paradigm.xyz | bash
foundryup
forge init my-fuzz-project

Tip: Use the --force flag with forge init if the directory is not empty to overwrite existing configuration files.

Detailed Instructions

The foundry.toml file controls the behavior of the forge test runner. For fuzzing, you must adjust key parameters under the [fuzz] and [profile.default] sections. The fuzz runs setting defines how many random inputs are generated for each test. The fuzz seed allows for deterministic test reproduction. Increase the fuzz max test rejections to handle complex preconditions. Under the default profile, you can set the gas limit and enable FFI if your tests require external calls.

• Sub-step 1: Open foundry.toml in your project root.
• Sub-step 2: Add or modify the [fuzz] section, setting runs = 10_000 and seed = "12345".
• Sub-step 3: In [profile.default], ensure gas_limit = 30000000 and ffi = true if needed.

tomlCopy
# Example foundry.toml configuration
[fuzz]
runs = 10000
seed = "12345"
max_test_rejections = 65536

[profile.default]
gas_limit = 30000000
ffi = true

Tip: A higher runs value increases coverage but slows test execution. Start with 10,000 for a balance.

Detailed Instructions

Fuzz tests validate invariants—properties that should always hold true. Write a simple contract, such as a token or vault, that maintains explicit invariants. For a Token contract, key invariants include: total supply consistency, non-negative balances, and allowance sums. Use the invariant_ prefix in your test function names later to target these properties. The contract should have functions that modify state (like transfer or mint) which the fuzzer will call with random inputs to try and break the defined rules.

• Sub-step 1: In src/, create Token.sol with totalSupply, balanceOf mapping, and a transfer function.
• Sub-step 2: Implement logic that maintains the invariant totalSupply == sum(balances).
• Sub-step 3: Add a mint function that increases both a user's balance and the total supply.

solidityCopy
// Example invariant-heavy contract snippet
contract Token {
    mapping(address => uint256) public balanceOf;
    uint256 public totalSupply;

    function mint(address to, uint256 amount) external {
        balanceOf[to] += amount;
        totalSupply += amount; // Invariant: totalSupply must always equal sum of balances
    }
}

Tip: Design invariants that are simple, atomic, and fundamental to the contract's correctness.

Detailed Instructions

In the test/ directory, create a test contract that extends forge-std's Test contract. Define a setUp() function to deploy your target contract and initialize a handler contract that will be called by the fuzzer. Write functions prefixed with invariant_ that assert a condition which must never be false, such as invariant_totalSupplyConsistency(). The fuzzer will randomly call functions on the handler, which in turn call the target contract, attempting to violate the invariant. Use forge test --match-contract to run specific invariant tests.

• Sub-step 1: Create test/Invariant.t.sol and import forge-std/Test.sol.
• Sub-step 2: In setUp(), deploy the Token contract and a Handler contract.
• Sub-step 3: Write function invariant_totalSupplyEqualsSumBalances() public that asserts the condition.

solidityCopy
// Example invariant test structure
import "forge-std/Test.sol";
import "../src/Token.sol";

contract InvariantTest is Test {
    Token token;
    function setUp() public {
        token = new Token();
    }
    function invariant_totalSupplyConsistency() public view {
        // This property should never be false during fuzzing
        assert(token.totalSupply() >= 0);
    }
}

Tip: Run your invariant tests with forge test --match-test invariant to execute only the fuzzing suite.

Detailed Instructions

When an invariant test fails, Foundry provides a detailed counterexample. This includes the seed used, the sequence of function calls that broke the invariant, and the state of all variables. Analyze the call trace to understand the exact path that led to the violation. The output will show the specific arguments passed to each function. Use this information to debug your contract logic or refine your invariant definitions. You can replay the exact failing sequence using the provided seed by running forge test --match-contract YourTest --ffi --seed <seed_value>.

• Sub-step 1: Run forge test --match-contract InvariantTest -vvv for verbose output on failure.
• Sub-step 2: Locate the Failing seed and sequence of Calls in the console output.
• Sub-step 3: Reproduce the failure deterministically using the command forge test --seed 12345.

bashCopy
# Example command to run tests and see detailed output on failure
forge test --match-contract InvariantTest -vvv

Tip: The -vvv flag provides the most verbose output, showing the exact call sequence and intermediate state changes.

Detailed Instructions

Adjust the [fuzz] section in your foundry.toml file to optimize the fuzzing campaign. The fuzz dictionary and runs parameters are critical for coverage.

• Sub-step 1: Set runs = 100000 for a more thorough exploration of the state space.
• Sub-step 2: Enable dictionary_weight = 40 to bias the fuzzer towards using known values from your contract's storage and constants.
• Sub-step 3: Configure include_storage = true and include_push_bytes = true to automatically populate the dictionary with on-chain data.

tomlCopy
[fuzz]
runs = 100000
dictionary_weight = 40
include_storage = true
include_push_bytes = true

Tip: For invariant tests, consider setting a lower runs value (e.g., 5000) for faster iteration, then increase it for final validation.

Detailed Instructions

Use the targetSelector cheatcode to focus fuzzing on a subset of your contract's functions. This is essential for differential fuzzing or testing complex interactions where random entry points are inefficient.

• Sub-step 1: In your test's setUp() function, call vm.targetSelector(bytes4 selector).
• Sub-step 2: Calculate the function selector, e.g., bytes4(keccak256("swapExactTokensForTokens(uint256,uint256,address[],address,uint256)")).
• Sub-step 3: The fuzzer will now primarily call functions matching this selector, generating inputs for their specific parameters.

solidityCopy
function setUp() public {
    // Focus fuzzing only on the 'swap' function
    bytes4 swapSelector = bytes4(keccak256("swapExactTokensForTokens(uint256,uint256,address[],address,uint256)"));
    vm.targetSelector(swapSelector);
}

Tip: You can call targetSelector multiple times to build a set of allowed functions, or use vm.targetContract(address) to focus on a specific contract in a multi-contract setup.

Detailed Instructions

Differential fuzzing compares the outputs of two systems given the same inputs. Deploy both your new Vault and a reference VaultReference contract.

• Sub-step 1: In the test's setUp(), deploy both contract implementations.
• Sub-step 2: In a forge test function with the fuzz modifier, perform the same state-changing operation on both contracts (e.g., deposit(amount)).
• Sub-step 3: Assert that key state variables (like user balance or total supply) match between the two contracts after the operation.

solidityCopy
function testFuzz_depositMatchesReference(uint96 amount) public {
    // Act on both systems
    vault.deposit(amount);
    referenceVault.deposit(amount);

    // Assert state equivalence
    assertEq(vault.balanceOf(address(this)), referenceVault.balanceOf(address(this)));
    assertEq(vault.totalSupply(), referenceVault.totalSupply());
}

Tip: Use vm.assume() to constrain fuzz inputs (e.g., vm.assume(amount <= type(uint96).max)) to avoid trivial reverts and focus on meaningful test cases.

Detailed Instructions

The vm.skip(bool condition) cheatcode allows you to halt execution of the current fuzz run if a condition is met, saving time. This is useful for input validation pre-checks.

• Sub-step 1: At the start of your fuzz test, identify inputs that would cause the contract to revert immediately with a custom error or require.
• Sub-step 2: Use vm.skip() with the condition that triggers this revert. For example, skip if a fuzzed address is the zero address.
• Sub-step 3: The fuzzer will discard this run and generate a new one, focusing computational effort on valid, interesting scenarios.

solidityCopy
function testFuzz_transferToNonZeroAddress(address to, uint256 amount) public {
    // Skip runs where 'to' is address(0), as transfer will revert
    vm.skip(to == address(0));

    // Also skip if the amount exceeds the sender's balance for a cleaner test
    vm.skip(amount > balanceOf[sender]);

    // Proceed with the core test logic...
    bool success = token.transferFrom(sender, to, amount);
    assertTrue(success);
}

Tip: Combine vm.skip() with vm.assume() for complex preconditions; assume reverts and consumes gas, while skip is cheaper and simply aborts the run.

Detailed Instructions

After running forge test --match-contract FuzzTest --fuzz-runs 50000, analyze the console output. Key metrics include unique reverts, total counterexamples, and code coverage.

• Sub-step 1: Look for the "Fuzzing" section in the output. Note the number of runs completed and any failing counterexample with calldata.
• Sub-step 2: Run forge coverage --report debug to generate a coverage report. Identify lines or branches in your src/ that were never executed during fuzzing.
• Sub-step 3: For each unique revert reason (e.g., "InsufficientBalance"), determine if it represents a legitimate bug or an expected guard. If expected, consider using vm.expectRevert() to make the test more precise.

bashCopy
# Example forge test output snippet
[PASS] testFuzz_withdraw(uint256) (runs: 50000, μ: 92506, ~: 102831)
  
[FAIL. Reason: InsufficientBalance] testFuzz_deposit(uint256) (runs: 50000, μ: 92506, ~: 102831)
  Counterexample: calldata=0x...0000000000000000000000000000000000000000000000000000000000000000 (args: [0])

Tip: A high number of unique reverts may indicate your fuzz inputs are too unconstrained. Use vm.assume or vm.skip to refine the input domain.

Detailed Instructions

When a fuzz test fails, Foundry outputs the specific calldata seed that triggered the failure. Use the -m flag with the test function name and the --ffi seed to reproduce it deterministically. First, run the test with forge test --match-test testFunctionName -vvv to see the detailed logs and the failing seed. Then, execute forge test --match-test testFunctionName --ffi <FAILING_SEED> to run only that specific scenario. This confirms the failure is reproducible and not a fluke. Check the console for the reverted reason and the state of storage variables printed in the trace.

Tip: The -vvvv flag provides a full stack trace, showing the exact line where the revert occurred within your contract or test.

Detailed Instructions

Foundry's verbose traces are essential for debugging. After reproducing the failure, analyze the output with -vvv or higher. Focus on the sequence of contract calls and storage changes. Look for unexpected state transitions or violated pre-conditions. Key details include:

• Call Sequence: Identify which external call or internal function triggered the revert.
• Storage Logs: Check STORAGE changes for variables like balance, allowance, or custom mapping states. An unexpected final state indicates a logic flaw.
• Event Logs: Missing or incorrect events can signal that a critical function path was not executed.

Cross-reference this trace against your invariant to understand which condition was broken.

Detailed Instructions

The failing seed corresponds to specific fuzz input values. Foundry logs these values (e.g., uint256 a, address sender). Decode these to understand the edge case. For example, a failure might occur when an input is zero, at a maximum uint256 value, or a specific address like the zero address. Write a simple test in your setUp() to log these values during the failing run. Analyze how these inputs flow through your contract's logic. Common issues include arithmetic overflow/underflow, incorrect access control for certain addresses, or logic that doesn't handle boundary values.

solidityCopy
// Example of logging a fuzz input in a test
function testFuzz(uint256 amount, address recipient) public {
    console.log("Fuzz Input - amount:", amount, "recipient:", recipient);
    // ... test logic
}

Detailed Instructions

Once you have the inputs and trace, create a new, focused test that isolates the bug. Comment out unrelated setup and assertions. Your goal is to write the smallest possible test that still fails. This often involves:

• Hardcoding the failing fuzz inputs directly into a test function (not a testFuzz).
• Reducing the number of interacting contracts or calls to the essential path.
• Checking intermediate values with console.log to see where calculations diverge from expectations.

This process transforms a complex, randomly-generated failure into a clear, deterministic bug report. It separates the invariant violation from any noise in the broader test setup.

Detailed Instructions

Based on the isolated bug, decide whether the issue is in the contract implementation or the test invariant. If the contract is wrong, apply a targeted fix, such as adding a missing check for zero address, using SafeMath libraries, or correcting a state update. If the invariant is too strict (i.e., the contract behavior is correct but your test assumption was wrong), refine the invariant property. After making changes, re-run the specific failing fuzz case to verify the fix. Finally, run the full fuzz test suite (forge test) to ensure no regressions were introduced.

solidityCopy
// Example fix: Adding a zero-address check
function transfer(address to, uint256 amount) public {
    require(to != address(0), "Transfer to zero address"); // Fix applied
    balances[msg.sender] -= amount;
    balances[to] += amount;
}