智能合约与以太坊 / 系统课时

用 Invariant 测试验证状态序列

用 Invariant 测试验证状态序列

单次单元测试能够证明某次存款或提款正确,却未必能发现多次操作后的状态错误。本课使用 Foundry 的 Invariant 测试和 Handler,随机组合存款、提款、份额转移与未授权操作,持续检查资产守恒、份额边界和授权约束,并学习如何复现失败序列。

学习目标

  • 理解 Invariant 测试的状态序列执行方式,以及 runs、depth 和 Handler 的作用。
  • 编写可运行的多账户 Handler,验证资产守恒、份额总量和授权限制。
  • 配置随机测试规模,分析失败轨迹并避免无效调用造成虚假通过。

为什么需要状态序列测试

普通 Fuzz 测试通常对单次函数调用生成随机参数。Invariant 测试则在同一测试序列中反复调用目标函数,并在调用后检查系统性质是否始终成立。

假设一个简化金库以 1:1 比例接收 ETH 并发行份额,必须满足三条约束:

  1. 资产守恒:金库 ETH 余额等于累计存入减去累计提取。
  2. 份额守恒:两个测试账户的份额之和等于 totalSupply。
  3. 授权限制:没有得到授权的账户不能转走其他账户的份额。

例如,Alice 存入 10 ETH、Bob 存入 5 ETH,随后 Alice 提取 3 ETH、向 Bob 转移 2 份份额。最终金库持有 12 ETH,总份额为 12;Alice 有 5 份,Bob 有 7 份。转移只改变份额归属,不改变总供应量。

Handler 多步状态序列与不变量检查流程

runs 表示独立随机调用序列的数量,depth 表示每条序列计划执行的调用次数。一次调用即使回滚,也可能消耗一个深度位置。因此,测试是否有效还取决于 Handler 能否产生足够多的成功状态变化。

实现可测试的份额金库

使用已安装 Foundry、能够执行 forge --version 的环境。下面采用 Solidity ^0.8.20 和 forge-std,不依赖 OpenZeppelin。示例将所有已发行份额限制在两个测试账户之间,方便逐项检查。

在 Foundry 项目中创建 src/ShareVault.sol:

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

contract ShareVault {
    mapping(address => uint256) public balanceOf;
    mapping(address => mapping(address => uint256)) public allowance;
    uint256 public totalSupply;

    function deposit() external payable {
        require(msg.value > 0, "ZERO_DEPOSIT");
        // 教学模型:1 wei 对应 1 份额,排除价格和舍入因素。
        balanceOf[msg.sender] += msg.value;
        totalSupply += msg.value;
    }

    function withdraw(uint256 shares) external {
        require(balanceOf[msg.sender] >= shares, "LOW_SHARES");
        balanceOf[msg.sender] -= shares;
        totalSupply -= shares;
        // 状态先更新,再进行外部转账。
        (bool ok,) = payable(msg.sender).call{value: shares}("");
        require(ok, "ETH_SEND_FAILED");
    }

    function approve(address spender, uint256 amount) external {
        allowance[msg.sender][spender] = amount;
    }

    function transferFrom(address owner, address to, uint256 amount) external {
        require(allowance[owner][msg.sender] >= amount, "NOT_APPROVED");
        require(balanceOf[owner] >= amount, "LOW_SHARES");
        allowance[owner][msg.sender] -= amount;
        balanceOf[owner] -= amount;
        balanceOf[to] += amount;
    }
}

这不是完整的 ERC-20 或 ERC-4626 实现,不包含价格换算、事件及标准接口。它只用于验证状态序列测试方法。生产金库还需要单独检查精度舍入、费用、重入保护和标准兼容性。

用 Handler 生成有意义的多步调用

Handler 负责将随机整数转换成合法操作。这里固定 Alice 与 Bob 两个账户,利用 bound 约束提款数量,使大部分调用确实修改状态,而不是因余额不足直接回滚。

创建 test/ShareVaultInvariant.t.sol:

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

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

contract VaultHandler is Test {
    ShareVault public vault;
    address public alice = address(0xA11CE);
    address public bob = address(0xB0B);
    uint256 public ghostDeposited;
    uint256 public ghostWithdrawn;
    uint256 public successfulDeposits;
    uint256 public successfulWithdrawals;
    uint256 public unauthorizedAttempts;

    constructor(ShareVault target) {
        vault = target;
    }

    function actor(uint256 seed) public view returns (address) {
        return seed % 2 == 0 ? alice : bob;
    }

    function deposit(uint256 seed, uint256 rawAmount) external {
        address user = actor(seed);
        uint256 amount = bound(rawAmount, 1, 1 ether);
        // 测试环境提供资金,不计入金库资产。
        vm.deal(user, user.balance + amount);
        vm.prank(user);
        vault.deposit{value: amount}();
        ghostDeposited += amount;
        successfulDeposits++;
    }

    function withdraw(uint256 seed, uint256 rawAmount) external {
        address user = actor(seed);
        uint256 shares = vault.balanceOf(user);
        if (shares == 0) return;
        uint256 amount = bound(rawAmount, 1, shares);
        vm.prank(user);
        vault.withdraw(amount);
        ghostWithdrawn += amount;
        successfulWithdrawals++;
    }

    function transfer(uint256 seed, uint256 rawAmount) external {
        address owner = actor(seed);
        address receiver = owner == alice ? bob : alice;
        uint256 shares = vault.balanceOf(owner);
        if (shares == 0) return;
        uint256 amount = bound(rawAmount, 1, shares);
        // owner 授权 receiver,receiver 执行转移。
        vm.prank(owner);
        vault.approve(receiver, amount);
        vm.prank(receiver);
        vault.transferFrom(owner, receiver, amount);
    }

    function unauthorizedTransfer(uint256 seed) external {
        address owner = actor(seed);
        address attacker = address(0xBAD);
        uint256 beforeShares = vault.balanceOf(owner);
        uint256 beforeSupply = vault.totalSupply();
        // 攻击者没有获得授权,调用必须失败且状态不变。
        vm.prank(attacker);
        (bool ok,) = address(vault).call(
            abi.encodeCall(vault.transferFrom, (owner, attacker, 1))
        );
        assertFalse(ok, "UNAUTHORIZED_TRANSFER_SUCCEEDED");
        assertEq(vault.balanceOf(owner), beforeShares);
        assertEq(vault.balanceOf(attacker), 0);
        assertEq(vault.totalSupply(), beforeSupply);
        unauthorizedAttempts++;
    }
}

