← COMP5521 全部讲次
Lab4b · 第 6 周

Lab4b 写一份能跑的 HTLC:接口、四步流程和本地演示

按课件接口实现 HTLC 合约,在本地链上跑通 approve、lock、claim、refund,并对照课程仓库的差异。

一句话版

HTLC 合约是一个带期限的托管箱:截止前凭 secret 领,截止后原主退。

先认识这几个词

词 全称 / 读法 一句人话
hashlock / timelock 哈希锁 / 时间锁 领钱要交出的密码指纹;过了就只能退款的截止时间
swapId 交换编号 一笔锁仓的编号,之后领款、退款都靠它找到这一笔
claim / refund 领取 / 退款 收款方凭 secret 领钱;过期后发送方取回
block.timestamp 区块时间戳,单位秒 合约眼里的「现在几点」,取自当前区块
keccak256 Keccak-256,以太坊用的哈希函数 hashlock 就是 secret 过一遍它得到的指纹
gas 燃料费 每笔交易付给网络的手续费,余额变化里要把它扣掉或加回来看

题目地图

本页讲 Lab4 课件后半,原理部分(为什么 T2 < T1)在 Lab4a。Alice 和 Bob 各在自己那条链上放一个托管箱,用同一个 hashlock 连起来。课件这一段只给接口和命令。下面补了一份按课件接口写的完整合约和两段演示,在本地 Hardhat 网络实测通过。本地只有一条链,所以用同一条链上的两个 HTLC 合约分别扮演 Chain A 和 Chain B。

段落 学什么 主要失分点
接口 五个函数、三个事件 说不出 lock1 为什么没有 amount 参数
四步流程 approve/lock → 对方 lock → claim → refund 把 approve 当成转账
课程仓库演示 八个脚本按顺序跑 照搬仓库的 timelock 设置
资源 仓库、RPC、水龙头 无

概念卡

1. 托管合约(escrow)

人话定义:它解决「互不信任的两个人谁先把钱交出去」。资产先转进一份代码公开、部署后不可改的合约,由合约按写死的条件放给收款方或退回发送方。

例子:Alice 调 lock 后,100 MST 从她的账户进入 ERC20HTLC 合约。之后这笔钱只有两条出路:Bob 出示 secret 领走,或者过期后退给 Alice。课件说它可信,理由是代码公开、不可改、没人能叫停。

常见误解

以为合约里的钱 Alice 还能随时取回 → 截止前只有 claim 一条路,Alice 自己也动不了;截止后才轮到 refund。

回讲义:L10c 合约的一生:部署、算地址、调用、自毁

2. swapId

人话定义:它解决「合约里锁着很多笔钱,怎么指认是哪一笔」。swapId 是一笔锁仓的编号,lock 时由合约生成并返回,之后 claim、refund、getSwap 都靠它找。

例子:参考实现把收发双方、代币、金额、hashlock、timelock 和一个递增的 nonce(计数器)一起哈希成 swapId。两条链上各有一笔锁仓,所以有两个 swapId:mstSwapId 和 ethSwapId。secret 却只有一个。加 nonce 是为了让参数完全相同的两次锁仓也得到不同编号,后一笔不会覆盖前一笔。

常见误解

以为 swapId 和 hashlock 是一回事 → hashlock 两条链共用,swapId 每条链各一个。课程仓库的写法又不同,swapId 由调用方传入,见下面的对照表。

回讲义:L09a 比特币交易长什么样:钱住在输出里,输入只是指针

3. 时间条件互斥

人话定义:它保证「领款和退款不会同时成立」。claim 要求 block.timestamp ≤ timelock,refund 要求 block.timestamp > timelock。意思是:截止前只能领,截止后只能退。

例子:本地实测里,到期前调 refund 报 not expired。把时间快进 3601 秒之后,拿着正确的 secret 调 claim 报 expired,refund 才成功。时间用的是区块时间,单位是秒,和运行脚本那台电脑的时钟无关。

常见误解

以为过期后收款方还能补领 → 不能,过期后 claim 一律失败,这正是 Lab4a 情形三里 Bob 受损的原因。

回讲义:L09c 比特币脚本:输出上挂锁,输入里带钥匙

逐题拆解

