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

用 ghost 变量追踪资产账本

用 ghost 变量追踪资产账本

当模糊测试连续执行存款和提款时,仅检查合约余额是否非负,无法发现资产被错误增加、少记或重复扣除的问题。本课使用 Foundry Handler 维护独立的 ghost 资产账本,记录每次成功操作的预期变化,并在调用序列执行过程中持续对照真实合约状态。

学习目标

  • 理解 ghost 变量与被测合约状态的区别,建立独立资产账本。
  • 使用 Handler 记录累计存款、提款和预期余额。
  • 编写 Foundry 不变量测试,识别多次调用后的账本偏差。

为什么需要独立账本

假设一个 ETH 存款合约提供 deposit() 和 withdraw(uint256),同时维护用户余额和总资产。如果实现存在重复记账问题,单独检查 totalAssets() >= 0 没有意义,因为 uint256 本身不能表示负数。

更有效的方法是在测试环境中建立参考账本。ghost 变量是测试辅助合约维护的状态,不属于被测业务合约,也不会直接影响其记账逻辑。

本例维护三个值:

Ghost 变量 含义 更新规则
ghostDeposited 累计成功存入的 ETH 每次成功存款后增加
ghostWithdrawn 累计成功提取的 ETH 每次成功提款后增加
ghostAssets() 理论剩余资产 累计存款减累计提款

例如,依次执行存入 5 ETH、提取 2 ETH、存入 4 ETH、提取 1 ETH,参考账本应得到累计存款 9 ETH、累计提款 3 ETH、剩余资产 6 ETH。

关键约束是:ghost 账本根据成功执行的操作参数更新,而不是读取被测合约的余额后复制。 如果直接执行 ghostBalance = vault.totalAssets(),真实实现发生错误时,参考账本也会同步错误,测试便失去独立判断能力。

Handler 如何维护账本

Foundry 的状态不变量测试会生成多次函数调用。Handler 负责规范化随机输入、执行操作,并维护测试侧记录。测试框架只需要调用 Handler,便能产生有效的存提款序列。

Handler、独立 ghost 账本与真实金库状态的关系

Handler 需要遵守三个规则:

  1. 存款金额限制在合理范围,例如 1 wei 到 1 ETH,避免无效输入占据测试预算。
  2. 提款金额不得超过 ghost 账本中的可用余额;如果余额为零,直接跳过此次提款。
  3. 先调用被测合约,确认成功后再更新 ghost 变量;交易失败时不能记为成功存款或提款。

这里使用一个 Handler 地址作为唯一存款人,暂不引入手续费、利息或其他资产来源。这样账本守恒关系可以精确表达为:

Aexpected=Dsuccess−WsuccessA_{expected}=D_{success}-W_{success}

其中 DsuccessD_{success} 是成功存款累计值,WsuccessW_{success} 是成功提款累计值。多个用户参与时,可以进一步维护 mapping(address => uint256) 形式的参考余额,但不能用真实合约的用户余额直接初始化每次操作后的预期结果。

实现可运行的 ghost 账本测试

下面是适用于使用 forge-std 的 Foundry 项目的完整示例。前提是已经创建 Foundry 项目,并安装标准测试库。在项目根目录创建 test/VaultInvariant.t.sol,写入以下代码。

示例将最小金库、Handler 和不变量测试放在同一文件中,以便直接运行。

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

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

contract Vault {
    mapping(address => uint256) public balanceOf;
    uint256 public totalAssets;

    function deposit() external payable {
        require(msg.value > 0, "zero deposit");
        balanceOf[msg.sender] += msg.value;
        totalAssets += msg.value;
    }

    function withdraw(uint256 amount) external {
        require(amount > 0, "zero withdrawal");
        require(balanceOf[msg.sender] >= amount, "insufficient");

        // 先更新账本,再执行外部 ETH 转账。
        balanceOf[msg.sender] -= amount;
        totalAssets -= amount;

        (bool success, ) = payable(msg.sender).call{value: amount}("");
        require(success, "transfer failed");
    }
}

contract VaultHandler is Test {
    Vault public immutable vault;
    uint256 public ghostDeposited;
    uint256 public ghostWithdrawn;

    constructor(Vault _vault) {
        vault = _vault;
    }

    receive() external payable {}

    function deposit(uint256 rawAmount) external {
        uint256 amount = bound(rawAmount, 1, 1 ether);

        // 给测试调用方准备资金,不改变 Vault 的账本。
        vm.deal(address(this), amount);
        vault.deposit{value: amount}();

        // 只有成功调用后,才记录参考账本。
        ghostDeposited += amount;
    }

    function withdraw(uint256 rawAmount) external {
        uint256 available = ghostAssets();
        if (available == 0) return;

        uint256 amount = bound(rawAmount, 1, available);
        vault.withdraw(amount);
        ghostWithdrawn += amount;
    }

    function ghostAssets() public view returns (uint256) {
        return ghostDeposited - ghostWithdrawn;
    }
}

