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

断言事件日志与余额变化

断言事件日志与余额变化

智能合约即使正确发出了事件,也不代表资金真的完成转移。本课使用 Foundry 的 vm.expectEmit、assertEq 和地址余额检查,为存款与提款建立测试,确保事件参数、事件发送合约、内部账本和实际 ETH 余额相互一致。

学习目标

  • 使用 vm.expectEmit 检查事件的索引参数、数据和发送合约地址。
  • 同时断言用户余额、合约余额与内部账本,验证真实资金变化。
  • 识别事件正确但状态错误、事件发送方错误等测试遗漏。

区分事件日志和真实状态

Solidity 的 emit 会生成交易日志,供区块浏览器、索引服务和前端订阅使用。事件本身不会自动改变合约存储,也不会转移 ETH。

例如用户向资金池存入 2 ETH,应该同时满足以下条件:

检查对象 操作前 操作后
用户 ETH 余额 10 ETH 8 ETH
资金池 ETH 余额 0 ETH 2 ETH
用户内部存款记录 0 ETH 2 ETH
Deposited 事件 不存在 用户地址、2 ETH

这里的余额是假设没有其他资金流动、用户通过外部测试环境调用且不计算交易手续费的结果。Foundry 本地单元测试可以使用 vm.deal 设置初始余额。

只检查 Deposited(user, 2 ether) 存在是不够的。错误的合约可能发出了该事件,却没有更新内部账本;或者事件中的金额与真正记账的金额不一致。

因此,测试需要分别覆盖两类证据:事件是否准确描述操作,以及链上状态是否真正发生了预期变化。

使用 expectEmit 检查事件参数

vm.expectEmit 是 Foundry 提供的测试作弊码,用于在执行目标操作之前注册预期事件。

对于下面的事件:

solidity
event Deposited(address indexed user, uint256 amount);

user 是第一个索引参数,存放在 Topic 1;Topic 0 是事件签名哈希。amount 没有 indexed 修饰,编码在事件的数据区域中。

对应的检查方式为:

solidity
vm.expectEmit(true, false, false, true, address(vault));
emit Deposited(alice, 2 ether);
vm.prank(alice);
vault.deposit{value: 2 ether}();

以上是片段示例,依赖已经部署的 vault、已定义的 alice 和 Deposited 事件;下方提供完整可运行版本。

四个布尔参数依次控制 Topic 1、Topic 2、Topic 3 和非索引数据是否参与比较。最后的 address(vault) 指定事件必须由目标资金池合约发出。

本例只存在一个索引参数,因此只需要启用第一个 Topic 检查。amount 位于数据区域,所以第四个参数必须为 true。

编写存款和提款完整测试

下面使用一个最小 ETH 资金池演示。合约支持存款与提款,并在状态更新后发出事件。测试采用 Foundry 的 forge-std/Test.sol,适用于支持 vm.expectEmit(bool,bool,bool,bool,address) 的 Foundry 版本。

先在已安装 Foundry 的终端执行:

bash
forge init vault-events-demo
cd vault-events-demo

预期结果:生成包含 foundry.toml、src、test 和 lib/forge-std 的 Foundry 项目。已有 Foundry 项目可以跳过初始化。

将下面代码保存为 test/VaultEvents.t.sol。这个文件同时包含演示合约与测试合约,因此无需另外创建业务合约文件。

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

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

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

    event Deposited(address indexed user, uint256 amount);
    event Withdrawn(address indexed user, uint256 amount);

    function deposit() external payable {
        require(msg.value > 0, "Zero deposit");
        balances[msg.sender] += msg.value;
        emit Deposited(msg.sender, msg.value);
    }

    function withdraw(uint256 amount) external {
        require(amount > 0, "Zero withdrawal");
        require(balances[msg.sender] >= amount, "Insufficient balance");

        // 外部转账前先扣减账本,遵循检查-生效-交互顺序。
        balances[msg.sender] -= amount;
        (bool ok, ) = payable(msg.sender).call{value: amount}("");
        require(ok, "ETH transfer failed");
        emit Withdrawn(msg.sender, amount);
    }
}