接口。lock1(recipient, hashlock, timelock) 带 payable(允许附带 ETH)。它锁的金额就是交易附带的 msg.value。lock2 锁 ERC-20,参数是 (token, recipient, amount, hashlock, timelock)。它比 lock1 多出 token 和 amount,调用前要先 approve。Claimed 事件(合约写进日志、链下可读的记录)里带着 secret,Bob 就是从这里读到它的。下面是按这个接口写的 contracts/SimpleHTLC.sol,实测可编译:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;
import "@openzeppelin/contracts/token/ERC20/IERC20.sol";
import "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol";
import "@openzeppelin/contracts/utils/ReentrancyGuard.sol";

contract SimpleHTLC is ReentrancyGuard {
    using SafeERC20 for IERC20;
    struct Swap {
        address sender; address recipient;
        address token;          // address(0) 表示原生 ETH
        uint256 amount; bytes32 hashlock; uint256 timelock;
        bool claimed; bool refunded;
        bytes32 secret;         // claim 成功后写入,任何人可读
    }
    mapping(bytes32 => Swap) private swaps;
    uint256 private nonce;

    event Locked(bytes32 indexed swapId, address indexed sender, address indexed recipient,
                 address token, uint256 amount, bytes32 hashlock, uint256 timelock);
    event Claimed(bytes32 indexed swapId, bytes32 secret);
    event Refunded(bytes32 indexed swapId);

    function lock1(address recipient, bytes32 hashlock, uint256 timelock)
        external payable returns (bytes32 swapId) {
        require(msg.value > 0, "amount = 0");
        swapId = _create(recipient, address(0), msg.value, hashlock, timelock);
    }
    function lock2(address token, address recipient, uint256 amount, bytes32 hashlock, uint256 timelock)
        external nonReentrant returns (bytes32 swapId) {
        require(token != address(0) && amount > 0, "bad token/amount");
        swapId = _create(recipient, token, amount, hashlock, timelock);
        IERC20(token).safeTransferFrom(msg.sender, address(this), amount); // 需事先 approve
    }
    function claim(bytes32 swapId, bytes32 secret) external nonReentrant {
        Swap storage s = swaps[swapId];
        require(s.sender != address(0), "no swap");
        require(!s.claimed && !s.refunded, "closed");
        require(block.timestamp <= s.timelock, "expired");
        require(keccak256(abi.encodePacked(secret)) == s.hashlock, "bad secret");
        s.claimed = true; s.secret = secret;
        _pay(s.token, s.recipient, s.amount);
        emit Claimed(swapId, secret);
    }
    function refund(bytes32 swapId) external nonReentrant {
        Swap storage s = swaps[swapId];
        require(s.sender != address(0), "no swap");
        require(!s.claimed && !s.refunded, "closed");
        require(block.timestamp > s.timelock, "not expired");
        s.refunded = true;
        _pay(s.token, s.sender, s.amount);
        emit Refunded(swapId);
    }
    function getSwap(bytes32 swapId) external view returns (Swap memory) { return swaps[swapId]; }

    function _create(address recipient, address token, uint256 amount, bytes32 hashlock, uint256 timelock)
        private returns (bytes32 swapId) {
        require(recipient != address(0), "bad recipient");
        require(timelock > block.timestamp, "timelock in past");
        swapId = keccak256(abi.encode(msg.sender, recipient, token, amount, hashlock, timelock, nonce++));
        swaps[swapId] = Swap(msg.sender, recipient, token, amount, hashlock, timelock, false, false, bytes32(0));
        emit Locked(swapId, msg.sender, recipient, token, amount, hashlock, timelock);
    }
    function _pay(address token, address to, uint256 amount) private {
        if (token == address(0)) {
            (bool ok, ) = payable(to).call{value: amount}("");
            require(ok, "ETH transfer failed");
        } else {
            IERC20(token).safeTransfer(to, amount);
        }
    }
}

设计上有四点。claimed、refunded 两个标志保证一笔锁仓只能结束一次。先改标志再转账,加上 ReentrancyGuard 防重入(转账途中被对方回头反复调用)。claim 不限定调用者,钱总是转给 recipient;refund 也一样,钱总是退给 sender。SafeERC20 防的是 Lab3 里那种余额不足却不报错的代币。secret 是 32 字节的 bytes32。链下用 ethers.keccak256(secret) 算出的 hashlock,和合约里 keccak256(abi.encodePacked(secret)) 算出的是同一个值。链下若对字符串做哈希,claim 会一直失败。

