路由节点的流水账：转发历史的 40 字节口径、分页与按时间删除

路由节点每天经手别人的付款，账本记在哪、能记多久、怎么合法地删，是运营者迟早要回答的问题。LND 把这笔账叫 forwarding history（转发历史）：每一笔成功转发的 HTLC 落一条记录。围绕它有查询、字段口径、按时间删除三块内容，接口定义里都写得明明白白。

一、一条记录里到底有什么

转发事件的消息定义列出了全部字段：完成时间（同时给了秒和纳秒两种精度，旧的秒字段已标记弃用）、进/出两侧通道标识（用 64 位整数的短格式 channel ID 表达，工具展示时常转成 x-y-z 格式）、进/出金额与所携费用（各有聪与毫秒两个口径，费用本身就是进额减出额）、进/出 HTLC 标识（可选字段，官方注释明确说早于 v0.20 的历史事件没有这一项，字段有无本身就是数据年龄的指纹）。还有一对可选的对端别名：查询请求里显式打开 peer alias 查找开关后，记录会带上进出两侧的别名，方便对照日志，代价是要多做身份解析。

二、查询接口的分页口径

ForwardingHistory 查询的注释直接给出算法约束：每条事件固定 40 字节，gRPC 单条消息上限 4 MiB，因此单次响应最多约 5 万条；不指定数量上限时默认只回 100 条。分页靠”索引偏移”完成——响应会带回最后一条的偏移量，下一次请求把它传进去就能续读。时间范围用起止时间圈定，还支持按进/出通道标识过滤，做单通道收益统计时用这组过滤器比拉全表再筛省资源得多。这套口径也解释了为什么不同报表工具对同一台节点的”历史总条数”会不一致：有的只翻了第一页，有的把 100 条默认值当成了全量。

三、删除：为数据保留策略准备的接口

DeleteForwardingHistory 的官方注释说明其动机是实现数据保留策略、服务隐私目的：删除时间戳不晚于给定截止点的事件，支持两种指定方式——绝对 Unix 秒，或 -30d、-24h 这样的相对时长字符串（日按 30.44 天、年按 365.25 天折算）。响应里带两个重要数字：删除条数，以及被删事件累计赚取的费用（毫秒口径，注释注明用于账务核对）。实现按批删除并保证事务安全，避免长时间锁库。这里有一条不可越界的纪律：先对账再删除。被删掉的记录无法恢复，税务或分成结算需要的费用汇总，务必先落盘再执行删除；删除也不影响钱包余额与通道状态，它只是事件日志上的剪刀。

四、把记录用于运营

转发历史是路由收入的事实底座：按天聚合 fee 字段可以画出收入曲线，按通道对聚合能看出哪些边在干活、哪些边纯占资金，配合金额分布还能判断节点更像”过路枢纽”还是”边缘代收”。需要长期留存原始事件流的运营者不应依赖这张表本身——它有自己的容量与保留策略，更稳妥的路径是订阅事件流写入外部数据库，让节点内的历史只当热缓存。最后提醒口径一致性：聪与毫秒两个口径混用会引入舍入误差，做费用审计时全程锁定同一口径，再和链上结算对账。

风险提示：转发数据涉及经营记录，删除前请确认合规保留义务，本文不构成任何财税建议。

五、一份运营者检查清单

把本文压缩成可执行的五条：查询用起止时间加索引偏移翻页，确认拿到全量再统计；金额与费用全程锁定同一口径；按通道对聚合前先弄清字段里进额与出额的符号方向；需要长期留存的报表先导出再删除；删除前先核对费用合计字段与自有账本一致。这五条都不依赖任何第三方工具的文档，全部落在官方接口定义的字段与注释范围内，升级版本时只需复查接口定义有无变动，不必重写整套统计逻辑。