智能合约与以太坊 / 系统课时
编写可退款的 ETH 托管合约
编写可退款的 ETH 托管合约
当买家需要先付款、确认交付后再向卖家放款时,可以使用智能合约临时托管 ETH。本课实现一个单笔交易托管合约:买家存入 1 ETH,在七天期限内主动放款,逾期则申请退款,并通过 Foundry 自动化测试验证权限、资金守恒和状态转换。
学习目标
- 设计存款、放款、超时退款互斥的托管状态机,明确各状态允许执行的操作。
- 使用 Solidity 实现权限检查、截止时间判断、ETH 转账和失败回滚。
- 编写 Foundry 测试,验证资金流向、时间边界、重复结算和转账失败后的状态恢复。
定义托管状态与资金守恒规则
假设买家 A 向卖家 B 购买一件数字商品,约定托管金额为 1 ETH,交易期限为部署合约后的七天。买家先存款,确认交付后执行 release();如果到期仍未放款,则通过 refund() 收回资金。
本例采用四个状态,状态只能向前转换,不能返回已经完成的状态。
| 当前状态 | 允许的操作 | 转换条件 | 下一状态 |
|---|---|---|---|
| Created | deposit() |
买家调用、金额恰好为 1 ETH、尚未到期 | Funded |
| Funded | release() |
买家调用、当前时间早于截止时间 | Released |
| Funded | refund() |
买家调用、当前时间达到或超过截止时间 | Refunded |
| Released | 无资金操作 | 已经完成放款 | 终态 |
| Refunded | 无资金操作 | 已经完成退款 | 终态 |
这里规定 block.timestamp < deadline 才允许存款和放款,block.timestamp >= deadline 才允许退款。因此在截止时间这一秒,放款窗口已经关闭,退款窗口开始生效。