四步流程

完整演示脚本是 scripts/swapDemo.js,它和 Lab3 的 MySimpleToken.sol 放在同一个项目里,用 npx hardhat run scripts/swapDemo.js 运行。它的主干:

const secret = ethers.hexlify(ethers.randomBytes(32));      // 0. Alice 生成 secret
const hashlock = ethers.keccak256(secret);
const now = (await ethers.provider.getBlock("latest")).timestamp;
const mstTimelock = now + 2 * 3600, ethTimelock = now + 1 * 3600;   // T2 < T1
await mst.connect(alice).approve(htlcA.target, mstAmount);          // 1. approve + lock2
const mstSwapId = await idFrom(await htlcA.connect(alice)
  .lock2(mst.target, bob.address, mstAmount, hashlock, mstTimelock), htlcA);
const s = await htlcA.getSwap(mstSwapId);                           // 2. Bob 核对后 lock1
const ethSwapId = await idFrom(await htlcB.connect(bob)
  .lock1(alice.address, hashlock, ethTimelock, { value: ethAmount }), htlcB);
await htlcB.connect(alice).claim(ethSwapId, secret);                // 3. Alice 领 ETH
const revealed = (await htlcB.getSwap(ethSwapId)).secret;           //    secret 上链
await htlcA.connect(bob).claim(mstSwapId, revealed);                // 4. Bob 领 MST

idFrom 从交易回执里解析 Locked 事件取出 swapId。实测输出共 13 行,这里摘最能说明问题的 6 行。其余几行是:Bob 的四项核对全为 true,HTLC-B 持有 0.001 ETH,Bob 读到的 secret 与原值一致:

Alice MST after approve: 100.0
Alice MST after lock2  : 0.0
claim with wrong secret -> VM Exception while processing transaction: reverted with reason string 'bad secret'
Alice ETH delta + gas  : 0.001
Bob MST                : 100.0
second claim -> VM Exception while processing transaction: reverted with reason string 'closed'

逐行看。approve 后 Alice 余额还是 100,lock2 后才变 0。课件那条总结说「approve 时资产还没动」,只对 approve 这一步成立,lock 之后钱就已经进了合约。错误的 secret 被拒,说明哈希锁在起作用。Alice 领到 0.001 ETH,输出把这笔 claim 的 gas 加了回去,所以正好是整数。Bob 用从链上读到的 secret 领到 100 MST,HTLC-A 随之清空。同一笔锁仓第二次领取被拒,因为 claimed 标志已经是 true。

一步一步看

目标:对照实测输出走完授权、两边锁仓和领款,看出错的 secret 会回滚,Alice 公开的 secret 让 Bob 也能领款。

下面每一帧对应实测输出里的一步,Alice 起始有 100 MST,Bob 起始有 0.001 ETH 可锁。

  1. Alice 调 approve,授权 HTLC-A 代扣 100 MST。余额不动,只多了一笔授权额度。

    第 1 帧:四个格子 Alice、HTLC-A、HTLC-B、Bob;Alice 仍有 100 MST,HTLC-A 余额 0 但可代扣 Alice 100,HTLC-A 青绿标出

  2. Alice 调 lock2,合约用 transferFrom 把 100 MST 拉进 HTLC-A,期限 now + 7200。

    第 2 帧:Alice 变成 0 MST,HTLC-A 持有 100 MST,授权额度用完归零,HTLC-A 青绿标出

  3. Bob 用 getSwap 核对 recipient、amount、hashlock、timelock 四项,全为 true 后调 lock1,附带 0.001 ETH,期限 now + 3600。

    第 3 帧:HTLC-B 青绿标出,持有 0.001 ETH、截止 now 加 3600;Bob 格子写着四项核对全为 true

  4. Alice 先用错误的 secret 调 claim,报 bad secret,交易回滚,余额一个都没变。

    第 4 帧:四个格子余额和上一帧一样,下方这一步一栏青绿标出 bad secret 回滚

  5. Alice 用正确的 secret 调 claim,领到 0.001 ETH。secret 写进了这笔交易和 HTLC-B 的记录,谁都能读。

    第 5 帧:HTLC-B 变成 0、claimed 为 true,Alice 多了 0.001 ETH;secret 一栏青绿标出,已经公开在链上

  6. Bob 从 HTLC-B 读到 secret,拿它在 HTLC-A 上 claim,领到 100 MST,HTLC-A 清空。

    第 6 帧:Bob 格子青绿标出,持有 100 MST;HTLC-A 和 HTLC-B 都已清空,交换完成

  7. Bob 对同一笔锁仓再 claim 一次,报 closed,因为 claimed 已经是 true。

    第 7 帧:余额都没变,这一步一栏青绿标出 closed,同一笔锁仓第二次领取被拒

