foundry-invariants

Foundry Invariants

Invariant tests assert properties that must hold across any sequence of state transitions. They are the protocol's constitution. If an invariant breaks, the protocol is broken — fix the implementation, never weaken the invariant.

When to use this skill

• Writing a new invariant suite for a fresh protocol
• Adding an invariant to an existing suite
• Debugging an invariant break (e.g. INV-1 fails after 1024 calls)
• Designing a handler to drive multi-actor state
• Adding ghost variables to track cumulative state
• Onboarding to this repo's test/invariant/VaultInvariant.t.sol

The contract — INV-1 and INV-2 in this stack

INV-1: address(vault).balance == vault.totalDeposits()
INV-2: ghost_totalDeposited - ghost_totalWithdrawn == vault.totalDeposits()

INV-1 is a balance ↔ accounting invariant — catches donation attacks, force-send drift, missing state updates. INV-2 is a flow conservation invariant — catches accounting bugs by reconciling external observations (ghost vars in the handler) against on-chain state.

Anatomy of an invariant suite

test/
├── handlers/
│   └── VaultHandler.sol      # drives actors through the state machine
└── invariant/
    └── VaultInvariant.t.sol  # the invariant_* functions

Handler — drives randomized actions

contract VaultHandler is Test {
    Vault public vault;
    address[] public actors;

    // Ghost variables — track cumulative state across calls
    uint256 public ghost_totalDeposited;
    uint256 public ghost_totalWithdrawn;

    constructor(Vault _vault) {
        vault = _vault;
        for (uint256 i; i < 5; i++) {
            actors.push(makeAddr(string.concat("actor", vm.toString(i))));
            vm.deal(actors[i], 1_000 ether);
        }
    }

    function deposit(uint256 actorSeed, uint256 amount) public {
        address actor = actors[bound(actorSeed, 0, actors.length - 1)];
        amount = bound(amount, 1, actor.balance);

        vm.prank(actor);
        vault.deposit{value: amount}();

        ghost_totalDeposited += amount;
    }

    function withdraw(uint256 actorSeed, uint256 amount) public {
        address actor = actors[bound(actorSeed, 0, actors.length - 1)];
        uint256 bal = vault.balanceOf(actor);
        if (bal == 0) return;
        amount = bound(amount, 1, bal);

        vm.prank(actor);
        vault.withdraw(amount);

        ghost_totalWithdrawn += amount;
    }
}