智能合约与以太坊 / 系统课时
编写 Handler 驱动合法交易
编写 Handler 驱动合法交易
直接让 Foundry 随机调用存款、取款和转账接口,常会因为余额不足、缺少授权或账户无效而反复回滚。本篇通过可运行的 Handler 示例,为每次调用准备合法前置条件,让模糊测试真正探索多账户、多交易组合后的合约状态。
学习目标
- 理解 Handler 如何控制随机调用的账户、金额与执行前置条件。
- 使用 Foundry 编写包含存款、取款和内部余额转账的状态测试。
- 通过调用计数和不变量检查,确认随机交易确实改变了合约状态。
为什么直接随机调用难以探索状态
假设一个资金池提供 deposit、withdraw 和 transferCredit 三个接口。存款需要 ERC-20 资产及授权;取款要求调用者拥有足够的池内余额;内部转账要求发送方有余额且接收方有效。
如果直接随机调用资金池,测试开始时账户可能没有资产,授权也是零。此时即使执行了几千次随机调用,大多数交易仍然只会回滚,无法覆盖资金在不同账户之间流转的状态。
Handler 是一个由测试框架随机调用的包装合约。它接收随机输入,选择有效账户,准备测试资产与授权,并把输入金额映射到当前可执行的范围,再调用被测合约。发生真正的状态变更后,还可以记录执行次数和辅助状态。

