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

创建 invariant 函数和测试目标

创建 invariant 函数和测试目标

普通模糊测试主要检验单次函数调用,而资金池、账本等合约的缺陷可能需要多次存取操作才能触发。本课使用 Foundry 创建可运行的状态不变量测试,配置目标合约、调用次数与随机序列深度,并通过运行结果确认属性确实受到检查。

学习目标

  • 使用 invariant_ 命名规则声明状态不变量,并通过 targetContract 指定测试对象。
  • 理解 runs、depth 和每次调用后的属性检查机制。
  • 运行完整测试,识别通过、断言失败和调用回滚之间的区别。

确定要持续成立的属性

假设一个简化资金账本只提供存入和取出操作,并记录累计存入量、累计取出量以及当前余额。

无论用户按什么顺序操作,都应该满足:

累计存入量=累计取出量+当前余额\text{累计存入量}=\text{累计取出量}+\text{当前余额}

例如,依次存入 100、取出 30、再存入 20,最后累计存入为 120、累计取出为 30、余额为 90,等式仍然成立。

这就是状态不变量:它并不要求余额保持不变,而是要求不同状态变量之间的关系始终成立。

普通单元测试可以手工检查这三次操作;不变量测试则由 Foundry 随机生成大量操作序列,在每次调用后检查关系是否被破坏。

创建合约与 invariant 测试

前置条件是已经安装 Foundry,并拥有包含 forge-std 依赖的标准 Forge 项目。可以通过 forge --version 检查安装状态。

在项目的 test/CounterInvariant.t.sol 中放入以下完整示例。为了方便直接运行,这里把待测合约和测试合约写在同一文件,实际项目可以把业务合约放在 src/ 下。

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

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

contract Ledger {
    uint256 public totalIn;
    uint256 public totalOut;
    uint256 public balance;

    function deposit(uint256 amount) external {
        // 限定单次金额,避免极大随机值干扰状态探索。
        amount = amount % 1001;
        totalIn += amount;
        balance += amount;
    }

    function withdraw(uint256 amount) external {
        if (balance == 0) return;
        // 保证取出金额不超过现有余额。
        amount = amount % (balance + 1);
        totalOut += amount;
        balance -= amount;
    }
}

contract CounterInvariantTest is Test {
    Ledger internal ledger;

    function setUp() public {
        ledger = new Ledger();
        // 只对账本合约的外部函数生成随机调用。
        targetContract(address(ledger));
    }

    function invariant_accounting() public view {
        assertEq(
            ledger.totalIn(),
            ledger.totalOut() + ledger.balance()
        );
    }
}

这里有三个关键位置。

  1. setUp() 在测试序列开始前部署待测账本并注册目标地址。
  2. targetContract(address(ledger)) 将随机调用限制在该合约,避免误将测试辅助合约加入测试范围。
  3. invariant_accounting() 通过 assertEq 声明必须持续成立的账务关系。

Foundry 使用以 invariant_ 开头的函数名识别不变量测试。测试函数不需要随机参数,因为随机参数由引擎传递给目标合约的函数,而不是直接传递给不变量函数。

targetContract 是继承 forge-std/Test.sol 后可用的测试辅助方法,不能直接写进普通生产合约。

配置 runs 和 depth

在项目根目录的 foundry.toml 中添加以下配置;如果已有 [invariant] 段,应合并字段,而不是重复声明同名表。

toml
[invariant]
runs = 20
depth = 32
fail_on_revert = true

各参数的含义如下。

参数 示例值 实际作用
runs 20 生成并执行 20 轮随机调用序列
depth 32 每轮最多执行 32 次目标函数调用
fail_on_revert true 目标调用发生未被容许的回滚时使测试失败

这组设置的计划调用量是 20 × 32 = 640 次,并不代表 640 种唯一状态,也不代表所有可能调用顺序都已覆盖。

runs 增加随机序列数量,适合扩大不同输入和初始操作组合的探索;depth 增加单条序列的长度,更适合寻找需要多次连续操作才能触发的状态缺陷。

例如,一个缺陷只有连续取款五次后才出现,那么将 depth 设置为 3 就无法覆盖该触发链,即使增加 runs 也不能弥补序列长度不足。

理解每次调用后的检查过程

Foundry 的不变量测试并不是完成整条随机序列后才做一次断言,而是在序列执行过程中持续检查属性。

随机调用序列及每次调用后的不变量检查

上图用三次调用说明一轮测试的基本行为。实际配置为 depth = 32 时,Foundry 会继续产生更多调用,并反复执行不变量检查。

需要特别注意以下边界:

  • 每轮随机序列在隔离的测试状态中执行,不会把上一轮结束的余额当成下一轮初始余额。
  • 如果没有开启 fail_on_revert,目标调用回滚通常不会直接导致整轮不变量测试失败,但仍会消耗一次调用深度。
  • 即使断言一直通过,如果所有目标函数都回滚,测试也可能没有覆盖真正的业务状态变化。
  • 多个独立的 invariant_ 测试通常使用各自的执行状态;要求同时检查的一组属性可以写进同一个不变量函数。

本例显式使用 fail_on_revert = true,并通过金额约束保证正常随机调用不会因为余额不足而回滚,便于观察真正的状态缺陷。

运行并检查结果

在 Forge 项目根目录执行:

bash
forge test --match-contract CounterInvariantTest -vv

预期结果是测试通过,控制台会出现类似以下摘要;耗时和完整日志会随环境变化。

text
[PASS] invariant_accounting() (runs: 20, calls: 640, reverts: 0)

这里的 calls: 640 对应 20 轮、每轮 32 次调用;reverts: 0 表示此次示例运行没有目标调用回滚。最终成功还应以 Forge 给出的测试通过状态为准。

为了确认断言不是摆设,可以做一次故障注入:暂时将 withdraw() 中的 totalOut += amount; 删除,其余逻辑保持不变。只要产生非零取款,累计存入量就不再等于累计取出量加余额。

重新执行同一条测试命令。

预期结果:invariant_accounting() 报告失败,Forge 输出触发问题的调用信息或反例序列。具体金额和调用顺序由随机探索决定,不应预设为固定值。随后恢复被删除的代码,再次运行并确认测试通过。

如果测试意外显示通过,先检查三件事:函数名是否以 invariant_ 开头,targetContract 是否指向真正的业务合约,以及运行摘要中的 calls、reverts 是否表明有效状态操作已经发生。

对于需要授权、代币余额或复杂操作前置条件的真实协议,通常还要增加 Handler 合约来生成有效调用。单纯调大 runs 和 depth,无法修复大量随机调用因前置条件不满足而回滚的问题。

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

目录与阅读设置

阅读设置

17

记录一个想法

创建 invariant 函数和测试目标

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

登录哪都通