The Complete Production SOP: How to Deploy and Run Foundry Forge Invariant Tests & Fuzzing in Autonomous AI Agents

---
name: "foundry-forge-invariant-testing"
description: "Write blazing-fast property-based fuzz tests and invariant checks in native Solidity."
metadata:
  author: "Foundry"
  version: "1.0.0"
  runtime_compatibility:
    - "codex"
    - "claude-code"
    - "cursor"
    - "windsurf"
triggers:
  - "write foundry invariant test"
  - "run forge test fuzzing"
  - "create handler based fuzzing foundry"
permissions:
  fs_read: true
  fs_write: "workspace"
  shell_exec: false
  net_access: false
---

[profile.default]
src = "src"
out = "out"
libs = ["lib"]

[invariant]
runs = 256
depth = 32
fail_on_revert = false
call_override = false
dictionary_weight = 80

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

import {Test} from "forge-std/Test.sol";
import {ERC20Vault} from "../../src/ERC20Vault.sol";

contract Handler is Test {
    ERC20Vault public immutable vault;
    uint256 public ghost_totalDeposited;
    address[] public actors;
    address internal currentActor;

    constructor(ERC20Vault _vault) {
        vault = _vault;
        actors.push(address(0xAAAA));
        actors.push(address(0xBBBB));
    }

    modifier useActor(uint256 actorIndexSeed) {
        currentActor = actors[bound(actorIndexSeed, 0, actors.length - 1)];
        vm.startPrank(currentActor);
        _;
        vm.stopPrank();
    }

    function deposit(uint256 actorSeed, uint256 amount) external useActor(actorSeed) {
        amount = bound(amount, 1, 100_000 ether);
        deal(address(vault.asset()), currentActor, amount);
        vault.asset().approve(address(vault), amount);
        vault.deposit(amount, currentActor);
        ghost_totalDeposited += amount;
    }
}

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

import {Test} from "forge-std/Test.sol";
import {ERC20Vault} from "../../src/ERC20Vault.sol";
import {Handler} from "../handlers/Handler.sol";

contract VaultInvariants is Test {
    ERC20Vault public vault;
    Handler public handler;

    function setUp() public {
        vault = new ERC20Vault();
        handler = new Handler(vault);

        targetContract(address(handler));
        bytes4[] memory selectors = new bytes4[](1);
        selectors[0] = Handler.deposit.selector;
        targetSelector(FuzzSelector({addr: address(handler), selectors: selectors}));
    }

    function invariant_vaultAssetsMatchGhostDeposits() public view {
        assertEq(
            vault.totalAssets(),
            handler.ghost_totalDeposited(),
            "Solvency invariant broken: vault assets diverge from ghost deposits"
        );
    }
}