lnd v0.21.0 RC 测试指南模板全解：固定章节契约、确定性 Pass/Fail 信号与实战编写规范

区块链【免费下载链接】lndLightning Network Daemon ⚡️项目地址https://gitcode.com/gh_mirrors/ln/lnd点击查看免费下载本文以 docs/testing-guides/v0.21.0/_template.md 为主体系统拆解 lnd 发布候选RC测试指南模板的设计意图、章节结构与编写纪律。读者将掌握如何为 v0.21.0 的某个功能或高风险回归面创建一份结构合规、可被人类测试者与自动化 Agent 一致执行、且每一步都带可验证信号精确 RPC 字段值、日志行、退出码的测试指南并以仓库中 10 份已完成指南如 payment-rpcs.md、rbf-taproot-coop-close.md为现实范本。一、模板的定位一份人机共用的 RC 测试契约在 v0.21.0 发布候选期间lnd 维护团队在docs/testing-guides/v0.21.0/目录下为每个需要重点验证的功能或高风险回归面建立独立测试指南。目录入口 README.md 明确了使用方式人类测试者选择与自己关心的功能面匹配的指南按场景逐条执行将结果回报到 RC 讨论帖或针对发现的回归问题提交 issue自动化 Agent固定章节顺序本身就是契约。每份指南按同一布局书写Agent 依靠固定布局导航每个场景末尾的 Pass/Fail 信号行是自动化验证的最终目标。模板开头的注释HTML 注释块写明了这一流程Copy it tofeature-slug.mdin this directory and fill in every section. Keep the section order and headings exactly as written below. Agents (and human reviewers) rely on the fixed layout to navigate the guides.也就是说模板的使用方式是复制_template.md为feature-slug.md逐节填写保持章节顺序与标题完全不变如果某个章节确实不适用写n/a而不是删掉标题。README 的 Authoring new guides 一节也重申了这一点并要求在目录表中新增一行条目。二、元数据头让风险与受众在一行内可判读每份指南的 H1 之下是一组结构化的元数据行模板规定了字段与取值字段取值示例含义PRs#10063, #10763关联的 GitHub Pull Request 编号用于绝对引用禁止用 the new feature 这类模糊指代Riskheadline/high-regression/new-rpc/operator-feature风险等级分类Audiencenode operators/RPC clients/LSPs/wallet integrators适用人群Backends affectedbbolt/sqlite/postgres/all受影响的后端存储Networksregtest/signet/testnet/mainnet适用的测试网络以实际指南为证payment-rpcs.md 的元数据头为**Risk:** new-rpc、**Audience:** RPC clients, routing nodes, MuSig2 coordinator integrators, LSPs、**Backends affected:** all、**Networks:** regtest (primary)而 closed-channel-tombstone.md 则标记为**Risk:** high-regression (one-way upgrade)、**Backends affected:** sqlite, postgres (kvdb-on-SQL schema)——一眼即可判断该指南的风险性质是升级后不可回退读者在动手前就能建立风险预期。三、模板正文的八大章节契约模板固定了八个正文章节这是整份模板的骨架。下面逐一拆解其编写要求并给出仓库中的真实范例。3.1 What this feature does功能做什么要求13 句平实英文描述禁止营销语言只讲可观察行为的变化不描述内部重构。范例closed-channel-tombstone.md 用两段话讲清了行为变化v0.21.0 之前在CloseChannel关闭事务中执行单次DeleteNestedBucket在 kvdb-on-SQL schemasqlite/postgres上会扇形展开为逐行的ON DELETE CASCADE在拥有数百万状态的通道上会长时间持有数据库写锁进而阻塞 HTLC 转发、超时htlcswitch重试并触发相邻通道的强制关闭v0.21.0 改为跳过级联删除以 outpoint 索引翻转作为权威的通道已关闭标记。3.2 Why it matters / what could break为什么重要 / 可能坏在哪要求列出具体的失败模式模板给出的示范句式是If X is wrong, channel force-closes.X 出错 → 通道被强制关闭If Y is wrong, payments stall inIN_FLIGHT.Y 出错 → 支付卡死在 IN_FLIGHTIf Z is wrong, the node refuses to start after upgrade.Z 出错 → 升级后节点拒绝启动范例rbf-taproot-coop-close.md 的风险清单非常典型跨 RBF 轮次的 nonce 复用是硬性 MuSig2 违规——一旦发生签名可被伪造务必盯住JIT nonce 顺序回归会表现为反复的ClosingComplete往返却始终产不出可确认的交易taproot-overlay 通道误入 RBF 流程会触发 nil 指针解引用或 aux-close 构建失败。3.3 Prerequisites前置条件要求逐项声明并把后面 Setup / Scenarios 中使用的每个 shell 变量都在此定义$ALICE_RPC、$BOB_PUBKEY等占位变量。模板规定的内容清单lnd buildv0.21.0-beta.rc1 or newer注明构建标签Backendbitcoind/btcd/neutrinoNetwork除非特别说明一律 regtestPeersN 个节点Alice、Bob、Carol说明场景开始时的通道与余额状态Config flags以protocol.option-namevalue、db.option-namevalue形式给出Toolslncli、bitcoin-cli、jq等Shell 变量定义块。范例production-taproot-channels.md 给出了完整的变量块这是全仓库指南的标准形态ALICE_RPClocalhost:10001 BOB_RPClocalhost:10002 ALICE_MAC~/.alice/data/chain/bitcoin/regtest/admin.macaroon BOB_MAC~/.bob/data/chain/bitcoin/regtest/admin.macaroon ALICE_DIR~/.alice BOB_DIR~/.bob LNCLI_Alncli --rpcserver$ALICE_RPC --macaroonpath$ALICE_MAC --lnddir$ALICE_DIR LNCLI_Blncli --rpcserver$BOB_RPC --macaroonpath$BOB_MAC --lnddir$BOB_DIR并把节点启动的最小配置一并给出protocol.simple-taproot-chans13.4 Setup环境搭建要求编号的、可直接复制粘贴的步骤带读者从全新节点走到场景起始状态并且以一个输出能证明搭建成功的命令收尾。模板给出了示范结构# 1. Start nodes ... # 2. Fund Alice ... # 3. Open Alice→Bob channel ... # Setup verification: lncli --rpcserver$ALICE_RPC listchannels | jq .channels | length # Expected: 1范例production-taproot-channels.md 的 Setup 完整覆盖了启动 regtest 并挖矿 → 以--protocol.simple-taproot-chans启动 Alice/Bob → 连接对端 → 给 Alice 链上钱包打钱并以一条带期望输出的命令收尾# Setup verification: $LNCLI_A walletbalance | jq .confirmed_balance # Expected: 100000000 (1 BTC in sats)3.5 Scenarios场景这是模板的核心模板规定25 个场景且必须覆盖至少一个 happy path、一个 edge case、一个 negative-path / 错误配置场景。每个场景采用固定小节结构### S1: short scenario name — happy pathS 编号 短名 路径类型标签Goal本场景要证明什么Steps可复制粘贴的 bash 命令块Expected具体可观察结果RPC 字段某值、日志包含某行等Pass/Fail signalPASS 条件 FAIL 条件是自动化验证目标。范例一happy pathproduction-taproot-channels.md 的 S1 验证打开taproot-final通道后报告SIMPLE_TAPROOT_FINAL承诺类型其信号是$LNCLI_A listchannels | \ jq .channels[] | select(.remote_pubkey$BOB_PUB) | .commitment_typePASSif 输出为SIMPLE_TAPROOT_FINALFAILif 输出为SIMPLE_TAPROOTstaging、ANCHORS或任何其他值——意味着协商回退到了错误类型。范例二negative-pathonion-messaging.md 的 S6 专测启动期拒绝非法限流配置无需任何驱动节点直接逐项启动并抓退出码ConfigExpected to reject?peer-kbps0,peer-burst-bytes262144yes (rate 0, burst 0)peer-kbps100,peer-burst-bytes0yes (rate 0, burst 0)peer-kbps100,peer-burst-bytes32768yes (burst 65535)peer-kbps0,peer-burst-bytes0no (cleanly disabled)PASSif 三个拒绝行在 gRPC 端点启动前就以明确报错退出、禁用行正常启动FAILif 任一非法配置被静默接受或禁用配置反而报错。范例三edge case 回归面rbf-taproot-coop-close.md 的 S2 验证 RBF 加价第二轮必须同时满足三个条件——新 txid$TXID2 ! $TXID1、更高费率$FEE2 $FEE1、不同的 MuSig2 nonce在 Bob 日志中确认NextCloseeNonce与上一轮不同并把nonce 复用明确标注为必须抓到的关键 bug。3.6 Failure investigation失败排查指引要求给出场景失败时的第一排查路径模板固定三块Logs可用的 grep 命令如grep -i keyword ~/.lnd/logs/bitcoin/mainnet/lnd.log以及建议开到debug的子系统列表如SUBSYSTEM_1、SUBSYSTEM_2RPCs to query for state用lncli command查什么、什么值代表 bugCommon bugs / prior regressions简要指针最好带 PR / issue 编号。范例closed-channel-tombstone.md 的排查节给出了子系统清单LNDB,CRTR,HSWC,RPCS、关键日志行tombstoning channel、db write took NNms警告、outpointClosed索引翻转并给出反查方法如果 S2 报告已关闭通道仍显示为 open就去搜索openChannelBucket的所有读取方找出未查询outpointIndex的路径——bug 就在那里。其 SQL 直接检查命令也原样继承SELECT * FROM chain_params;出自 chain-params-guard.md 的排查节。3.7 Related itests关联集成测试要求指向覆盖同一代码路径的 itest 用例格式为itest/lnd_area_test.go::TestName。模板强调它们不是手动场景的替代品而是可执行的参考。仓库中的实际引用示例onion-messaging.mditest/lnd_onion_message_test.gotestOnionMessage、itest/lnd_onion_message_forward_test.gotestOnionMessageForwarding含buildForwardNextNodePath、buildForwardSCIDPath、buildConcatenatedPath、itest/config_onion_ratelimit_test.go限流配置、onionmessage/test_utils.goBuildOnionMessage辅助函数payment-sql-migration.mdpayments/db/migration1/sql_migration_test.go迁移单元/集成测试、itest/lnd_payment_test.go端到端支付行为production-taproot-channels.mditest/lnd_open_channel_test.gotaproot 开通道路径、itest/lnd_taproot_test.gotaproot 专属 HTLC 与关闭流程、itest/lnd_channel_force_close_test.gotaproot 强制关闭。3.8 Out of scope范围外要求明确本指南不测什么防止范围蔓延并引导测试者去正确的指南。模板给出的写法是什么不做 指向哪份指南。范例payment-rpcs.md 的 Out of scope 为Payment SQL migration——单独指南payment-sql-migration.mdBOLT-12 / offers——不在 v0.21.0 中多输入EstimateFee的性能特性。四、模板注释里的四条硬性样式纪律模板顶部 HTML 注释块虽然不渲染但它是规范本体定义了四条编写纪律这四条正是模板的灵魂Pass/Fail 信号必须确定性必须是精确的 RPC 字段值、精确的日志行必要时用正则、退出码或通过具体命令可观察的状态。Should succeed 不是信号。Setup 块必须可直接复制粘贴使用占位变量$ALICE_RPC、$BOB_PUBKEY等并在 Prerequisites 中定义全部占位变量。优先 regtest / signet而非 mainnet如果 mainnet 是唯一有意义的测试面必须明说并标注风险。使用绝对引用PR 编号、文件路径、RPC 方法名而不是the new feature或this change。五、从模板到成文仓库中的真实对照模板并非孤立存在。docs/testing-guides/v0.21.0/目录下 10 份指南全部遵循同一骨架且与模板的各个细节一一对应构成模板 → 实例的完整学习闭环。按其风险排序与 README 表格一致Headline features主推功能风险最高排在最前production-taproot-channels.md——特性位 80/81 的生产版简单 taproot 通道、优化承诺脚本OP_CHECKSIGVERIFY替代OP_CHECKSIGOP_DROP、按 funding TXID 键控的 MuSig2 nonce 映射编码rbf-taproot-coop-close.md——taproot 通道的 RBF 协作关闭、MuSig2 JIT nonce、nonce 复用防护、--protocol.rbf-coop-closepayment-sql-migration.md——--db.use-native-sql节点的支付存储 KV→SQL 自动迁移bbolt 用户必须先经lndinitonion-messaging.md——洋葱消息转发、寻路、逐 peer / 全局限流器、通道在场门控channel-presence gate。High-risk regressions高风险回归与破坏性变更5. closed-channel-tombstone.md——KV-over-SQL 后端上的单向升级陷阱降级后已关闭通道会复活为开放状态 6. reorg-safe-closes.md——关闭需 3–6 个按容量缩放的确认为前提MinCLTVDelta由 18 提至 24对自定义 CLTV 发票是破坏性变更 7. chain-params-guard.md——native-SQL 节点检测到数据库曾在不同网络使用则拒绝启动 8. getdebuginfo-log-optin.md——GetDebugInfo日志字段改为 opt-in客户端不传include_logtrue将拿不到日志。New RPCs / operator features新 RPC 与运维特性9. payment-rpcs.md——五个小而独立的 RPC 变更DeleteForwardingHistory截止时间戳必须至少 1 小时以前、MuSig2RegisterCombinedNonce/MuSig2GetCombinedNonce仅 MuSig2 v1.0.0rc2、EstimateFee新增inputs字段与lncli estimatefee --utxos、HTLC 事件订阅的发票级失败明细、SubscribeChannelEvents新增 update 事件 10. middleware-multiple-readonly.md——多个只读 RPC 中间件拦截器可同时注册。其中 onion-messaging.md 还示范了指南引用设计文档的协作模式其开头明确要求先读 docs/onion_message_rate_limiting.md限流设计文档指南只测该文档描述的可观察运维行为。同理production-taproot-channels.md 在 S4 中引用 docs/zero_conf_channels.md 说明 zero-conf 与 SCID-alias 所需的--protocol.*旗标。这意味着写新指南时若功能有配套设计文档应在指南中建立指向关系。六、编写一份新指南的完整操作流综合模板、README 与上述实例为 v0.21.0 新增一份指南的步骤为复制模板将_template.md复制为feature-slug.md同一目录下填写元数据头确认 PR 编号、风险等级、受众、受影响后端、测试网络按固定顺序逐节填写What it does → Why it matters → Prerequisites含全部 shell 变量定义→ Setup以证明命令收尾→ 25 个场景覆盖 happy path / edge case / negative-path→ Failure investigation → Related itests → Out of scope逐条核对信号确定性每个场景的 Pass/Fail 必须是精确 RPC 字段值、精确日志行或退出码杜绝 should succeed不适用章节写n/a不要删除标题在 README.md 的指南表中新增一行并按风险排序插入正确位置若涉及新 RPC 或 proto 字段先在lnrpc/routerrpc/router.proto、lnrpc/signrpc/signer.proto、lnrpc/lightning.proto等 proto 源中核对字段名与调用参数payment-rpcs.md 的 Failure investigation 一节即为范例避免以错误的字段名记录 FAIL。对于自动化 Agent 而言README 的表述可以视作执行规范固定章节顺序是契约每个场景的 Pass/Fail 信号行是验证目标——Agent 只需定位到该行、执行其命令、比对输出即可对 RC 功能完成确定性验证。七、实战要点总结模板是内容少于结构的元文档它的价值在于固化结构与纪律而非提供功能内容照搬模板本身没有意义按章节填充具体功能事实才有意义。信号确定性是最高优先级一份指南如果某个场景只有应当成功而没有精确比对项对 Agent 就是不可执行的。绝对引用贯穿全文PR 编号、RPC 方法名、文件路径、proto 字段名均可作为验证锚点这在 payment-rpcs.md 中体现得尤为彻底五个 RPC 各带 PR 号。风险导向的目录排序headline 功能排最前高风险回归次之新 RPC/运维特性殿后新增指南需按风险插入而非追加在末尾。边界意识Out of scope 与 Related itests 两节共同约束指南的测试面与佐证面防止范围蔓延也防止重复劳动——例如 RBF 协作关闭与普通协作关闭互相引用避免了同一场景在两份指南中重复出现。赞分享区块链【免费下载链接】lndLightning Network Daemon ⚡️项目地址https://gitcode.com/gh_mirrors/ln/lnd点击查看免费下载相关推荐PTO-ISA 指令契约模板Appendix B实战指南为 Ascend PTO 每条指令编写规范文档的章节结构与规范性要求PTO ISA 指令契约模板Appendix B实战指南为 Ascend PTO 每条指令编写规范文档的章节结构与规范性要求 导读 本文面向在 CANN/算子库人工智能CANNlnd 开发指南代码规范、测试流程与 Git 提交约定实战详解lnd 开发指南代码规范、测试流程与 Git 提交约定实战详解 本文是 lndLightning Network Daemon仓库内 docs/devel区块链graphify extraction-spec 详解语义提取子代理的 Prompt 契约与确定性节点 ID 规范graphify extraction spec 详解语义提取子代理的 Prompt 契约与确定性节点 ID 规范 本文围绕 extraction spec.人工智能知识图谱RAGAI 技能开发工具MCP 服务上一篇显卡驱动彻底清理终极指南Display Driver Uninstaller 完整使用教程下一篇GetQzonehistory数字记忆的时光穿梭机一键归档你的QQ空间青春足迹创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考