solidity-agentic-stack: Skill for Claude Code

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;
    }
}