contract VaultEventsTest is Test {
    Vault vault;
    address alice = address(0xA11CE);

    event Deposited(address indexed user, uint256 amount);
    event Withdrawn(address indexed user, uint256 amount);

    function setUp() public {
        vault = new Vault();
        vm.deal(alice, 10 ether);
    }

    function testDepositEventAndBalances() public {
        uint256 amount = 2 ether;
        uint256 userBefore = alice.balance;
        uint256 vaultBefore = address(vault).balance;

        // 同时匹配事件参数与事件发送合约。
        vm.expectEmit(true, false, false, true, address(vault));
        emit Deposited(alice, amount);

        vm.prank(alice);
        vault.deposit{value: amount}();

        // 校验事件之外的真实 ETH 余额和内部账本。
        assertEq(alice.balance, userBefore - amount);
        assertEq(address(vault).balance, vaultBefore + amount);
        assertEq(vault.balances(alice), amount);
    }

    function testWithdrawEventAndBalances() public {
        uint256 depositAmount = 2 ether;
        uint256 withdrawAmount = 0.5 ether;

        vm.prank(alice);
        vault.deposit{value: depositAmount}();

        uint256 userBefore = alice.balance;
        uint256 vaultBefore = address(vault).balance;
        uint256 recordedBefore = vault.balances(alice);

        // 提款事件必须与实际调用者和提款金额一致。
        vm.expectEmit(true, false, false, true, address(vault));
        emit Withdrawn(alice, withdrawAmount);

        vm.prank(alice);
        vault.withdraw(withdrawAmount);

        assertEq(alice.balance, userBefore + withdrawAmount);
        assertEq(address(vault).balance, vaultBefore - withdrawAmount);
        assertEq(vault.balances(alice), recordedBefore - withdrawAmount);
    }
}

完整测试覆盖两个独立场景。setUp 在每次测试前重新部署资金池并为 Alice 分配 10 ETH,避免不同测试之间共享业务状态。

存款测试要求事件金额、内部记账增量和资金池 ETH 增量全部等于 2 ETH。提款测试先准备 2 ETH 的存款,再提取 0.5 ETH,并分别验证用户收到的金额、资金池减少的金额及账本扣减值。

vm.prank(alice) 让下一次目标调用以 Alice 的身份执行,因此事件中的 msg.sender 应为 Alice。事件声明必须与被测合约中的事件签名及索引位置一致。

执行测试并检查预期结果

在项目根目录运行:

bash
forge test --match-contract VaultEventsTest -vv

预期输出(省略编译耗时、Gas 数值等环境相关信息):

text
[PASS] testDepositEventAndBalances()
[PASS] testWithdrawEventAndBalances()
Suite result: ok. 2 passed; 0 failed; 0 skipped

测试完整通过后,还可以逐项核对最终余额:

测试场景 用户 ETH 资金池 ETH Alice 账本余额
存款 2 ETH 后 8 ETH 2 ETH 2 ETH
存入 2 ETH 再提取 0.5 ETH 后 8.5 ETH 1.5 ETH 1.5 ETH

每个测试都拥有独立初始化的状态。测试运行结果中的执行耗时和 Gas 消耗可能随 Foundry 版本不同而变化,不应将这些动态值作为固定断言依据。

验证测试确实能够发现错误

一套有价值的测试不仅要能够通过,还要确认合约出现错误时能够失败。这可以通过临时引入缺陷进行验证,验证完成后必须恢复正确实现。

可以尝试以下三种修改,每次只修改一处并重新运行测试:

  1. 事件金额错误:将存款事件中的 msg.value 临时改为 msg.value + 1。预期事件数据不匹配,存款测试失败。
  2. 内部账本错误:将存款函数中的 balances[msg.sender] += msg.value 临时删除。存款事件和 ETH 转入仍可能正常,但账本余额断言失败。
  3. 提款记账错误:将提款函数中的 balances[msg.sender] -= amount 临时删除。提款事件和 ETH 转账仍可能成功,但提款后的账本余额断言失败。

第一种修改验证事件断言的有效性,后两种验证状态断言的有效性。如果只写事件断言,后两种缺陷就可能被漏掉。

还有三个容易遗漏的边界:

  • 一次业务操作发出多个事件时,应明确预期事件的参数及相对顺序,避免只验证其中一个成功日志。
  • 提款失败或业务回滚时,事件和状态修改都会随交易回滚;应使用 vm.expectRevert 检查失败路径,而不是期待保留失败交易中的事件。
  • 如果资金池原本存在余额,应使用操作前后的余额差值进行断言,不要固定假设初始余额永远为零。

对于转账、存款、提款等资金相关操作,至少要同时验证事件参数、事件发送合约、用户资产变化和业务内部记账。事件负责证明合约对外报告了什么,状态断言负责证明资金和账本实际上发生了什么。

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

目录与阅读设置

阅读设置

17

记录一个想法

断言事件日志与余额变化

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

登录哪都通