智能合约与以太坊 / 系统课时
构造时间和区块高度边界
构造时间和区块高度边界
智能合约中的锁仓到期、拍卖截止和区块确认限制,都依赖链上时间或高度。本课使用 Foundry 的 `vm.warp` 和 `vm.roll` 精确控制测试环境,分别验证阈值前、恰好等于阈值以及超过阈值时的执行结果,避免遗漏最容易出错的边界条件。
学习目标
- 掌握 `vm.warp` 与 `vm.roll` 的作用、单位和适用场景。
- 为时间戳和区块高度分别构造阈值前、等于阈值、超过阈值的测试。
- 使用 `forge test` 验证边界行为,并识别比较运算符导致的缺陷。
区分时间戳与区块高度
Solidity 提供两个常见的链上环境变量:`block.timestamp` 表示区块时间戳,单位是秒;`block.number` 表示当前区块高度,是整数计数。Foundry 的作弊码可以在测试 EVM 中修改它们。
| 作弊码 | 修改的变量 | 参数含义 | 典型用途 |
|---|---|---|---|
| `vm.warp(1700003600)` | `block.timestamp` | Unix 时间戳,秒 | 锁仓、截止时间、冷却期 |
| `vm.roll(105)` | `block.number` | 目标区块高度 | 区块锁定、确认高度、投票生效高度 |
两者是独立操作:`warp` 不会自动推进区块高度,`roll` 也不会按照平均出块时间增加时间戳。因此,涉及两个条件的业务必须分别设置两个变量。
例如,资金释放条件为时间戳不小于 1700003600,同时区块高度不小于 105。即使时间已经到期,只要高度还是 104,交易依然必须拒绝。
实现可以验证的双重锁定合约
以下使用 Solidity 0.8.24、Foundry 和 `forge-std/Test.sol`。合约只有一个业务入口 `release()`,要求时间戳与区块高度同时达到阈值。成功后记录释放状态,重复调用必须失败。
在已有 Foundry 项目的 `src/BoundaryLock.sol` 中写入:
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;
contract BoundaryLock {
uint256 public immutable unlockTime;
uint256 public immutable unlockBlock;
bool public released;
error TooEarly();
error AlreadyReleased();
constructor(uint256 time_, uint256 block_) {
unlockTime = time_;
unlockBlock = block_;
}
function release() external {
if (block.timestamp < unlockTime || block.number < unlockBlock) {
revert TooEarly();
}
if (released) revert AlreadyReleased();
// 两种限制都满足后才改变业务状态。
released = true;
}
}这是完整的最小合约。`<` 表示当前值等于阈值时允许释放;如果误写成 `<=`,边界恰好相等时会被拒绝。使用自定义错误能够在测试中精确断言失败原因,而不只是检查交易是否回滚。
覆盖阈值前、等于阈值与超过阈值
为避免测试互相污染,每个测试用例使用 `setUp()` 创建全新合约。时间阈值固定为 1700003600,高度阈值固定为 105。首先将另一个维度设为已经满足,使当前测试只检验单个条件。
在 `test/BoundaryLock.t.sol` 中写入:
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;
import {Test} from "forge-std/Test.sol";
import {BoundaryLock} from "../src/BoundaryLock.sol";
contract BoundaryLockTest is Test {
uint256 constant UNLOCK_TIME = 1700003600;
uint256 constant UNLOCK_BLOCK = 105;
BoundaryLock lock;
function setUp() public {
lock = new BoundaryLock(UNLOCK_TIME, UNLOCK_BLOCK);
}
function testTimeBeforeThreshold() public {
vm.warp(UNLOCK_TIME - 1);
vm.roll(UNLOCK_BLOCK);
vm.expectRevert(BoundaryLock.TooEarly.selector);
lock.release();
assertFalse(lock.released());
}
function testTimeExactlyAtThreshold() public {
vm.warp(UNLOCK_TIME);
vm.roll(UNLOCK_BLOCK);
lock.release();
assertTrue(lock.released());
}
function testTimeAfterThreshold() public {
vm.warp(UNLOCK_TIME + 1);
vm.roll(UNLOCK_BLOCK);
lock.release();
assertTrue(lock.released());
}
function testBlockBeforeThreshold() public {
vm.warp(UNLOCK_TIME);
vm.roll(UNLOCK_BLOCK - 1);
vm.expectRevert(BoundaryLock.TooEarly.selector);
lock.release();
assertFalse(lock.released());
}
function testBlockExactlyAtThreshold() public {
vm.warp(UNLOCK_TIME);
vm.roll(UNLOCK_BLOCK);
lock.release();
assertTrue(lock.released());
}
function testBlockAfterThreshold() public {
vm.warp(UNLOCK_TIME);
vm.roll(UNLOCK_BLOCK + 1);
lock.release();
assertTrue(lock.released());
}
function testTimeReachedButBlockNotReached() public {
vm.warp(UNLOCK_TIME + 100);
vm.roll(UNLOCK_BLOCK - 1);
vm.expectRevert(BoundaryLock.TooEarly.selector);
lock.release();
}
function testCannotReleaseTwice() public {
vm.warp(UNLOCK_TIME);
vm.roll(UNLOCK_BLOCK);
lock.release();
vm.expectRevert(BoundaryLock.AlreadyReleased.selector);
lock.release();
}
}上述八个测试覆盖了六个单维边界、一个双条件交叉边界,以及一次状态重复操作。`vm.expectRevert` 必须放在预期回滚的合约调用之前;对于成功分支则使用 `assertTrue` 检查状态实际变化。
边界覆盖结果可以逐项核对:
| 测试条件 | 时间戳 | 区块高度 | 预期行为 |
|---|---|---|---|
| 时间未到 | 阈值 - 1 | 105 | `TooEarly` |
| 时间恰好到期 | 阈值 | 105 | 释放成功 |
| 时间超过阈值 | 阈值 + 1 | 105 | 释放成功 |
| 高度未到 | 阈值 | 104 | `TooEarly` |
| 高度恰好达到 | 阈值 | 105 | 释放成功 |
| 高度超过阈值 | 阈值 | 106 | 释放成功 |
| 时间已到、高度未到 | 阈值 + 100 | 104 | `TooEarly` |
执行测试并定位边界缺陷
在包含 `foundry.toml` 且已安装 `forge-std` 的项目根目录执行:
forge test --match-contract BoundaryLockTest预期输出(仅展示关键结果,编译信息、执行时间及 Gas 数值可能不同):
Ran 8 tests for test/BoundaryLock.t.sol:BoundaryLockTest
[PASS] testBlockAfterThreshold()
[PASS] testBlockBeforeThreshold()
[PASS] testBlockExactlyAtThreshold()
[PASS] testCannotReleaseTwice()
[PASS] testTimeAfterThreshold()
[PASS] testTimeBeforeThreshold()
[PASS] testTimeExactlyAtThreshold()
[PASS] testTimeReachedButBlockNotReached()
Suite result: ok. 8 passed; 0 failed; 0 skipped实际输出的耗时、Gas 和编译日志由本地环境决定。若测试失败,可以执行 `forge test --match-test testTimeExactlyAtThreshold -vvvv` 查看具体失败位置。
尝试将合约中的时间判断从 `block.timestamp < unlockTime` 错改成 `block.timestamp <= unlockTime`,再次运行测试。此时恰好等于时间阈值的测试应当失败,因为合约错误地把到期时刻也视为未到期。将运算符恢复为 `<` 后重新运行,确认所有用例通过。
避免把模拟区块推进当成真实链运行
`vm.roll(105)` 直接设置区块高度,并不会生成从原高度到 105 的全部中间区块,也不会执行这些区块本应包含的交易。类似地,`vm.warp` 不会自动触发定时任务或调用合约函数。
假设某个合约按每个区块发放奖励,只调用一次 `roll` 再读取余额,并不能证明奖励会按经过的区块数自动入账。正确做法是测试业务函数如何根据高度差计算奖励,并单独验证领取时的状态更新。
另外,时间锁测试还应区分 `>=` 与 `>` 的业务含义。如果产品明确规定“截止时间之后才允许操作”,等于截止时间时应当拒绝;如果规定“达到截止时间即可操作”,等于阈值时应当成功。测试断言必须与业务约定一致,而不是机械地把等于阈值视为成功。
实际项目可把边界用例固定为三点组合:阈值减一、阈值本身、阈值加一。涉及时间与区块两个限制时,再补充其中一个满足、另一个不满足的交叉用例,才能有效发现遗漏条件、运算符错误以及过早释放等问题。