Test smart contracts through state invariants

A contract’s security depends on state transitions across calls, not just whether each function returns the expected value in isolation. An external call, including a plain transfer of ether to a contract, transfers control to code you do not own, which can call back before the original operation has finished, the on-chain form of the check-then-act race in /domains/appsec/business-logic/transaction-races/. The OWASP Smart Contract Top 10 (2026) lists this as SC08:2026 Reentrancy Attacks (SC05 in the 2025 edition). Ordering, authorization and accounting must remain valid at every externally observable boundary. Cross-function reentrancy is not hypothetical: a bug in the Vyper compiler's named reentrancy locks (CVE-2023-39363, versions 0.2.15, 0.2.16 and 0.3.0) gave each function its own lock regardless of the key, which enabled the July 2023 reentrancy exploits of several Curve stable pools.

Start with invariants stated in domain terms. For a simple custody contract, recorded liabilities should not exceed the funds available to honor them, and one user must not spend another user’s credit. Define assumptions about assets, fees, external donations and administrative actions before turning these statements into tests.

The model starts with Alice credit 100, Bob credit 200 and contract funds 300. The invariant is total recorded liabilities ≤ available funds, assuming this simple asset has no fees or unusual transfer semantics. A vulnerable withdraw function sends Alice 100 before clearing her credit. At the callback boundary funds have fallen to 200 but recorded liabilities remain 300; the invariant is already false while external code can run.

Alice’s receiver calls withdraw again while her recorded credit still says 100. The nested call pays another 100 and then clears Alice’s credit. When the outer call finishes, Alice has received 200, Bob is still owed 200, and funds are only 100. Checking that Alice’s credit ends at zero misses the loss. Assert funds, each actor’s claim and total payments, not one final field.

The corrected contract below validates Alice’s claim, sets her credit to zero before the external transfer, and reverts if the transfer fails, which restores the credit. At the external-call boundary after a successful 100 payment, funds=200 and liabilities=200. A nested withdrawal is stopped twice over: the nonReentrant guard reverts it on entry, and without the guard it would find zero credit. Whether the receiver propagates that nested failure or catches it changes whether the outer call succeeds; the test must state the receiver behavior.

This is a deliberately small accounting model. Cross-function callbacks may reach other functions sharing state, and token hooks, fees, oracles, upgrades and forced asset movements change the assumptions. Keep the invariant and environmental model explicit and run the executable tests below against the real implementation.

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

import {ReentrancyGuardTransient} from
    "@openzeppelin/contracts/utils/ReentrancyGuardTransient.sol";

contract Vault is ReentrancyGuardTransient {
    mapping(address => uint256) public credit;

    function deposit() external payable {
        credit[msg.sender] += msg.value;
    }

    function withdraw() external nonReentrant {
        uint256 amount = credit[msg.sender];
        require(amount > 0, "no credit");
        credit[msg.sender] = 0; // effects before the external call
        (bool ok,) = msg.sender.call{value: amount}("");
        require(ok, "transfer failed"); // the revert restores the credit
    }
}

The vulnerable version differs only in where the credit is cleared. Nothing in it looks wrong to a test that withdraws once from an ordinary account: the bug needs a receiver contract that calls back during the payment.

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

contract VulnerableVault {
    mapping(address => uint256) public credit;

    function deposit() external payable {
        credit[msg.sender] += msg.value;
    }

    function withdraw() external {
        uint256 amount = credit[msg.sender];
        require(amount > 0, "no credit");
        (bool ok,) = msg.sender.call{value: amount}(""); // the receiver runs code here
        require(ok, "transfer failed");
        credit[msg.sender] = 0; // too late: the nested call already saw the old credit
    }
}

List entry points, privileged roles, upgrade paths, external calls, oracle inputs and state shared between functions. Specify who may pause, withdraw, change configuration or upgrade the contract. An access-control library helps implement these rules, but a mistaken administrator assignment or upgrade authority can still invalidate the intended trust model.

For withdrawals, update state before transferring control and handle transfer failure consistently. Put the reentrancy guard on every function that touches the shared accounting: protecting withdraw alone does not stop a callback from entering transfer or borrow while balances are stale. Read-only reentrancy is the same problem seen from outside: another protocol calls one of your view functions during the callback and prices assets from inconsistent state, which nonReentrantView prevents.

Begin with ordinary deposit and withdrawal tests and unauthorized-operation tests. Add a local receiver contract that attempts a callback during payment and another that rejects payment. Assert final balances, liabilities and events, not only whether a call reverted. A repair that prevents all withdrawals fails the legitimate-use requirement.