退款路径

退款路径用 scripts/refundDemo.js 测。Bob 锁 0.001 ETH,期限 now + 3600,到期前调 refund。再用 evm_increaseTime 快进 3601 秒,让 Alice 调 claim,再让 Bob refund。实测输出依次是 'not expired'、'expired'、Bob ETH back (+gas) : 0.001、refunded flag : true。快进时间只在本地网络有效,测试网上只能真等。

一步一步看

目标:跟着退款路径的四次调用,看出到期前不能退款、到期后不能领款,最后 ETH 回到 Bob。

  1. Bob 调 lock1,锁 0.001 ETH 给 Alice,timelock 是 now + 3600。

    退款第 1 帧:三个格子 Bob、HTLC、Alice;HTLC 青绿标出,持有 0.001 ETH、timelock 为 now 加 3600;区块时间还是 now

  2. 还没到期,Bob 调 refund,报 not expired。

    退款第 2 帧:余额没变,区块时间没超过 timelock,这一步一栏青绿标出 not expired

  3. 用 evm_increaseTime 快进 3601 秒,Alice 拿正确的 secret 调 claim,报 expired。

    退款第 3 帧:区块时间变成 now 加 3601、超过 timelock,这一步一栏青绿标出 expired,过期后领款被拒

  4. Bob 再调 refund,0.001 ETH 回到 Bob,refunded 变成 true。

    退款第 4 帧:Bob 格子青绿标出,0.001 ETH 退回;HTLC 清空,refunded 标记为 true

课程仓库演示

clone 课程仓库,npm install,复制 .env.example 为 .env。在里面填 RPC、Alice 和 Bob 两个测试账户的私钥和地址、Lab3 的 MST 地址。之后按课件顺序跑十步,全部加 --network sepolia:deploySimpleHTLC、generateSecret、checkBalances、lockMST、lockETH。接着是 checkSwap、claimETH、claimMST、checkSwap、checkBalances。这一段需要真实 RPC 和测试币,本页没有实测。演示只部署在 Sepolia 一条链上,ETH 一侧锁的是 Sepolia ETH,模拟的是流程,并没有真正跨链。两个私钥都要用专门的测试账户,.env 不能提交。

仓库合约和课件接口不一样,读代码时对照着看:

课件接口 课程仓库
锁仓函数 lock1、lock2 createETHSwap、createERC20Swap
swapId 合约生成并返回 调用方传入
claim 收款方出示 secret 只允许 receiver 调用,要求 timestamp < timelock
refund 有 没有
事件 Locked、Claimed、Refunded SwapCreated、SwapClaimed

课件里的坑

  • [课件有误] p.15 三处:ERCHTLC 是 ERC20HTLC 的笔误;approve 说明里的 1000 与 p.9 的 100 MST 不一致;Key Takeaway 写 No assets have moved yet,和上一条 MST moves into the ERC20HTLC contract 矛盾,这句只对 approve 那一步成立,上面实测的余额变化就是证据。
  • [适用条件] p.23 的 timelock:仓库两个锁仓脚本都把期限设为本机时间加 3600 秒,lockETH 后运行,ETH 一侧反而更晚到期,T2 > T1,正是 Lab4a 的情形三。演示由一个人扮演两方,没人作弊所以没事;自己写的时候让 Bob 一侧明显更短,并以区块时间为准。
  • [补充] 仓库没有 refund:对方一直不领时,锁进去的资产取不回来,上面的 refundDemo 补了这条路径。
  • [读图提醒] p.22 和 p.24:generateSecret 把 preimage 写进同一个 .env,claimMST 也从 .env 直接读它,这是一个人演两个角色的简化。真实场景里 Bob 只拿得到 hashlock,secret 要从 Alice 那笔 claim 交易里读。p.24 的第 7、8 步都编号成了 7.,是笔误。