以三个测试账户为例:Alice 存入 100,向 Bob 转账 40,Bob 取出 15,最后池内 Alice 为 60、Bob 为 25,资金池持有 85 个代币。整个过程中,资金池持有的资产应始终等于账户池内余额之和。
准备最小可测试资金池
以下示例适用于使用 Solidity 0.8.20 或兼容版本、已安装 forge-std 的 Foundry 项目。先在项目根目录执行 forge init handler-demo 并进入目录;如果当前已经是 Foundry 项目,则直接使用现有项目。示例不需要 OpenZeppelin,使用一个只供测试的简化 ERC-20 代币。
创建 src/HandlerDemo.sol,实现测试代币以及使用内部记账的资金池。资金池的 transferCredit 仅移动池内余额,不转出底层代币。
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;
contract MockToken {
mapping(address => uint256) public balanceOf;
mapping(address => mapping(address => uint256)) public allowance;
// 测试专用铸造接口,不用于真实资产发行。
function mint(address to, uint256 amount) external {
balanceOf[to] += amount;
}
function approve(address spender, uint256 amount) external returns (bool) {
allowance[msg.sender][spender] = amount;
return true;
}
function transfer(address to, uint256 amount) external returns (bool) {
require(balanceOf[msg.sender] >= amount, "balance");
balanceOf[msg.sender] -= amount;
balanceOf[to] += amount;
return true;
}
function transferFrom(address from, address to, uint256 amount) external returns (bool) {
require(allowance[from][msg.sender] >= amount, "allowance");
require(balanceOf[from] >= amount, "balance");
allowance[from][msg.sender] -= amount;
balanceOf[from] -= amount;
balanceOf[to] += amount;
return true;
}
}
contract DemoVault {
MockToken public immutable asset;
mapping(address => uint256) public credit;
uint256 public totalCredits;
constructor(MockToken token) {
asset = token;
}
function deposit(uint256 amount) external {
require(amount > 0, "zero");
require(asset.transferFrom(msg.sender, address(this), amount), "transfer");
credit[msg.sender] += amount;
totalCredits += amount;
}
function withdraw(uint256 amount) external {
require(amount > 0 && credit[msg.sender] >= amount, "credit");
credit[msg.sender] -= amount;
totalCredits -= amount;
require(asset.transfer(msg.sender, amount), "transfer");
}
// 只转移池内债权,不改变资金池持有的代币数量。
function transferCredit(address to, uint256 amount) external {
require(to != address(0), "recipient");
require(amount > 0 && credit[msg.sender] >= amount, "credit");
credit[msg.sender] -= amount;
credit[to] += amount;
}
}这里使用的代币没有实现完整 ERC-20 标准,包括事件和部分接口行为,因此只能作为本例的测试替身。资金池假设资产不收手续费、不会发生自动增减余额,也不会收到外部直接转入的捐赠。只有在这些条件下,资产守恒等式才成立。
编写带账户与金额约束的 Handler
创建 test/Handler.t.sol。Handler 继承 Test,使用 bound 将随机金额映射到有效区间,使用 vm.prank 指定真正操作资金池的账户。三个账户由固定地址生成,避免随机地址无法追踪。
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;
import {Test} from "forge-std/Test.sol";
import {StdInvariant} from "forge-std/StdInvariant.sol";
import {MockToken, DemoVault} from "../src/HandlerDemo.sol";
contract VaultHandler is Test {
MockToken public token;
DemoVault public vault;
address[3] public actors;
uint256 public deposits;
uint256 public withdrawals;
uint256 public transfers;
constructor(MockToken t, DemoVault v) {
token = t;
vault = v;
actors[0] = address(0xA11CE);
actors[1] = address(0xB0B);
actors[2] = address(0xCA101);
}
function deposit(uint256 actorSeed, uint256 amountSeed) external {
address actor = actors[actorSeed % actors.length];
uint256 amount = bound(amountSeed, 1, 100 ether);
// 存款前为选中的账户准备资产和足额授权。
token.mint(actor, amount);
vm.prank(actor);
token.approve(address(vault), amount);
vm.prank(actor);
vault.deposit(amount);
deposits++;
}
function withdraw(uint256 actorSeed, uint256 amountSeed) external {
address actor = actors[actorSeed % actors.length];
uint256 available = vault.credit(actor);
if (available == 0) return;
// 只有账户实际拥有余额时才生成合法取款。
uint256 amount = bound(amountSeed, 1, available);
vm.prank(actor);
vault.withdraw(amount);
withdrawals++;
}
function transferCredit(
uint256 actorSeed,
uint256 receiverSeed,
uint256 amountSeed
) external {
uint256 fromIndex = actorSeed % actors.length;
address from = actors[fromIndex];
uint256 available = vault.credit(from);
if (available == 0) return;
// 偏移量保证接收方与发送方不是同一账户。
uint256 offset = 1 + receiverSeed % (actors.length - 1);
address to = actors[(fromIndex + offset) % actors.length];
uint256 amount = bound(amountSeed, 1, available);
vm.prank(from);
vault.transferCredit(to, amount);
transfers++;
}
}
contract HandlerInvariantTest is StdInvariant, Test {
MockToken internal token;
DemoVault internal vault;
VaultHandler internal handler;
function setUp() public {
token = new MockToken();
vault = new DemoVault(token);
handler = new VaultHandler(token, vault);
// 只让随机调用进入 Handler 的三种业务操作。
bytes4[] memory selectors = new bytes4[](3);
selectors[0] = VaultHandler.deposit.selector;
selectors[1] = VaultHandler.withdraw.selector;
selectors[2] = VaultHandler.transferCredit.selector;
targetSelector(FuzzSelector({addr: address(handler), selectors: selectors}));
}
function invariant_assetConservation() public view {
assertEq(token.balanceOf(address(vault)), vault.totalCredits());
uint256 sum;
for (uint256 i = 0; i < 3; i++) {
sum += vault.credit(handler.actors(i));
}
assertEq(sum, vault.totalCredits());
}
}targetSelector 将模糊测试入口限定为 Handler 的三个操作。每次调用随机选择操作类型和输入参数,由 Handler 负责执行前置条件检查。deposit 是状态探索的入口,withdraw 和 transferCredit 则消耗此前随机调用形成的余额。
这里没有使用 vm.assume(available > 0),因为它可能导致大量输入被丢弃。账户余额为零时直接返回,让调用序列继续执行;同时通过成功计数区分空操作与真实状态变更。
运行测试并核对调用效果
在项目根目录运行下面的命令。--match-contract 限定测试合约,-vv 输出测试结果。
forge test --match-contract HandlerInvariantTest -vv预期结果:测试成功时,控制台会显示 invariant_assetConservation() 的 [PASS],并报告随机调用序列数量、调用次数及回滚次数。具体数值依赖 Foundry 版本、随机种子和测试参数,不应硬编码为固定次数。
为了增加状态探索深度,可以在项目的 foundry.toml 中配置以下参数。它们作用于不变量测试,而非普通单次输入的模糊测试。
[invariant]
runs = 256
depth = 100
fail_on_revert = true
show_metrics = true预期结果:每条测试序列最多执行 100 次目标函数调用,执行 256 条序列;如果目标调用发生未被 Handler 处理的回滚,测试会失败。支持 show_metrics 的 Foundry 版本还会输出函数调用和回滚的统计信息。
检查时不要只看 [PASS],还应确认三个关键指标:
- 存款确实发生。否则所有余额保持为零,守恒检查即使通过也没有测试价值。
- 取款和转账出现有效执行。可以通过 Handler 的
withdrawals、transfers计数,或增加专门的测试断言进行验证。 - 回滚次数合理。在当前简化资金池和合法输入策略下,正常预期应接近零;异常回滚需要结合
-vvvv跟踪具体调用序列。
可以在测试合约中追加下面的检查函数,用于确定 Handler 的三个入口确实能完成状态变更。此处是片段示例,依赖上面完整的 HandlerInvariantTest 和 VaultHandler 定义,放入 HandlerInvariantTest 合约内部。
function test_handlerActions() public {
handler.deposit(0, 100 ether);
handler.transferCredit(0, 0, 40 ether);
handler.withdraw(1, 15 ether);
assertEq(handler.deposits(), 1);
assertEq(handler.transfers(), 1);
assertEq(handler.withdrawals(), 1);
assertEq(vault.credit(handler.actors(0)), 60 ether);
assertEq(vault.credit(handler.actors(1)), 25 ether);
assertEq(token.balanceOf(address(vault)), 85 ether);
}预期结果:重新运行前面的 forge test 命令,test_handlerActions() 与 invariant_assetConservation() 均通过。这验证的是一条确定的存款、转账、取款路径;随机序列的实际覆盖程度仍要结合统计指标判断。
什么时候应该保留失败交易
Handler 不是让所有交易无条件成功的工具。合法交易测试与异常输入测试应当分开设计,否则会遗漏权限绕过、资金不足或错误接收方等真实风险。
| 测试场景 | Handler 合法路径 | 负向测试路径 |
|---|---|---|
| 账户没有存款资产 | 先铸造测试资产并授权 | 验证存款失败或回滚 |
| 取款金额超过余额 | 将金额约束在现有余额内 | 验证超额取款被拒绝 |
| 转账接收方无效 | 选择固定有效账户 | 验证零地址等非法目标 |
| 授权额度不足 | 设置足额授权 | 验证未授权转移失败 |
需要特别注意:bound 能保证输入在合法区间,但它并不等同于真实用户的金额分布。若始终使用很小的上限,测试可能覆盖不到极大数值下的算术边界;若始终强制不同接收方,也无法测试自转账行为。
实际项目可以维护两组 Handler:一组专注合法状态迁移,另一组专注异常条件与预期回滚。对于完整 ERC-20 或 ERC-4626 协议,还需要考虑代币手续费、捐赠、舍入误差和多参与者授权等情况,不能直接照搬本例的资产守恒断言。
本例的验收标准是:三种操作都能产生真实状态变化,合法交易序列不会因缺少资产或授权而无意义回滚,且随机调用后资金池资产总量与内部账户记账保持一致。