智能合约与以太坊 / 系统课时
用 Invariant 测试验证状态序列
用 Invariant 测试验证状态序列
单次单元测试能够证明某次存款或提款正确,却未必能发现多次操作后的状态错误。本课使用 Foundry 的 Invariant 测试和 Handler,随机组合存款、提款、份额转移与未授权操作,持续检查资产守恒、份额边界和授权约束,并学习如何复现失败序列。
学习目标
- 理解 Invariant 测试的状态序列执行方式,以及
runs、depth和 Handler 的作用。 - 编写可运行的多账户 Handler,验证资产守恒、份额总量和授权限制。
- 配置随机测试规模,分析失败轨迹并避免无效调用造成虚假通过。
为什么需要状态序列测试
普通 Fuzz 测试通常对单次函数调用生成随机参数。Invariant 测试则在同一测试序列中反复调用目标函数,并在调用后检查系统性质是否始终成立。
假设一个简化金库以 1:1 比例接收 ETH 并发行份额,必须满足三条约束:
- 资产守恒:金库 ETH 余额等于累计存入减去累计提取。
- 份额守恒:两个测试账户的份额之和等于
totalSupply。 - 授权限制:没有得到授权的账户不能转走其他账户的份额。
例如,Alice 存入 10 ETH、Bob 存入 5 ETH,随后 Alice 提取 3 ETH、向 Bob 转移 2 份份额。最终金库持有 12 ETH,总份额为 12;Alice 有 5 份,Bob 有 7 份。转移只改变份额归属,不改变总供应量。

runs 表示独立随机调用序列的数量,depth 表示每条序列计划执行的调用次数。一次调用即使回滚,也可能消耗一个深度位置。因此,测试是否有效还取决于 Handler 能否产生足够多的成功状态变化。
实现可测试的份额金库
使用已安装 Foundry、能够执行 forge --version 的环境。下面采用 Solidity ^0.8.20 和 forge-std,不依赖 OpenZeppelin。示例将所有已发行份额限制在两个测试账户之间,方便逐项检查。
在 Foundry 项目中创建 src/ShareVault.sol:
// 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:
// 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 中添加或合并以下配置:
[invariant]
runs = 256
depth = 50
fail_on_revert = true
show_metrics = true这相当于为每个 Invariant 测试配置 256 条随机序列,每条最多安排 50 次调用。fail_on_revert = true 适用于本例:Handler 已处理正常前置条件,未授权操作的预期回滚也已通过低级调用捕获。
在项目根目录执行:
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 失败时会给出调用序列或重放相关信息,具体输出格式随版本变化。排查应从第一个违反断言的操作开始,而不是只盯着最后的余额。
- 查看失败属于
assetsConserved、sharesConserved还是授权断言。 - 使用
forge test --match-contract ShareVaultInvariantTest -vvvv查看更详细的执行轨迹。 - 记录关键调用的账户、金额与顺序,在独立单元测试中固定重现。
- 修复后重新运行完整随机测试,并保留该固定回归用例。
对于真实 ERC-4626 金库,还应增加 mint、redeem、transfer 和收益变化操作。份额与资产不再总是 1:1,因此不能直接要求金库资产余额等于份额供应量;必须根据协议定义的舍入方式、捐赠处理和债务口径建立新的守恒关系。
建议开发阶段采用 runs = 256、depth = 50,在 CI 中根据运行时间逐步增加到 runs = 1000、depth = 100。同时保留确定性的漏洞回归测试,检查实际执行覆盖率,并确保每条安全性质都有可以触发失败的反例。