invariant-testing

Foundry Invariant Testing

Overview

Invariant tests execute random sequences of function calls against handler contracts and assert that system invariants hold after every call. Unlike stateless fuzz tests, invariant tests maintain state across calls, exploring complex state transitions.

Configuration

In foundry.toml:

[invariant]
runs = 256          # number of random sequences
depth = 64          # calls per sequence
fail_on_revert = false  # don't fail on handler reverts (expected)

Handler Contract Template

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

import {Test} from "forge-std/Test.sol";
import {CommonBase} from "forge-std/Base.sol";
import {StdCheats} from "forge-std/StdCheats.sol";
import {StdUtils} from "forge-std/StdUtils.sol";
import {Vault} from "../../src/Vault.sol";
import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";

contract VaultHandler is CommonBase, StdCheats, StdUtils {
    Vault public vault;
    IERC20 public token;

    // Ghost variables track expected state
    uint256 public ghost_totalDeposited;
    uint256 public ghost_totalWithdrawn;
    mapping(address => uint256) public ghost_userDeposits;

    // Actors for randomized msg.sender
    address[] public actors;
    address internal currentActor;

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

    constructor(Vault _vault, IERC20 _token) {
        vault = _vault;
        token = _token;

        // Create actor pool
        for (uint256 i = 0; i < 5; i++) {
            address actor = address(uint160(0x1000 + i));
            actors.push(actor);
            deal(address(token), actor, 1_000_000e18);
            vm.prank(actor);
            token.approve(address(vault), type(uint256).max);
        }
    }

    function deposit(uint256 actorSeed, uint256 amount) external useActor(actorSeed) {
        amount = bound(amount, 1e18, 100_000e18);

        uint256 balance = token.balanceOf(currentActor);
        if (balance < amount) return; // skip if insufficient

        vault.deposit(amount);

        ghost_totalDeposited += amount;
        ghost_userDeposits[currentActor] += amount;
    }

    function withdraw(uint256 actorSeed, uint256 amount) external useActor(actorSeed) {
        uint256 staked = vault.balanceOf(currentActor);
        if (staked == 0) return; // skip if nothing to withdraw

        amount = bound(amount, 1, staked);

        vault.withdraw(amount);

        ghost_totalWithdrawn += amount;
        ghost_userDeposits[currentActor] -= amount;
    }

    function warpTime(uint256 seconds_) external {
        seconds_ = bound(seconds_, 1, 7 days);
        skip(seconds_);
    }
}