为了让守恒关系可以直接检查,假设买家初始拥有 10 ETH、卖家初始余额为零,并暂时忽略测试环境中不计入账户余额的 Gas 成本。
| 交易阶段 | 买家余额 | 托管余额 | 卖家余额 |
|---|---|---|---|
| 存款前 | 10 ETH | 0 ETH | 0 ETH |
| 存入 1 ETH 后 | 9 ETH | 1 ETH | 0 ETH |
| 成功放款后 | 9 ETH | 0 ETH | 1 ETH |
| 或者成功退款后 | 10 ETH | 0 ETH | 0 ETH |
后两行是从 Funded 状态出发的两种独立结局,不是连续执行的两个步骤。托管金额不能被支付两次;失败交易不得改变托管状态,也不得损失已存资金。
创建 Foundry 项目并确定合约接口
以下示例适用于 Solidity 0.8.24 及兼容的 0.8.x 编译器、包含 forge-std 的 Foundry 项目。先确认已安装 forge,本地环境能够下载或使用所需的 Solidity 编译器。
在终端执行:
forge init --no-git eth-escrow-lab
cd eth-escrow-lab预期结果:项目目录中出现 foundry.toml、src/、test/ 和 lib/forge-std/。具体终端提示可能因 Foundry 版本不同而变化。如果初始化时依赖下载失败,应检查网络和 Git 环境后重新执行。
在 src/EthEscrow.sol 中实现一个单笔托管合约。部署时确定四个参数:买家地址、卖家地址、托管金额和绝对截止时间戳。它们在部署后不可修改,避免任意一方在存款后偷偷修改收款地址或延长期限。
接口职责如下:
deposit():接收恰好等于约定金额的 ETH,仅允许买家调用一次。release():在截止时间之前向卖家支付托管金额,仅允许买家发起。refund():到期后向买家退还托管金额,仅允许买家发起。state():公开读取当前状态,供前端和自动化测试判断是否还能操作。
资金结算采用 Checks-Effects-Interactions 顺序:先检查权限、状态与时间,再把状态切换到终态,最后调用外部收款地址。这样即使收款方是恶意合约,其回调也不能再次从 Funded 状态完成结算。
实现 ETH 托管合约
新建或填写 src/EthEscrow.sol,完整代码如下。为了控制示例范围,每份合约只处理一笔固定金额的交易,不实现争议仲裁或批量订单。
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;
contract EthEscrow {
enum State { Created, Funded, Released, Refunded }
error NotBuyer();
error InvalidTerms();
error InvalidState();
error WrongAmount();
error Expired();
error TooEarly();
error PaymentFailed();
address public immutable buyer;
address payable public immutable seller;
uint256 public immutable amount;
uint256 public immutable deadline;
State public state;
event Deposited(address indexed from, uint256 value);
event Released(address indexed to, uint256 value);
event Refunded(address indexed to, uint256 value);
constructor(
address buyer_,
address payable seller_,
uint256 amount_,
uint256 deadline_
) {
if (
buyer_ == address(0) ||
seller_ == address(0) ||
buyer_ == seller_ ||
amount_ == 0 ||
deadline_ <= block.timestamp
) revert InvalidTerms();
buyer = buyer_;
seller = seller_;
amount = amount_;
deadline = deadline_;
// state 默认是 Created,对应枚举值 0。
}
modifier onlyBuyer() {
if (msg.sender != buyer) revert NotBuyer();
_;
}
function deposit() external payable onlyBuyer {
if (state != State.Created) revert InvalidState();
if (block.timestamp >= deadline) revert Expired();
if (msg.value != amount) revert WrongAmount();
state = State.Funded;
emit Deposited(msg.sender, msg.value);
}
function release() external onlyBuyer {
if (state != State.Funded) revert InvalidState();
if (block.timestamp >= deadline) revert Expired();
// 先结束可结算状态,再向外部地址转账。
state = State.Released;
(bool ok, ) = seller.call{value: amount}("");
if (!ok) revert PaymentFailed();
emit Released(seller, amount);
}
function refund() external onlyBuyer {
if (state != State.Funded) revert InvalidState();
if (block.timestamp < deadline) revert TooEarly();
// 退款失败会撤销状态更新,资金仍留在合约中。
state = State.Refunded;
(bool ok, ) = payable(buyer).call{value: amount}("");
if (!ok) revert PaymentFailed();
emit Refunded(buyer, amount);
}
}预期结果:编译器能够识别完整的合约定义,状态默认为 Created。只有成功存款才会进入 Funded;只有成功转账才能永久进入 Released 或 Refunded。
这里有三个必须理解的实现细节。
首先,msg.value 必须与 amount 完全相等。直接允许超额存款会产生不属于订单金额的余额,导致后续资金归属不清。因此 1 ETH 的订单发送 0.5 ETH 或 2 ETH 都应回滚。
其次,call{value: amount}("") 会将控制权交给接收方。使用返回的 ok 判断是否成功,并在失败时执行 revert PaymentFailed()。因为 EVM 的回滚是原子性的,之前更新的 state 和本次转账产生的状态变化都会被撤销。
最后,事件记录成功完成的存款、放款与退款,便于前端查询和审计。已经回滚的交易不会保留这些事件日志。事件也不能代替状态变量判断资金是否完成结算。
编写自动化测试覆盖关键分支
测试文件放在 test/EthEscrow.t.sol。通过 vm.deal 准备测试账户余额、vm.prank 模拟不同调用者、vm.warp 控制区块时间,并使用 vm.expectRevert 验证非法调用必须失败。
测试要覆盖五类行为:成功放款、边界时刻退款、未授权调用、错误金额与过期操作、收款方拒绝 ETH 后的原子回滚。为模拟最后一种场景,先定义一个收到 ETH 就主动回滚的合约。
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;
import {Test} from "forge-std/Test.sol";
import {EthEscrow} from "../src/EthEscrow.sol";
contract RejectEther {
receive() external payable {
revert("reject ETH");
}
}
contract EthEscrowTest is Test {
EthEscrow internal escrow;
address internal buyer = address(0xA11CE);
address payable internal seller = payable(address(0xB0B));
address internal stranger = address(0xBAD);
uint256 internal deadline;
function setUp() public {
vm.deal(buyer, 10 ether);
vm.deal(seller, 0);
deadline = block.timestamp + 7 days;
escrow = new EthEscrow(buyer, seller, 1 ether, deadline);
}
function fund() internal {
vm.prank(buyer);
escrow.deposit{value: 1 ether}();
}
function testReleaseMovesOneEther() public {
fund();
assertEq(address(escrow).balance, 1 ether);
assertEq(uint256(escrow.state()), 1);
vm.prank(buyer);
escrow.release();
assertEq(uint256(escrow.state()), 2);
assertEq(address(escrow).balance, 0);
assertEq(seller.balance, 1 ether);
assertEq(buyer.balance, 9 ether);
// 放款完成后,即使到期也不能再次退款。
vm.warp(deadline);
vm.expectRevert(EthEscrow.InvalidState.selector);
vm.prank(buyer);
escrow.refund();
}
function testRefundAtDeadline() public {
fund();
vm.warp(deadline - 1);
vm.expectRevert(EthEscrow.TooEarly.selector);
vm.prank(buyer);
escrow.refund();
// 截止时间包含在允许退款的范围内。
vm.warp(deadline);
vm.prank(buyer);
escrow.refund();
assertEq(uint256(escrow.state()), 3);
assertEq(address(escrow).balance, 0);
assertEq(buyer.balance, 10 ether);
assertEq(seller.balance, 0);
vm.expectRevert(EthEscrow.InvalidState.selector);
vm.prank(buyer);
escrow.release();
}
function testUnauthorizedCalls() public {
vm.deal(stranger, 1 ether);
vm.expectRevert(EthEscrow.NotBuyer.selector);
vm.prank(stranger);
escrow.deposit{value: 1 ether}();
fund();
vm.expectRevert(EthEscrow.NotBuyer.selector);
vm.prank(stranger);
escrow.release();
vm.warp(deadline);
vm.expectRevert(EthEscrow.NotBuyer.selector);
vm.prank(stranger);
escrow.refund();
assertEq(address(escrow).balance, 1 ether);
}
function testWrongAmountAndExpiry() public {
vm.expectRevert(EthEscrow.WrongAmount.selector);
vm.prank(buyer);
escrow.deposit{value: 0.5 ether}();
assertEq(address(escrow).balance, 0);
fund();
vm.expectRevert(EthEscrow.InvalidState.selector);
vm.prank(buyer);
escrow.deposit{value: 1 ether}();
vm.warp(deadline);
vm.expectRevert(EthEscrow.Expired.selector);
vm.prank(buyer);
escrow.release();
assertEq(uint256(escrow.state()), 1);
assertEq(address(escrow).balance, 1 ether);
}
function testRejectedPayoutRollsBack() public {
RejectEther receiver = new RejectEther();
EthEscrow blocked = new EthEscrow(
buyer,
payable(address(receiver)),
1 ether,
deadline
);
vm.prank(buyer);
blocked.deposit{value: 1 ether}();
// 外部接收方回滚,不能留下已放款的假状态。
vm.expectRevert(EthEscrow.PaymentFailed.selector);
vm.prank(buyer);
blocked.release();
assertEq(uint256(blocked.state()), 1);
assertEq(address(blocked).balance, 1 ether);
assertEq(address(receiver).balance, 0);
}
}预期结果:五个测试函数分别验证成功和失败路径。setUp() 会在每个测试开始前重新部署合约,因此一个测试的放款或退款结果不会污染其他测试。测试中状态值 0、1、2、3 分别对应 Created、Funded、Released、Refunded。
尤其要检查 testRejectedPayoutRollsBack:如果只检查调用会不会回滚,却不核对回滚后的状态和余额,就可能漏掉资金记账错误。这里要求失败之后状态仍为 Funded,1 ETH 仍然留在托管合约,拒收方余额为零。
运行测试并检查验收结果
保存两个 Solidity 文件后,在项目根目录执行编译和定向测试:
forge build
forge test --match-contract EthEscrowTest -vv预期结果:编译成功,定向测试包含五个成功用例,零个失败用例。终端中的 Gas、执行时间和文件路径会随环境变化;关键测试摘要应包含以下结果:
Suite result: ok. 5 passed; 0 failed; 0 skipped如果出现失败,不要只调整断言让测试通过,应根据失败类型检查资金路径。
| 失败现象 | 优先检查位置 | 正确结果 |
|---|---|---|
| 错误金额仍存款成功 | msg.value != amount |
回滚且余额不增加 |
| 未到期可以退款 | block.timestamp < deadline |
返回 TooEarly |
| 到期仍然可以放款 | release() 的时间检查 |
返回 Expired |
| 结算后还能执行另一种结算 | Funded 状态前置检查 | 返回 InvalidState |
| 接收方拒绝 ETH 后状态已结算 | call 返回值与 revert |
状态回到 Funded、余额保留 |
这个最小项目的验收标准是:正常结算只支付一次 1 ETH;没有权限的人无法改变托管状态;时间边界严格遵守截止时间;所有被拒绝的调用均不改变托管资金;两个终态互斥且不可再次结算。
还要区分业务记账金额与 EVM 地址余额。生产环境可能存在通过特殊链上机制强制向合约增加 ETH 的情况,因此不能把 address(this).balance == amount 当作任何环境下都成立的安全不变量。本例用固定的 amount 作为待结算金额,并在没有外部强制转入资金的正常测试环境下检查合约余额。正式多订单系统需要单独维护各订单的负债总额。
完成这些测试后,可以确认单笔托管的主要状态转换和资金路径符合预期,但不能据此断言合约已经具备生产安全性。特别是买家失去密钥、收款合约持续拒收 ETH、发生交付争议等场景,仍需要在真实资金上线前设计可执行的恢复与仲裁机制。