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。
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 受损的原因。
逐题拆解
接口。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 可锁。
-
Alice 调 approve,授权 HTLC-A 代扣 100 MST。余额不动,只多了一笔授权额度。
-
Alice 调 lock2,合约用 transferFrom 把 100 MST 拉进 HTLC-A,期限 now + 7200。
-
Bob 用 getSwap 核对 recipient、amount、hashlock、timelock 四项,全为 true 后调 lock1,附带 0.001 ETH,期限 now + 3600。
-
Alice 先用错误的 secret 调 claim,报 bad secret,交易回滚,余额一个都没变。
-
Alice 用正确的 secret 调 claim,领到 0.001 ETH。secret 写进了这笔交易和 HTLC-B 的记录,谁都能读。
-
Bob 从 HTLC-B 读到 secret,拿它在 HTLC-A 上 claim,领到 100 MST,HTLC-A 清空。
-
Bob 对同一笔锁仓再 claim 一次,报 closed,因为 claimed 已经是 true。
退款路径
退款路径用 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。
-
Bob 调 lock1,锁 0.001 ETH 给 Alice,timelock 是 now + 3600。
-
还没到期,Bob 调 refund,报 not expired。
-
用 evm_increaseTime 快进 3601 秒,Alice 拿正确的 secret 调 claim,报 expired。
-
Bob 再调 refund,0.001 ETH 回到 Bob,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 分钟怎么用:先默写五个函数各自的时间条件和调用者,再做完整例题,把每一步之后的余额和合约状态写出来;最后做变式题。
必背
- HTLC 接口:lock1 锁 ETH(payable)、lock2 锁 ERC-20、claim、refund、getSwap;事件 Locked、Claimed(带 secret)、Refunded。
- lock2 之前必须 approve;approve 只改授权额度不动余额,lock 才转移资产。
- claim 要求 block.timestamp ≤ timelock 且 keccak256(secret) == hashlock;refund 要求 block.timestamp > timelock。
- Bob 锁仓前核对 recipient、amount、hashlock、timelock 四项,两笔锁仓只靠 hashlock 在逻辑上关联。
- 两次 claim 用各自链上的 swapId、同一个 secret;Alice 领款后 Bob 从链上读出 secret。
- 课程仓库的合约没有 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,以及失败的那几步报什么。
- approve 后:Alice 100,HTLC-A 0,只有 allowance 变成 100。
- lock2 后:Alice 0,HTLC-A 100。
- lock1 后:HTLC-B 持有 0.001 ETH。
- 错误 secret:keccak256 对不上,报 bad secret,状态不变。
- 正确 secret:HTLC-B 变 0,Alice 收到 0.001 ETH,secret 写进 getSwap 和 Claimed 事件。
- 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 领取失败。
个人整理的学习笔记,不是官方材料;数字与结论以课件和讲师为准。