智能合约与以太坊 / 系统课时
用 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 需要遵守三个规则:
- 存款金额限制在合理范围,例如 1 wei 到 1 ETH,避免无效输入占据测试预算。
- 提款金额不得超过 ghost 账本中的可用余额;如果余额为零,直接跳过此次提款。
- 先调用被测合约,确认成功后再更新 ghost 变量;交易失败时不能记为成功存款或提款。
这里使用一个 Handler 地址作为唯一存款人,暂不引入手续费、利息或其他资产来源。这样账本守恒关系可以精确表达为:
其中 是成功存款累计值, 是成功提款累计值。多个用户参与时,可以进一步维护 mapping(address => uint256) 形式的参考余额,但不能用真实合约的用户余额直接初始化每次操作后的预期结果。
实现可运行的 ghost 账本测试
下面是适用于使用 forge-std 的 Foundry 项目的完整示例。前提是已经创建 Foundry 项目,并安装标准测试库。在项目根目录创建 test/VaultInvariant.t.sol,写入以下代码。
示例将最小金库、Handler 和不变量测试放在同一文件中,以便直接运行。
// 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 限制参数后,测试仍可产生不同金额和顺序的交易,例如连续存款、存款后全额提款、部分提款后再次存款等。
运行测试并检查比较结果
在项目根目录执行以下命令:
forge test --match-contract VaultInvariantTest -vv预期结果:正确实现下,invariant_assetsMatchGhost() 显示 [PASS],Foundry 输出调用序列的运行统计和回退次数。具体运行次数、调用次数与耗时由测试配置决定。
可以进一步在项目根目录的 foundry.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 变量才真正成为独立的资产正确性检查依据。