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

编写可退款的 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 才允许退款。因此在截止时间这一秒,放款窗口已经关闭,退款窗口开始生效。

ETH 托管状态转换与资金流向

为了让守恒关系可以直接检查,假设买家初始拥有 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 编译器。

在终端执行:

bash
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,完整代码如下。为了控制示例范围,每份合约只处理一笔固定金额的交易,不实现争议仲裁或批量订单。

solidity
// 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 就主动回滚的合约。

solidity
// 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 文件后,在项目根目录执行编译和定向测试:

bash
forge build
forge test --match-contract EthEscrowTest -vv

预期结果:编译成功,定向测试包含五个成功用例,零个失败用例。终端中的 Gas、执行时间和文件路径会随环境变化;关键测试摘要应包含以下结果:

text
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、发生交付争议等场景,仍需要在真实资金上线前设计可执行的恢复与仲裁机制。

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

目录与阅读设置

阅读设置

17

记录一个想法

编写可退款的 ETH 托管合约

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

登录哪都通