Then let Foundry generate call sequences. In the test below a handler bounds the inputs, gives the fuzzer three actors including the malicious receiver, and counts successful withdrawals; invariant_solvent checks the balance against total credit after every call, and afterInvariant fails the run if no withdrawal ever happened. Pointed at the vulnerable contract, the same suite fails within a few calls; against the corrected contract it passes 256 runs of 50 calls each.

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

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

// Receiver R1: withdraws again while it is being paid, and swallows the failure.
contract Reenterer {
    Vault public immutable vault;
    bool private inside;

    constructor(Vault v) {
        vault = v;
    }

    function deposit() external payable {
        vault.deposit{value: msg.value}();
    }

    function withdraw() external {
        vault.withdraw();
    }

    receive() external payable {
        if (inside) return;
        inside = true;
        try vault.withdraw() {} catch {}
        inside = false;
    }
}

contract Handler is Test {
    Vault public immutable vault;
    address[] public actors;
    uint256 public withdrawals; // ghost counter: proves the risky path was reached

    constructor(Vault v) {
        vault = v;
        actors.push(makeAddr("alice"));
        actors.push(makeAddr("bob"));
        actors.push(address(new Reenterer(v)));
    }

    function deposit(uint256 who, uint256 amount) external {
        address actor = actors[who % actors.length];
        amount = bound(amount, 1, 100 ether);
        vm.deal(actor == actors[2] ? address(this) : actor, amount);
        if (actor == actors[2]) {
            Reenterer(payable(actor)).deposit{value: amount}();
        } else {
            vm.prank(actor);
            vault.deposit{value: amount}();
        }
    }

    function withdraw(uint256 who) external {
        address actor = actors[who % actors.length];
        if (vault.credit(actor) == 0) return;
        if (actor == actors[2]) {
            Reenterer(payable(actor)).withdraw();
        } else {
            vm.prank(actor);
            vault.withdraw();
        }
        withdrawals++;
    }

    function liabilities() external view returns (uint256 total) {
        for (uint256 i; i < actors.length; i++) total += vault.credit(actors[i]);
    }
}

contract VaultInvariantTest is Test {
    Vault internal vault;
    Handler internal handler;

    function setUp() public {
        vault = new Vault();
        handler = new Handler(vault);
        targetContract(address(handler));
    }

    // Recorded liabilities never exceed the funds that back them.
    function invariant_solvent() public view {
        assertGe(address(vault).balance, handler.liabilities());
    }

    // A run that never withdraws proves nothing about the external call.
    function afterInvariant() public view {
        assertGt(handler.withdrawals(), 0, "no withdrawal was exercised");
    }
}

Reentrancy is one of ten classes in the OWASP Smart Contract Top 10 (2026); access control, business logic, oracle manipulation, flash-loan attacks, missing input validation, unchecked external calls, arithmetic rounding and precision, integer overflow and proxy upgradeability each need their own invariants and tests. Upgradeable contracts add storage-layout collisions, and signed messages add replay across chains and contracts. This guide covers none of those; the companion guide /domains/appsec/smart-contracts/defi-attack-patterns/ covers oracle manipulation, flash loans, upgradeable-proxy storage collisions and signature replay.

Review source and deployment configuration, pin compiler and dependency versions, and supplement testing with static analysis and independent review. A local invariant suite provides bounded evidence; it does not certify a deployed economic protocol or justify testing against contracts you do not control.

A test that expects every adversarial receiver transaction to revert can misclassify a safe result. R1 catches the denied nested call, so the outer legitimate withdrawal can succeed once. Assert the economic outcome rather than requiring one universal return status.

Property tests can pass vacuously if the handler selects only actors without credit, never reaches a withdrawal, or discards every reverting sequence. Track reachable deposits, successful withdrawals, callbacks and rejection cases, and keep minimized failing traces. Coverage of meaningful transitions matters more than a large iteration count alone.

Each row is a case from the state-table exercise and the state it must end in. The completed attack and both corrected cases are the three Foundry tests in the last exercise step.

Sources & further reading

The standards, specifications and documentation behind the guidance above. Each is the evidence for a claim on this page; consult it for detail beyond the defaults and versions listed here.

1. Solidity: Security Considerations
2. Foundry: Invariant Testing
3. OpenZeppelin Contracts 5.x: ReentrancyGuard and ReentrancyGuardTransient
4. OWASP Smart Contract Top 10 (2026)
5. EIP-1153: Transient storage opcodes. Final (created 15 June 2018).
6. NVD: CVE-2023-39363, Vyper named reentrancy lock allocation (Curve, July 2023)

Reference information

Tags

Business logic and race conditionsSecurity testing

SDLC phase

DesignDevelopmentTesting

Role

Developers

Download this guide as Markdown

Continue exploring