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

编写 Handler 驱动合法交易

编写 Handler 驱动合法交易

直接让 Foundry 随机调用存款、取款和转账接口,常会因为余额不足、缺少授权或账户无效而反复回滚。本篇通过可运行的 Handler 示例,为每次调用准备合法前置条件,让模糊测试真正探索多账户、多交易组合后的合约状态。

学习目标

  • 理解 Handler 如何控制随机调用的账户、金额与执行前置条件。
  • 使用 Foundry 编写包含存款、取款和内部余额转账的状态测试。
  • 通过调用计数和不变量检查,确认随机交易确实改变了合约状态。

为什么直接随机调用难以探索状态

假设一个资金池提供 deposit、withdraw 和 transferCredit 三个接口。存款需要 ERC-20 资产及授权;取款要求调用者拥有足够的池内余额;内部转账要求发送方有余额且接收方有效。

如果直接随机调用资金池,测试开始时账户可能没有资产,授权也是零。此时即使执行了几千次随机调用,大多数交易仍然只会回滚,无法覆盖资金在不同账户之间流转的状态。

Handler 是一个由测试框架随机调用的包装合约。它接收随机输入,选择有效账户,准备测试资产与授权,并把输入金额映射到当前可执行的范围,再调用被测合约。发生真正的状态变更后,还可以记录执行次数和辅助状态。

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 仅移动池内余额,不转出底层代币。

solidity
// 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 指定真正操作资金池的账户。三个账户由固定地址生成,避免随机地址无法追踪。

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 {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 输出测试结果。

bash
forge test --match-contract HandlerInvariantTest -vv

预期结果:测试成功时,控制台会显示 invariant_assetConservation() 的 [PASS],并报告随机调用序列数量、调用次数及回滚次数。具体数值依赖 Foundry 版本、随机种子和测试参数,不应硬编码为固定次数。

为了增加状态探索深度,可以在项目的 foundry.toml 中配置以下参数。它们作用于不变量测试,而非普通单次输入的模糊测试。

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 合约内部。

solidity
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 协议,还需要考虑代币手续费、捐赠、舍入误差和多参与者授权等情况,不能直接照搬本例的资产守恒断言。

本例的验收标准是:三种操作都能产生真实状态变化,合法交易序列不会因缺少资产或授权而无意义回滚,且随机调用后资金池资产总量与内部账户记账保持一致。

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

目录与阅读设置

阅读设置

17

记录一个想法

编写 Handler 驱动合法交易

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

登录哪都通