课后 10 分钟:考点复习

这 10 分钟怎么用:先默写五个函数各自的时间条件和调用者,再做完整例题,把每一步之后的余额和合约状态写出来;最后做变式题。

必背

  1. HTLC 接口:lock1 锁 ETH(payable)、lock2 锁 ERC-20、claim、refund、getSwap;事件 Locked、Claimed(带 secret)、Refunded。
  2. lock2 之前必须 approve;approve 只改授权额度不动余额,lock 才转移资产。
  3. claim 要求 block.timestamp ≤ timelock 且 keccak256(secret) == hashlock;refund 要求 block.timestamp > timelock。
  4. Bob 锁仓前核对 recipient、amount、hashlock、timelock 四项,两笔锁仓只靠 hashlock 在逻辑上关联。
  5. 两次 claim 用各自链上的 swapId、同一个 secret;Alice 领款后 Bob 从链上读出 secret。
  6. 课程仓库的合约没有 refund,两个锁仓脚本的 timelock 默认都是本机时间加 3600 秒。

完整例题

Alice 有 100 MST。依次发生:Alice approve HTLC-A 100 MST;Alice 调 lock2 锁 100 MST 给 Bob;Bob 调 lock1 锁 0.001 ETH 给 Alice;Alice 用错误的 secret 调 claim;Alice 用正确的 secret 调 claim;Bob 用读到的 secret 调 claim 两次。写出每步之后 Alice 的 MST、HTLC-A 的 MST、HTLC-B 的 ETH,以及失败的那几步报什么。

  1. approve 后:Alice 100,HTLC-A 0,只有 allowance 变成 100。
  2. lock2 后:Alice 0,HTLC-A 100。
  3. lock1 后:HTLC-B 持有 0.001 ETH。
  4. 错误 secret:keccak256 对不上,报 bad secret,状态不变。
  5. 正确 secret:HTLC-B 变 0,Alice 收到 0.001 ETH,secret 写进 getSwap 和 Claimed 事件。
  6. Bob 第一次 claim:HTLC-A 变 0,Bob 得 100 MST。第二次:claimed 已是 true,报 closed。

答案与上面的实测输出逐行一致。

变式题(先自己做)

Bob 锁了 0.001 ETH 给 Alice,期限 T2 = now + 3600。(1) 在 now + 1000 时 Bob 调 refund 会怎样?(2) 在 now + 3601 时 Alice 拿着正确的 secret 调 claim 会怎样?(3) 紧接着 Bob 调 refund,然后又调一次 refund,各自结果如何?(4) 如果用的是课程仓库的合约,(3) 能做到吗?

提示

claim 和 refund 的时间条件正好互斥;两个标志保证只能结束一次;再对照仓库缺了哪个函数。

判分点与答案

(1) 没过期,报 not expired。(2) 已过期,报 expired,secret 对也没用。(3) 第一次 refund 成功,Bob 拿回 0.001 ETH,refunded 变 true;第二次报 closed。(4) 做不到,仓库合约没有 refund,ETH 会一直留在合约里。

闪卡自测

1. lock1 为什么没有 amount 参数?

金额就是交易附带的 msg.value,ETH 也不需要指明资产合约。

2. Bob 从哪里读到 secret?

Alice 那笔 claim 的交易参数、Claimed 事件,或者 getSwap 返回的 secret 字段。

3. 合约为什么先改标志再转账?

防重入:转账时对方合约回调进来,标志已经是 true,再调就失败。

4. 本地演示为什么用两个合约代替两条链?

本地网络只有一条链,两个 HTLC 分别扮演 Chain A 和 Chain B,流程相同。

下一步

Project 要用两条真链:Chain A 是 Ethereum Sepolia,Chain B 是 Arbitrum Sepolia,需要在 hardhat.config.js 里再配一个网络,并给 Bob 准备 Arbitrum Sepolia 的测试 ETH。先把本页的合约和两段演示在本地跑通,再故意把 T2 设得比 T1 长,用 evm_increaseTime 复现 Lab4a 的作弊路径,亲眼看到 Bob 领取失败。

下一讲 →
L06a L06a 3-D Secure 架构:三个域、两台关键服务器、五条加密线路

个人整理的学习笔记,不是官方材料;数字与结论以课件和讲师为准。