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`: ```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 ```solidity // 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_); } } ``` ## Invariant Test File ```solidity // SPDX-License-Identifier: MIT pragma solidity ^0.8.20; import {Test} from "forge-std/Test.sol"; import {Vault} from "../src/Vault.sol"; import {MockERC20} from "./mocks/MockERC20.sol"; import {VaultHandler} from "./handlers/VaultHandler.sol"; contract VaultInvariantTest is Test { Vault public vault; MockERC20 public token; VaultHandler public handler; function setUp() public { token = new MockERC20("Token", "TKN", 18); vault = new Vault(address(token)); handler = new VaultHandler(vault, token); // Only target the handler — never call vault directly targetContract(address(handler)); } /// @dev Total shares == total deposits - total withdrawals function invariant_solvency() public view { assertGe( token.balanceOf(address(vault)), handler.ghost_totalDeposited() - handler.ghost_totalWithdrawn(), "vault is insolvent" ); } /// @dev Vault token balance >= total supply of shares function invariant_sharesBacked() public view { uint256 totalShares = vault.totalSupply(); uint256 totalAssets = token.balanceOf(address(vault)); if (totalShares > 0) { assertGt(totalAssets, 0, "shares exist but no assets"); } } /// @dev No individual user has more shares than total supply function invariant_noShareInflation() public view { address[] memory actors = _getActors(); uint256 totalSupply = vault.totalSupply(); for (uint256 i = 0; i < actors.length; i++) { assertLe(vault.balanceOf(actors[i]), totalSupply); } } /// @dev Ghost tracking matches actual state function invariant_ghostAccuracy() public view { uint256 expectedVaultBalance = handler.ghost_totalDeposited() - handler.ghost_totalWithdrawn(); assertEq( token.balanceOf(address(vault)), expectedVaultBalance, "ghost tracking diverged" ); } function _getActors() internal view returns (address[] memory) { address[] memory actors = new address[](5); for (uint256 i = 0; i < 5; i++) { actors[i] = handler.actors(i); } return actors; } } ``` ## Common DeFi Invariants ### Lending Protocol ```solidity function invariant_totalDebtLeTotalSupply() public view { assertLe(pool.totalDebt(), pool.totalSupply()); } function invariant_allPositionsCollateralized() public view { // For each borrower, collateral * LTV >= debt } ``` ### AMM / DEX ```solidity function invariant_constantProduct() public view { uint256 k = pool.reserve0() * pool.reserve1(); assertGe(k, initialK, "k decreased"); // k should only increase (fees) } function invariant_lpTokensBacked() public view { // LP tokens redeemable for proportional reserves } ``` ### Staking ```solidity function invariant_rewardsSolvent() public view { assertGe(rewardToken.balanceOf(address(staking)), staking.totalPendingRewards()); } function invariant_totalStakedMatchesSum() public view { uint256 sum = 0; for (uint256 i = 0; i < actors.length; i++) { sum += staking.balanceOf(actors[i]); } assertEq(sum, staking.totalSupply()); } ``` ## Target Configuration ```solidity // Target specific contract targetContract(address(handler)); // Target specific functions (exclude admin/setup) bytes4[] memory selectors = new bytes4[](3); selectors[0] = VaultHandler.deposit.selector; selectors[1] = VaultHandler.withdraw.selector; selectors[2] = VaultHandler.warpTime.selector; targetSelector(FuzzSelector({addr: address(handler), selectors: selectors})); // Exclude senders excludeSender(address(vault)); // don't call as the vault itself ``` ## Checklist - [ ] Handler wraps all user-facing functions with input bounding - [ ] Ghost variables track expected state changes - [ ] Actor pool covers multiple users with pre-approved balances - [ ] `bound()` constrains all numeric inputs to valid ranges - [ ] Handler functions silently return on invalid preconditions (don't revert) - [ ] `targetContract()` points to handler, not the system under test - [ ] Invariant functions start with `invariant_` prefix - [ ] Time progression handler included for time-dependent protocols - [ ] Run with sufficient depth (64+) and runs (256+) for confidence