contract ShareVaultInvariantTest is StdInvariant, Test {
    ShareVault internal vault;
    VaultHandler internal handler;

    function setUp() public {
        vault = new ShareVault();
        handler = new VaultHandler(vault);
        // 只对 Handler 的四种业务操作进行随机调用。
        targetContract(address(handler));
        bytes4[] memory selectors = new bytes4[](4);
        selectors[0] = handler.deposit.selector;
        selectors[1] = handler.withdraw.selector;
        selectors[2] = handler.transfer.selector;
        selectors[3] = handler.unauthorizedTransfer.selector;
        targetSelector(FuzzSelector({addr: address(handler), selectors: selectors}));
    }

    function invariant_assetsConserved() public view {
        assertEq(
            address(vault).balance,
            handler.ghostDeposited() - handler.ghostWithdrawn()
        );
        assertEq(address(vault).balance, vault.totalSupply());
    }

    function invariant_sharesConserved() public view {
        uint256 aliceShares = vault.balanceOf(handler.alice());
        uint256 bobShares = vault.balanceOf(handler.bob());
        assertEq(aliceShares + bobShares, vault.totalSupply());
        assertEq(vault.balanceOf(address(0xBAD)), 0);
    }

    function invariant_authorization() public view {
        assertEq(vault.allowance(handler.alice(), address(0xBAD)), 0);
        assertEq(vault.allowance(handler.bob(), address(0xBAD)), 0);
    }
}

ghostDeposited 和 ghostWithdrawn 是 Handler 的影子变量,记录累计成功存提款金额。它们独立于金库自身的 totalSupply,可以避免仅用被测合约的两个字段相互比较而遗漏同源错误。

授权检查分为两层:Handler 主动发起未授权转移并断言失败;Invariant 再检查攻击者余额和授权额度。主动攻击断言可以发现函数错误放行的情况,仅检查授权额度为零则不能做到这一点。

配置并运行随机状态序列

在项目的 foundry.toml 中添加或合并以下配置:

toml
[invariant]
runs = 256
depth = 50
fail_on_revert = true
show_metrics = true

这相当于为每个 Invariant 测试配置 256 条随机序列,每条最多安排 50 次调用。fail_on_revert = true 适用于本例:Handler 已处理正常前置条件,未授权操作的预期回滚也已通过低级调用捕获。

在项目根目录执行:

bash
forge test --match-contract ShareVaultInvariantTest -vvv

预期结果:编译成功且三个 invariant_ 测试均显示 [PASS]。日志中的 runs、calls、reverts 和耗时随 Foundry 版本及测试执行情况变化,不应要求固定数值。

重点检查 successfulDeposits、successfulWithdrawals 和 unauthorizedAttempts 对应的 Handler 调用是否被实际覆盖。需要注意,Handler 中遇到零份额后直接返回,不代表一次有效提款;因此还应检查成功计数,而不是只看函数调用次数。

可以临时将金库 transferFrom 中的授权检查删除,再执行同一命令。预期结果:未授权转移能够执行,Handler 的 UNAUTHORIZED_TRANSFER_SUCCEEDED 断言触发,Invariant 测试失败。恢复授权检查后应重新通过。这个故障注入能证明测试真正检测了授权漏洞。

如何分析失败轨迹与提升覆盖率

Foundry 在 Invariant 失败时会给出调用序列或重放相关信息,具体输出格式随版本变化。排查应从第一个违反断言的操作开始,而不是只盯着最后的余额。

  1. 查看失败属于 assetsConserved、sharesConserved 还是授权断言。
  2. 使用 forge test --match-contract ShareVaultInvariantTest -vvvv 查看更详细的执行轨迹。
  3. 记录关键调用的账户、金额与顺序,在独立单元测试中固定重现。
  4. 修复后重新运行完整随机测试,并保留该固定回归用例。

对于真实 ERC-4626 金库,还应增加 mint、redeem、transfer 和收益变化操作。份额与资产不再总是 1:1,因此不能直接要求金库资产余额等于份额供应量;必须根据协议定义的舍入方式、捐赠处理和债务口径建立新的守恒关系。

建议开发阶段采用 runs = 256、depth = 50,在 CI 中根据运行时间逐步增加到 runs = 1000、depth = 100。同时保留确定性的漏洞回归测试,检查实际执行覆盖率,并确保每条安全性质都有可以触发失败的反例。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

用 Invariant 测试验证状态序列

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通