contract VaultInvariantTest is StdInvariant, Test {
    Vault internal vault;
    VaultHandler internal handler;

    function setUp() public {
        vault = new Vault();
        handler = new VaultHandler(vault);

        // 只让模糊测试调用这两个 Handler 入口。
        bytes4[] memory selectors = new bytes4[](2);
        selectors[0] = VaultHandler.deposit.selector;
        selectors[1] = VaultHandler.withdraw.selector;
        targetSelector(FuzzSelector({
            addr: address(handler),
            selectors: selectors
        }));
    }

    function invariant_assetsMatchGhost() public view {
        uint256 expected = handler.ghostAssets();

        // 参考账本同时约束三种真实状态。
        assertEq(vault.totalAssets(), expected);
        assertEq(vault.balanceOf(address(handler)), expected);
        assertEq(address(vault).balance, expected);
    }
}

这里 ghostDeposited 和 ghostWithdrawn 只依赖 Handler 的实际成功操作金额,不依赖 vault.totalAssets() 的返回值。targetSelector 将随机调用限定为存款和提款,避免测试框架调用无关辅助函数。

vm.deal 是 Foundry 的测试作弊码,只用于测试环境准备 ETH,不会出现在生产部署的金库代码中。Handler 的 receive() 则允许金库提款时正常向其转回 ETH。

通过 bound 限制参数后,测试仍可产生不同金额和顺序的交易,例如连续存款、存款后全额提款、部分提款后再次存款等。

运行测试并检查比较结果

在项目根目录执行以下命令:

bash
forge test --match-contract VaultInvariantTest -vv

预期结果:正确实现下,invariant_assetsMatchGhost() 显示 [PASS],Foundry 输出调用序列的运行统计和回退次数。具体运行次数、调用次数与耗时由测试配置决定。

可以进一步在项目根目录的 foundry.toml 中设置不变量测试参数:

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

这是配置示例,保存后重新执行 forge test --match-contract VaultInvariantTest -vv 即可生效。runs = 256 表示执行 256 条调用序列,depth = 50 表示每条序列最多包含 50 次调用。fail_on_revert = true 会把未处理的目标调用回退视为失败,便于排查无效操作。

本例通过限制提款金额和准备存款资金,正常情况下不会因为余额不足而回退。但如果被测金库存在资产错误、转账失败等问题,可能出现不变量断言失败或调用回退,需要结合失败轨迹判断原因。

为了验证 ghost 账本确实能捕获缺陷,可以进行一次故障注入。在 Vault.deposit() 中把 totalAssets += msg.value; 临时改为 totalAssets += msg.value * 2;,随后重新运行测试。

预期结果:包含成功存款的调用序列会使 totalAssets() 高于 ghostAssets(),invariant_assetsMatchGhost() 应报告 [FAIL],而不是继续通过。Foundry 通常会尝试缩减失败序列,输出能够重现问题的调用信息。

恢复原来的记账代码后重新执行,测试应再次通过。这一步可以验证断言确实能够发现故意引入的账本错误。

避免参考账本产生假阳性或漏报

独立账本也需要明确测试边界,否则比较结果可能失真。

错误做法 产生的问题 正确处理
从 totalAssets() 复制 ghost 值 真实错误被同步复制,导致漏报 按成功操作金额独立累计
在外部调用前更新 ghost 捕获并忽略失败调用时可能错误记账 成功后更新;失败分支单独处理
直接用随机金额提款 大量余额不足的回退浪费测试预算 使用 ghost 可用余额约束参数
将所有资产变化都当作存款 忽略费用、奖励及其他资金来源 为每类业务变化建立独立参考字段
无条件要求合约 ETH 余额等于用户存款 强制转入 ETH 可能造成误报 区分内部负债与实际持币余额

特别注意,本例的三个相等性断言建立在严格的简化假设上:只有 Handler 一个存款人,没有手续费、奖励、外部转账,也没有通过 selfdestruct 等机制强制转入的额外 ETH。

真实协议中,内部总资产、用户负债和链上代币余额可能并不相等。例如 Vault 存在收益或捐赠时,链上资产余额可能大于用户存款账本。此时应分别建立用户负债、收益、费用和外部资产流入的参考模型,而不是直接沿用三个相等断言。

还有一个容易忽略的边界:当前提款上限使用 ghostAssets(),而不是 vault.balanceOf()。这样做能减少对被测实现的依赖。如果真实金库少记了用户存款,Handler 可能尝试提取参考账本认为合法、但真实合约拒绝的金额;开启 fail_on_revert 后,这类差异也能暴露问题。

对于业务允许的失败操作,需要明确区分预期回退和缺陷回退。可以在 Handler 中针对特定场景使用 try/catch 或 vm.expectRevert,但不要简单吞掉所有异常,否则资产缺陷可能被隐藏。

最终的验收标准是:正常金库在连续存提款下始终满足参考账本守恒;故意破坏存款或提款记账后,测试能够失败并给出可复现序列。满足这两点,ghost 变量才真正成为独立的资产正确性检查依据。

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

目录与阅读设置

阅读设置

17

记录一个想法

用 ghost 变量追踪资产账本

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

登录哪都通