lncli wallet labeltx：给闪电钱包交易打标签的三条硬规则

一、为什么闪电钱包需要标签

闪电节点的链上钱包通常很安静：不开太多通道时，一年也就几十笔链上进出——开通道出资、强制关闭回收、扫零钱。时间一长，光靠 txid 和金额完全分不出哪笔对应哪个事件。LND 在 walletkit 里放了 LabelTransaction，命令行入口 lncli wallet labeltx，作用就是给一笔钱包交易钉一条人类可读备注，让 wallet transactions 一类列表命令能把这笔等于三月那次被动强关的对应关系带出来。

二、接口定义的三条硬规则

按 v0.19.0-beta 的 walletkit.proto 逐条核对。第一，标签不能为空，长度上限 500 字符——这是接口层固定约束，超限直接报错，不存在截断保存。第二，幂等保护：目标交易已有标签时，不带 overwrite 的调用会失败而不是静默追加；显式带覆盖参数后旧标签被整体替换，不做合并、不保留历史版本。第三，txid 的书写姿势：注释专门提醒走 gRPC 直调时 txid 是 bytes 字段、必须按小端反向顺序编码——同一串十六进制在命令行与 gRPC 两个通道里指向不同交易，这是脚本对接最高频的翻车点；用 lncli 则没有这个问题，命令行按标准显示端序传参即可。

三、标签长在哪一层

从相邻接口能看清这套标签的落点：SendOutputs 的请求里就有可选 label 字段、同样限 500 字符，扫币等发起路径可以在创建交易时顺手写备注；LabelTransaction 负责补写——发起时忘了写，事后还能对没有标签的交易追补，或经确认后覆盖旧的。标签属于 LND 本地数据库的记账字段：区块里没有它，其他节点的数据库里没有它，也不会随任何 P2P 消息外发。这带来两面：合规导出时要走 LND 自己的接口、区块浏览器上看不到备注；另一面是账目隐私完全留在自己机器上。

四、和核心版标签体系的差异

比特币核心的标签体系以地址为主体：setlabel 给地址挂备注，对账命令按标签聚合收支。LND 的 labeltx 把标签挂在交易上，配合交易列表按笔查看。两个体系在各自钱包内自成闭环，不互通也不冲突：同一笔链上交易可能在核心节点钱包里挂着地址标签、在 LND 里挂着交易标签，各自记账。混合部署做账时，建议统一以 txid 为主键、标签只作辅助文本，别试图把两层标签机械对齐。

五、实操词表与批量补标技巧

稳定的标签词表比临场发挥重要。可行的最小约定是事件类型加日期加对象，例如 force-close-2026-08-12-nodeX、channel-open、sweep 加日期，全部小写、连字符分隔、不含引号与换行——标签是纯文本，字段本身不做命令转义，混进引号或换行会把按行解析的下游脚本弄坏。批量补标时可以利用失败语义做保护：先全部不带 overwrite 跑一遍，失败的集合恰好是已有标签的交易，人工复核后再决定哪些值得覆盖，把幂等保护反过来当审计清单用。500 字符足够放一段工单号或内部凭证号，但完整 JSON 别塞进去——它是备注栏，不是数据库。

六、边界提醒

标签不参与选币、不影响任何链上动作，删改随时安全。真正要留心的是拿标签当唯一检索键的脚本：wallet removetx 处理未确认交易时，整条交易记账连同标签一起移除，重播交易后标签需要重新打。对账日志里同一笔交易的标签反复变或凭空消失，多半就是这类删除重建循环的足迹，而不是数据库被动了手脚。另外标签不构成任何查询索引，跨库检索请始终以 txid 与高度为条件，标签只用于人眼。

风险提示：本文仅作机制说明，不构成投资建议。