闪电网络适配 Setu or DAG 链 — 改造重构文档

0. Overview

将 LND 闪电网络改造为同时支持 Bitcoin + Setu 双链。Setu 是基于对象账户模型的 DAG 区块链，使用自定义 10 操作码解释器（ProgramTx）作为合约语言，密码学同时支持 secp256k1 和 Ed25519，通道以 32 字节 ObjectID 标识。改造策略：在现有 Bitcoin 类型之上引入链无关抽象层，Bitcoin 保留为一个实现，Setu 作为另一个实现插入，通过 ChainControl 做双链调度。

核心改造工作量分布：新增抽象层（40%）→ Setu 后端实现（30%）→ 现有模块适配接口（20%）→ Setu 链上合约（10%）。

1. 流程交互图

如下 7 张图分别覆盖了：

  1. 架构总览 — 双链抽象层分层与模块关系
  2. 通道生命周期对比 — Bitcoin vs Setu 的流程差异一目了然
  3. 开通道序列 — 详细的双方+链交互时序
  4. 多跳 HTLC 支付 — 正常流转与异常超时的完整序列
  5. 强制关闭与争议解决 — 含违约惩罚的完整决策流程
  6. Script→ProgramTx 映射 — 每个 Bitcoin 操作码如何翻译为 Setu 10 操作码
  7. 改造阶段依赖 — 5 个 Phase 的执行顺序与依赖
  8. 链上/链下数据流全景 — 完整的通道生命周期交互泳道

1. 双链抽象架构总览

2. 通道生命周期对比（Bitcoin vs Setu）

  • 图1：Bitcoin 闪电网络通道生命周期
  • 图2：Setu 闪电网络通道生命周期

3. 开通道序列交互图（Setu 适配）

4. 多跳 HTLC 支付序列图

5. 强制关闭与争议解决流程图

6. Setu ProgramTx 合约逻辑映射图

7. 模块改造优先级与依赖关系

8. 数据流：链上 vs 链下交互全景

2. 改造步骤

1. 新增 chaintype/ 包 — 链无关基础类型

在项目根目录创建独立包，定义所有链无关的原始类型，替代 Bitcoin 特定类型在接口层的直接使用：

新类型替代说明
chaintype.TxIDchainhash.Hash32 字节交易/对象标识
chaintype.ChannelPointwire.OutPointBitcoin: {TxID, Index}；Setu: ObjectID
chaintype.Amountbtcutil.Amount统一金额类型（int64 最小单位）
chaintype.RawTx*wire.MsgTx字节序列化交易（链特定格式不透明传递）
chaintype.Addressbtcutil.Address统一地址接口
chaintype.PubKey*btcec.PublicKey[]byte（secp256k1 33 字节 / Ed25519 32 字节）
chaintype.Signature*ecdsa.Signature[]byte（链特定编码）
chaintype.FeeRatechainfee.SatPerKWeight抽象费率（Bitcoin: sat/kw, Setu: gas price）
chaintype.BlockHeightuint32Bitcoin: 区块高度；Setu: epoch 编号
chaintype.ShortChannelIDlnwire.ShortChannelIDBitcoin: 8 字节 block:tx:pos；Setu: ObjectID 哈希截断或直接 32 字节

同时定义 chaintype.ChainID 枚举标识当前链（Bitcoin/Setu），以及 chaintype.Converter 接口做不同链类型间的编解码。

2. 重定义核心链后端接口

