Skip to main content
本指南使用 KaleidoSDK 完整演示一次原子交换(节点直连),并同时提供 TypeScript 与 Python 示例。 原子交换无需信任:做市方始终不会托管你的资金,因为密钥由你自己的 RGB Lightning Node 持有,且必须先由它把交换加入白名单才能结算。这也意味着你需要在客户端旁运行一个 RLN 节点 —— 可选方案见 节点托管

环境准备

baseUrlnodeUrl 都必须提供:前者用于访问做市方,后者用于访问你自己的节点。

第 1 步:获取报价

为想要交换的交易对请求报价。金额一律使用原始整数单位 —— 转换辅助函数见 工具函数
响应中的 rfq_id 是把下一步与本次价格绑定起来的凭据。报价会过期 —— 不要让 rfq_id 跨越用户的思考时间,否则 initSwap 会抛出 QuoteExpiredError

第 2 步:初始化交换

依据该报价与做市方锁定交换。这一步返回后续每一步都要用到的 swapstringpayment_hash,以及授权状态轮询的 access_token —— access_token 只在这里返回一次,请与 payment hash 一起保存。

第 3 步:在接单方节点上加入白名单

你的节点必须先授权该 swapstring,才会接受传入的 HTLC。这是唯一一个通过 client.rln 执行的步骤。
跳过这一步是执行阶段出现 SwapError 的最常见原因:初始化成功,但由于接单方从未同意该交换,执行随即失败。

第 4 步:执行交换

把你节点的信息交给做市方,由它完成结算。

第 5 步:跟踪结算

executeSwap 返回并不等于交换已经结算。请携带 initSwap 返回的 access_token,按 payment_hash 轮询状态,直到进入终态。
如果某笔转移待处理的时间超出预期,client.rln.refreshTransfers() / refresh_transfers() 可以推进待处理的 RGB 转移,而 client.rln.listSwaps() 能让你看到节点自身的视图。各类失败情形见 故障排查

后续步骤

错误处理

异常层级结构,以及围绕每一步的重试模式。

交换协议

底层 HTLC 流程,逐个接口端点讲解,并附时序图。

WebSocket

流式接收实时报价,而不必逐条请求。

客户端参考

client.makerclient.rln 上的全部方法。