修改以下接口使其使用 chaintype.* 而非 wire.*/btcutil.*。保留现有 Bitcoin 实现，通过包装器 (wrapper) 在 Bitcoin 侧做类型转换：

  • ChainNotifier (interface.go) — RegisterConfirmationsNtfn/RegisterSpendNtfn 参数从 *chainhash.Hash/*wire.OutPoint 改为 chaintype.TxID/chaintype.ChannelPoint
  • BlockChainIO (interface.go:567-597) — GetBestBlock/GetUtxo/GetBlock 返回值抽象化
  • Signer (signer.go) — SignOutputRaw/ComputeInputScript 参数从 *wire.MsgTx 改为 chaintype.RawTx + 抽象 SignRequest
  • WalletController (interface.go:230-563) — 这是最大挑战；策略是拆分为通用钱包接口（余额查询、转账、地址生成）+ 链特有扩展接口（Bitcoin: PSBT/UTXO 操作；Setu: 对象操作）

3. 扩展 ChainControl 为链调度器

修改 chainregistry.go:193-220 中的 ChainControl 结构体：

  • 新增 ChainType chaintype.ChainID 字段
  • 在 chainregistry.go:266-350 的 switch 语句中新增 "setu" 分支
  • 创建 chainreg/setu_params.go 定义 SetuNetParams（网络 ID、创世哈希、默认端口、epoch 间隔）
  • 修改 config.go:249 新增 SetuChainName = "setu" 和 Setu *lncfg.Chain 配置项

4. 实现 Setu 链通知后端 chainntnfs/setunotify/

实现 ChainNotifier 接口，核心映射关系：

Bitcoin 概念Setu 实现
RegisterConfirmationsNtfn(txid, numConfs)订阅对象最终确定事件（DAG 最终性通常 1 次确认即可）
RegisterSpendNtfn(outpoint)订阅 Channel Object 状态变更（余额变化/对象销毁）
RegisterBlockEpochNtfn()订阅 Setu epoch 推进事件
区块重组检测大幅简化（DAG 无经典重组）
GetBlock() / GetBlockHash()查询 epoch 信息 / DAG 轮次数据

5. 实现 Setu 钱包 lnwallet/setuwallet/

实现适配后的 WalletController 接口：

Bitcoin 操作Setu 操作
ListUnspentWitness() — 列出 UTXOGetBalance() — 查询账户余额
LeaseOutput(OutPoint) — 锁 UTXOReserveBalance(amount) — 预留余额
SendOutputs([]*wire.TxOut) — 构建 TXTransfer(to, amount) — 调用转账
FundPsbt() / SignPsbt()BuildProgramTx() / SignProgramTx() — 构建 Setu 可编程交易
币选择（selectInputs）不需要（直接从余额扣减）
找零地址生成不需要

密钥管理方面：复用 derivation.go 的 KeyFamily 体系，新增 Setu coinType，密钥衍生支持 secp256k1 和 Ed25519 双路径。

6. Setu 链上脚本合约 — 基于 10 操作码解释器

基于 Setu 的 ProgramTx 和 {Nop, Const, Mov, BinOp, Cmp, LoadInput, StoreOutput, Jump, JumpIf, Halt} 操作码，实现以下闪电网络核心合约逻辑：

6a. 通道资金合约（Channel Funding Program）：

  • 使用 Const + Cmp + JumpIf 实现双方签名验证分支
  • LoadInput 加载签名数据，BinOp 做哈希计算
  • 对象字段存储：local_balance, remote_balance, local_key, remote_key, state_num

6b. HTLC 合约程序：

  • 三路径分支（JumpIf）：① 原像解锁（BinOp 做 SHA256 比较）② 超时回收（Cmp 比较当前 epoch）③ 撤销惩罚（签名验证）
  • LoadInput 从交易输入加载原像/签名
  • StoreOutput 写入余额变更

6c. 时间锁实现：

  • 相对时间锁（CSV 等价）：LoadInput(current_epoch) → Const(creation_epoch + delay) → Cmp → JumpIf(fail)
  • 绝对时间锁（CLTV 等价）：LoadInput(current_epoch) → Const(expiry_epoch) → Cmp → JumpIf(fail)

6d. 撤销/惩罚机制：

  • 对象状态中存储 revocation_key
  • 若检测到旧状态广播，持有撤销密钥的一方可调用惩罚入口（通过签名验证分支）

在 Go 侧创建 input/setu_programs.go，封装上述合约的构建函数（等价于现有 script_utils.go 的 3275 行 Bitcoin Script 构建）。

7. 通道标识体系重设计

  • 修改 channel_id.go — NewChanIDFromOutPoint 在 Setu 链上直接使用 ObjectID 的前 32 字节，无需 XOR 变换
  • 修改 short_channel_id.go — Setu 模式下 ShortChannelID 使用 ObjectID（32 字节）。路由协议消息中的编码需扩展为变长或使用 TLV 扩展字段承载完整 ObjectID
  • 更新 channel.go — FundingOutpoint 字段改为 chaintype.ChannelPoint，数据库 schema 需支持 Bitcoin OutPoint 和 Setu ObjectID 两种格式的序列化
  • 修改 channel_edge_info.go — BitcoinKey1Bytes/BitcoinKey2Bytes 重命名为 ChainKey1Bytes/ChainKey2Bytes，或保留 Bitcoin 字段并新增 SetuKey1Bytes/SetuKey2Bytes

8. 通道状态机适配

channel.go（10185 行）的改造策略是分离协议逻辑与链上操作：

  • 提取接口 CommitmentBuilder：Bitcoin 实现构建 wire.MsgTx 承诺交易，Setu 实现构建 ProgramTx 状态更新
  • 提取接口 ScriptEngine：Bitcoin 实现使用 txscript 验证/构建脚本，Setu 实现使用 10 操作码解释器
  • 修改 commitment.go — CommitmentKeyRing 的密钥衍生保留通用逻辑，签名/验证委托给 Signer 接口
  • 保留状态编号（StateNum）、HTLC 管理（UpdateLog）、撤销密钥交换（shachain）的核心来协议逻辑不变

9. 资金管理器适配

修改 manager.go：

  • waitForFundingConfirmation — Setu 模式下等待 DAG 最终确定（1 次确认），大幅缩短超时
  • 资金交易构建从 chanfunding.WalletAssembler（UTXO 选择）切换到新的 chanfunding.SetuAssembler（直接创建 Channel Object + 余额锁定）
  • ShortChannelID 生成逻辑：Bitcoin 等待在区块中确认后编码位置；Setu 在对象创建最终确定后使用 ObjectID

10. 合约裁决适配

修改 contractcourt 所有 resolver：

  • commitSweepResolver — Setu: 调用 Channel Object 的 claim_local_balance 入口
  • htlcTimeoutResolver — Setu: 调用 HTLC 的 timeout_claim 入口（等待 epoch 到期）
  • htlcSuccessResolver — Setu: 调用 HTLC 的 preimage_claim 入口
  • breachArbitrator — Setu: 调用 Channel Object 的 penalize 入口（提交撤销密钥 + 旧状态证明）
  • anchorResolver — Setu: 不需要（DAG 无需费率提升机制）
  • 修改 channel_arbitrator.go 检测对象状态变更而非 UTXO 花费

11. Sweep 模块简化

在 sweep 中新增 Setu 模式：

  • 移除 Bitcoin 特有的交易构建 (wire.NewMsgTx)、权重估算、RBF/CPFP 逻辑
  • Setu 上的"扫回"简化为：调用 Channel Object 的 withdraw 函数将余额转回个人账户
  • FeeRate 从 SatPerKWeight 改为 chaintype.FeeRate（Setu: gas price）
  • 批量聚合优化在 Setu 上用处不大（每次调用成本低于 Bitcoin TX）

12. 图与发现适配

  • 修改 builder.go — 通道存活性检查：Bitcoin 检查 UTXO 集合；Setu 查询 Channel Object 是否仍存在于状态树（SMT 查询）
  • 修改 gossiper.go — 通道验证：Bitcoin 验证链上 2-of-2 多签脚本；Setu 验证 Channel Object 存在 + 双方 key 匹配 + SMT Merkle 证明
  • chanvalidate/ 新增 Setu 验证逻辑

13. 费率体系适配

  • 在 chainfee 中新增 SetuEstimator 实现 Estimator 接口
  • Bitcoin: EstimateFeePerKW(numBlocks) → Setu: EstimateGasPrice(priority)
  • 修改 rates.go — 新增 GasPrice 类型和转换方法
  • 移除 Setu 模式下的 dust 限制检查（账户模型无 dust 概念）

14. RPC 与发票适配

  • 修改 rpcserver.go 中的 GetInfo — 根据 ChainType 返回 "bitcoin" 或 "setu"
  • 钱包 RPC（SendCoins、NewAddress、ListUnspent）需按链类型调度
  • 修改 zpay32 — 新增 Setu HRP（如 lnst 主网、lnsts 测试网）
  • 金额单位在 proto 定义中保持为最小单位整数，由客户端解释

15. 配置与启动

  • 修改 config.go — 新增 Setu *lncfg.Chain、SetuMode *lncfg.SetuNode
  • 新增 lncfg/setu.go — Setu 节点配置（RPC 地址、SDK 路径等）
  • 修改 config_builder.go — BuildChainControl 新增 Setu 分支
  • 修改 server.go — 根据链类型初始化对应子系统

3. Setu 链必须支持的完整能力清单

P0 — 核心能力（无此能力则无法运行闪电网络）

#能力详细需求对应 LND 模块
1可编程交易 (ProgramTx)10 操作码解释器需支持：条件分支、哈希比较、签名验证、epoch 比较、状态读写input/setu_programs.go
2共享对象 (Shared Object)Channel Object 需双方都能操作；状态更新需双方签名授权lnwallet/setuwallet/
3哈希锁 (Hashlock)BinOp 操作码需支持 SHA256，Cmp 需支持字节数组/哈希比较HTLC 合约
4Epoch 级时间查询LoadInput 能加载当前 epoch 编号，合约可据此做时间锁判断CSV/CLTV 等价
5对象版本/序列号Channel Object 需有单调递增的 state_num，防止旧状态重放承诺交易序号
6事件订阅 API按 ObjectID 订阅状态变更事件（创建、更新、销毁）；epoch 推进事件chainntnfs/setunotify/
7最终性通知交易提交后能回调通知最终确定状态manager.go 确认流程
8多签名验证ProgramTx 中能验证 2-of-2 签名（secp256k1 ECDSA 或 Ed25519）资金输出 2-of-2
9对象查询 API按 ObjectID 查询完整对象状态（余额、密钥、HTLC 列表等）BlockChainIO 等价
10原子性状态更新合约执行的状态变更要么全部生效、要么全部回滚通道状态一致性
11密钥管理 SDKGo SDK 支持 secp256k1 和 Ed25519 密钥对生成、HD 衍生、签名、验证keychain
12交易构建与广播 SDKGo SDK 支持编程构建 ProgramTx、签名、提交到网络lnwallet/setuwallet/

P1 — 重要能力（影响安全性和可扩展性）

#能力详细需求对应 LND 模块
13Merkle 证明 (SMT Proof)提供对象存在性/不存在性的 Binary+Sparse Merkle Tree 证明discovery 通道验证
14历史状态查询按 epoch 查询 Channel Object 的历史状态（用于争议仲裁）contractcourt
15Gas 估算 API估算 ProgramTx 执行的 gas 消耗chainfee/
16批量操作单笔交易中原子性地操作多个对象（批量 HTLC 结算）sweep 批量处理
17对象销毁通知Channel Object 被销毁时（通道关闭）生成可订阅事件builder.go 通道存活性
18节点发现/P2PSetu 网络节点的 P2P 连接信息（用于 LN gossip 引导）chainreg DNS 种子

P2 — 优化能力（提升性能和用户体验）

#能力详细需求
19轻客户端模式类似 Neutrino 的 Setu 轻节点（仅验证 Merkle 证明，不存全量状态）
20Watchtower 支持第三方可监控 Channel Object 状态并在违约时自动提交惩罚交易
21原子跨链操作支持 Bitcoin↔Setu 的原子交换/跨链 HTLC（如果需要双链互操作）

4. 验证

  • 单元测试: 每个新增的 Setu 实现（setunotify/、setuwallet/、setu_programs.go）独立测试，mock Setu SDK
  • 集成测试: 修改 itest 框架，新增 Setu devnet backend，覆盖核心场景：
    • 开通道 → 发送支付 → 多跳转发 → 协作关闭
    • 单方面关闭 → HTLC 超时/成功解析
    • 违约检测 → 惩罚交易
    • 双链模式：Bitcoin 和 Setu 通道共存
  • 命令: make itest backend=setu 或 go test -tags setu [lnd](http://_vscodecontentref_/118).
  • 手动检查: lncli --chain=setu getinfo、lncli --chain=setu openchannel

5. 决策记录

  • 密码学: 双支持 secp256k1 + Ed25519（同 Sui），keychain 需扩展双路径衍生
  • 双链支持: 保留 Bitcoin，通过接口抽象 + ChainControl 调度同时支持 Setu
  • 合约语言: Setu 自定义 10 操作码解释器（ProgramTx），非 Move/EVM — 需精心设计操作码序列实现 HTLC/时间锁/撤销逻辑
  • 通道 ID: Setu 上使用 32 字节 ObjectID 直接标识通道，路由协议消息中通过 TLV 扩展承载