上个月帮朋友排查一个TRC20收款系统的故障现象很典型用户拿着转账成功的截图来催单订单状态却一直停在待支付。客服手工去链上核对记录确实存在金额也对但系统就是没认。顺着日志往回翻发现监听器在节点抖动的几分钟里跳过了两个区块而补偿任务只扫最近十个块中间那段刚好成了盲区。这件事让我意识到TRC20收款系统的开发链条虽然不长——区块监听、交易确认、回调机制三件事——但每一环都有需要自己拿主意的地方选错一个细节后面就是无穷无尽的用户说付了、系统说没收到的工单。这篇内容想聊的就是这三件事怎么落地。适合已经能跑通基础RPC调用、准备把收款功能真正推到线上的开发者也适合接手了一个半成品系统、正被各种边角情况折磨的同学。我不会只给一段查询事件然后比对地址的示例代码而是把每个环节里那些文档上不写、但踩过的人都知道的取舍讲清楚包括确认数怎么定、游标怎么存、回调怎么做幂等、对账怎么兜底。1. 把到账这件事拆开TRC20收款链路真实长什么样1.1 一笔TRC20转账在链上留下的痕迹很多人对收款系统的第一印象是监听转账这个说法不太准确。TRC20代币并不是原生资产它本质上是某个智能合约内部维护的一张余额映射表。用户点转账的时候做的是一次合约调用合约把发送方那一栏的数字减掉把接收方那一栏的数字加上然后抛出一个事件日志作为凭证。整个过程里没有任何币在地址之间移动你要找的只是这张表被修改的证据。这个认知很重要因为它决定了你能观察到什么。你能看到的只有三样东西交易本身谁发起的、调用了哪个合约、带了多少参数、交易执行产生的日志事件、以及合约当前的余额查询结果。反过来你看不到的东西也很多看不到用户的意图看不到交易所内部的归集动作看不到某笔转账背后是不是有另一个系统在做批量分发。所以一套收款系统的核心工作就是把链上发生了事件翻译成业务上这笔订单收到了钱。中间要跨越三道坎第一道是发现也就是区块监听你得知道链上出现了哪些新交易第二道是判定也就是交易确认你得确定这笔交易不会被回滚、金额和收款地址都对得上第三道是通知也就是回调机制你得把这个结论可靠地告诉订单系统而且只告诉一次。1.2 收款系统必须自己回答的四个问题在动手写代码之前有几个问题必须先有明确答案否则写到一半一定会返工。第一个问题是监听范围。是只监听某一个代币合约还是监听所有合约只监听固定收款地址还是监听所有转入答案通常取决于业务形态如果你只收一种稳定币那只监听这个合约就够了如果你要支持多种代币就得维护一张合约白名单并且每个合约的小数位数、事件签名可能都不一样。第二个问题是什么时候算到账。是交易一进块就算还是等若干个确认这个数字直接决定了资金风险敞口和用户体验之间的平衡点。等得太少遇到链上回滚或者极端情况会出问题等得太多用户付款后要盯着页面转圈。第三个问题是通知语义。回调是尽力而为还是至少一次链上事件是事实但网络请求不是回调失败是常态。系统必须接受同一笔交易可能被通知多次这个前提然后在接收方做幂等。第四个问题是漏了怎么办。任何监听系统都会有漏块、宕机、节点不可用的时刻必须有一个独立于实时链路的补偿机制定期回扫历史区间把断档补上。这四个问题如果没有提前想清楚后面每个功能都会变成临时打补丁。关键决策常见选项影响监听范围单合约 单地址 / 多合约 多地址决定解析复杂度与白名单维护成本确认数1 块 / 19 块 / 自定义阈值决定资金风险与到账延迟回调语义至多一次 / 至少一次决定是否需要幂等表补偿策略定时回扫 / 手动触发决定故障恢复能力2. 区块监听轮询、事件查询和节点推送怎么选2.1 全量拉块的笨办法反而是最可靠的基线监听链上数据有三条主流路径按块号全量拉取、按合约事件查询、以及订阅节点推送。三条路各有各的适用场景我建议先用最笨的那条把系统跑通再考虑优化。全量拉块的逻辑很直白从游标记录的上次扫描高度开始逐块调用获取区块详情的接口拿到块里的交易列表再针对每笔交易查询执行回执从回执的日志里筛出目标合约的Transfer事件。这个方案的优点是语义最完整——你不仅能看到成功的事件还能看到失败的交易能看到块时间戳、块内交易顺序排查问题时信息量充足。缺点也很明显每个块可能包含几十到上百笔交易逐笔查回执会让RPC调用量成倍增长节点扛不住你自己也扛不住。实际落地时一般会做一层优化先用块里的交易列表做粗筛只对调用了目标合约的交易去查回执。这样能把大部分无关交易挡在外面。如果业务量不大这个方案完全够用而且它的确定性最强出问题时你手里有完整的块数据可以复现。2.2 按事件查询效率高但边界条件必须小心更常见的做法是直接查事件日志接口允许你指定合约地址、事件名、块高范围一次返回一批匹配的日志。这个方案的优势是请求次数少一批能拿回几百条记录适合交易量大的场景。但它有几个边界必须提前处理。第一是分页单次返回条数有上限块高跨度大的时候必须循环翻页直到返回为空或者条数小于上限。第二是块高范围不能太大跨度几千个块以上节点可能直接拒绝或者超时稳妥的做法是切成固定大小的窗口比如每批五百到一千个块逐窗口推进。第三是别用时间戳查询时间戳查询在跨节点时行为不完全一致边界块容易重复或遗漏用块高最稳。还有一点容易被忽略事件查询接口返回的通常是成功执行的事件但不同节点实现在极端情况下可能有细微差异。所以拿到事件之后我仍然建议对关键交易再做一次回执查询确认交易状态字段是成功这一步多花一次请求换来的是判定逻辑的确定性。2.3 事件订阅的断连、漏块和重放节点推送看起来最优雅——连上之后有新区块就推给你不用反复问。但推送通道的稳定性取决于网络和节点断线重连是家常便饭。这里最容易出问题的是重连之后的起点如果你从当前最新块开始断线期间产生的块就永久丢失了如果你从上次处理的块开始又可能重复处理一批已经处理过的数据。正确的做法是把游标持久化每次处理完一批就更新游标重连时从游标位置继续。重复的部分靠下游的唯一约束去重。另外推送通道本身不保证顺序尤其是在多实例部署时A实例收到块100B实例可能先收到块101所以处理逻辑不能假设后到的块一定更高。2.4 一个能跑的监听器骨架下面这段是我实际用过的一个简化版本思路是游标持久化加批量事件查询加地址过滤去掉业务代码之后大概长这样。import time import requests from decimal import Decimal NODE https://api.trongrid.io # 换成自己的节点地址 CONTRACT TContractAddressHere # 目标代币合约 MERCHANT TYourReceiveAddressHere # 你的收款地址 WINDOW 500 # 每批扫描的块数 DECIMALS 6 # 代币小数位 def fetch_events(from_block, to_block): 按块高窗口拉取 Transfer 事件自动翻页 url f{NODE}/v1/contracts/{CONTRACT}/events page 0 while True: params { event_name: Transfer, from_block: from_block, to_block: to_block, size: 200, page: page, } resp requests.get(url, paramsparams, timeout15) resp.raise_for_status() data resp.json().get(data, []) if not data: break for item in data: yield item page 1 def normalize(item): 把原始事件整理成业务字段注意金额用 Decimal result item.get(result, {}) return { txid: item.get(transaction_id), block_number: item.get(block_number), block_ts: item.get(block_timestamp), from_addr: result.get(from), to_addr: result.get(to), amount: Decimal(result.get(value, 0)) / (10 ** DECIMALS), } def scan_once(cursor): latest get_latest_block() start cursor while start latest: end min(start WINDOW - 1, latest) for raw in fetch_events(start, end): ev normalize(raw) if ev[to_addr] ! MERCHANT: continue # 进入确认队列不在这里直接入账 enqueue_for_confirm(ev) cursor end 1 save_cursor(cursor) # 每批都落盘别等全部跑完 start end 1 return cursor这段代码有几个点值得注意。金额必须用十进制或者整数处理浮点数在六位小数的代币上会丢精度小额入账对不上账是必然的。游标要每批落盘不能等整轮扫描结束再存否则中途挂掉就白跑了。事件进入确认队列而不是直接入账是为了把发现和判定两件事解耦后面确认逻辑可以独立演进。提示游标表的更新一定要加行锁或者用乐观锁版本号多实例时防止两个进程同时推进同一个游标导致跳块。3. 交易确认几个块才算真的到账3.1 确认数的经验值从哪来确认数的本质是在赌这笔交易所在的那个块不会被换掉。链上共识机制决定了最终一致性需要时间不同网络的出块节奏不同确认数的经验值也不同。TRC20所在的网络出块间隔大约三秒常见的经验区间是十九到二十个块折算下来一分钟左右。这个数字不是拍脑袋来的大型平台在长期运行中逐步收敛到这个量级既能覆盖绝大多数极端情况又不至于让用户等太久。当然这个值需要根据单笔金额做分层几百块的小额订单三到五个块就可以先给用户一个已确认的中间态提示上万的大额订单建议等到三十个块以上再标记为可结算。这里有个实用技巧把确认过程设计成多阶段状态而不是非黑即白的布尔值。订单可以依次经过已发现已打包确认中已确认可结算几个状态前端可以展示进度业务侧也可以根据金额自行决定在哪个状态放开权益。这样即使用户催单客服也有东西可看。3.2 交易回执里必须逐个校验的字段拿到一笔候选交易之后校验清单比想象中长。下面这几项是我踩过坑之后固定下来的检查顺序。校验项说明漏掉的后果交易状态回执里的执行结果必须是成功失败交易被当成成功入账日志合约地址事件必须来自白名单合约假币合约伪造同名事件事件签名必须是标准 Transfer 签名其他事件被误解析接收地址与订单绑定的收款地址完全一致转给同合约其他地址被误认金额精度用十进制或整数换算小额金额对不上账区块高度达到预设确认数回滚后账实不符特别说一下日志合约地址这一项。有些人写监听逻辑时只看事件名和参数不看日志是哪个合约发出来的。这种做法在早期可能没问题但一旦有人部署一个同名事件的合约往你的地址转一堆毫无价值的代币系统就会把它当成真钱入账。白名单校验是必须的而且要校验到日志级别不能只看交易调用的主合约。3.3 失败交易的花样比想象中多交易失败不等于没上链。在TRC20的场景里合约调用失败依然会消耗手续费交易记录会留在链上回执状态标记为失败事件日志通常为空。常见的失败原因包括资源不足、合约内部主动回退、参数不合法等。资源不足是最常见的一种。TRC20转账需要消耗合约执行资源如果发送方账户没有足够的资源储备交易会以失败告终。这种情况下用户那边可能看到转账失败的提示但有些钱包的提示文案不清晰用户会误以为自己付成功了。所以你的系统在收到这笔交易时必须明确判定为失败并且不产生入账同时把失败原因记录下来方便客服解释。还有一种更隐蔽的情况交易成功事件也有但事件的参数被合约做了手脚。某些非标准合约会在转账时额外扣除手续费或者把金额拆成多笔或者事件里的数值和实际余额变化不一致。对付这种情况唯一的办法是不完全信任事件对高价值订单额外做一次余额差值校验——在交易前后各查一次收款地址的余额用差值来交叉验证。3.4 金额处理的精度陷阱这个坑太常见了值得单独拎出来说。代币的金额在链上是整数单位是最小精度六位小数的代币意味着链上数值 1000000 对应实际的 1 个币。如果代码里用浮点数做除法再比较很容易出现 0.1 0.2 不等于 0.3 这类问题订单金额和实收金额差一个最小单位判定就失败了。正确做法是全程用整数或者高精度十进制类型。订单侧存储的应收金额也用最小单位整数比较的时候直接比整数展示的时候再格式化。这一条看着基础但我见过不止一个系统在金额比较上翻车最后查了半天发现是浮点误差。4. 回调机制把链上事实变成业务事实4.1 回调报文该带哪些字段回调是收款系统和业务系统之间的契约字段设计得好后面能省很多沟通成本。我习惯带上这些商户订单号、交易哈希、日志序号、实付金额、币种合约、区块高度、确认数、通知时间、以及一个签名。日志序号这个字段容易被忽略。同一笔交易里可能有多个Transfer事件比如批量转账光靠交易哈希无法定位到具体是哪一条。把交易哈希和日志序号组合成唯一键才能保证幂等判断的准确性。签名的作用是让接收方确认通知来源可信。做法很简单把关键字段按固定顺序拼接加上双方约定的密钥做一次哈希放在头部或者报文体里。接收方用同样方式计算一遍对比即可。注意拼接时字段顺序和空值处理必须严格一致否则验签会莫名其妙失败。4.2 幂等是回调设计的第一原则链上事件可能被重复处理回调请求可能超时重发业务系统可能重复消费消息。这三点叠加起来同一笔收款被通知多次几乎是必然事件。所以回调的第一原则不是保证送达而是保证重复送达不会出问题。实现方式是在接收方建一张唯一约束表主键用交易哈希加日志序号插入成功才继续处理业务逻辑插入冲突直接返回成功。这样即使通知十次业务只执行一次。发送方这边则要保证每次重试用的是完全相同的内容不要每次重新生成订单号或者时间戳否则接收方没法识别为同一条。4.3 重试策略与死信处理回调失败的原因五花八门接收方服务重启、网络抖动、证书过期、限流。发送方需要一个明确的重试策略我一般用指数退避间隔从几秒开始逐步拉长重试若干次之后转入死信队列由人工或者定时任务处理。这里有个经验重试次数不要设太多也不要设太少。太少了偶发故障就进死信运维压力大太多了会拖长整个通知链路而且对已经挂掉的服务反复请求没有意义。我的习惯是首轮快速重试三次覆盖瞬时抖动之后拉长间隔再试几次总量控制在八到十次左右超过就进死信并触发告警。死信队列必须有配套的处理界面或者脚本能看到失败的订单、失败原因、最后尝试时间并且支持手动重推。没有死信处理机制的回调系统等于把问题藏起来了。4.4 乱序和延迟先到的通知不一定先成交多实例部署时两个监听进程可能同时处理相邻区块导致通知到达业务系统的顺序和链上顺序不一致。如果业务逻辑对顺序敏感比如同一地址的多笔收款要按时间累计额度就需要在通知里带上区块高度和块内序号接收方按这个顺序做排序或者缓冲。还有一种情况是补偿任务和实时链路同时工作补偿任务扫到一笔历史交易实时链路也扫到了同一笔两条路径几乎同时发出通知。这时候幂等约束会挡住重复但要注意补偿任务发出的通知里确认数可能已经很高不要让业务侧误以为是新交易。解决办法是在报文里带上是否补偿的标记或者干脆让补偿任务也走同一个确认队列统一出口。5. 上线前必须做的对账和压测5.1 每日对账用余额快照给账本做体检再严密的监听也可能漏所以必须有一个独立于实时链路的对账任务。做法是每天固定时间查一次收款地址在合约里的余额和系统账本里累计入账金额做比对差额超过阈值就告警。对账的难点在于收款地址通常有资金转出余额不等于累计入账。解决办法是维护一张资金流水表入账和转出都记录对账时用累计入账减累计转出得到应有余额再去和链上查到的余额比较。如果差额不为零就按时间倒序逐笔核对通常能很快定位到漏掉的那笔。5.2 几个真实踩过的故障场景第一个是节点切换导致的游标回退。某次主节点不可用系统自动切到备用节点备用节点的最新块高比主节点低了几百个块监听器按备用节点的高度推进游标结果那几百个块被当成未来跳过了。修复方式是切换节点时校验新节点的块高不低于当前游标低于就等它同步上来。第二个是时间窗口查询的边界重复。早期用时间戳做补偿扫描每批的起止时间有重叠导致边界上的交易被重复处理。虽然幂等表挡住了重复入账但确认队列里堆了一堆重复任务拖慢了整体处理速度。改成块高窗口之后问题消失。第三个是回调签名因为字段顺序变化失败。业务方升级了一次接口把报文字段重新排了序签名逻辑没跟着改导致所有回调验签失败全部进了死信。这件事之后我在双方约定里加了一条签名只针对固定的核心字段新增字段不影响签名计算。5.3 值得常驻的监控指标系统跑起来之后几个指标建议做成看板常驻。扫描高度和链上最新高度的差值正常应该稳定在很小的范围持续拉大说明监听卡住了。从事件发现到确认完成的中位耗时突然变长可能是节点变慢或者队列积压。回调成功率和死信数量反映下游健康状况。每日对账差额正常情况下应该恒为零。这些指标不需要多复杂能画出趋势线就够了。真正出问题的时候趋势线比日志更快告诉你哪里不对。6. 写在最后的一点个人经验做这类系统这些年我最大的体会是链上数据是可信的但你对链上数据的理解不一定可信。监听漏块、确认数不够、事件伪造、精度误差、回调重复这些问题没有一个来自链本身全部来自实现细节。所以与其追求架构多漂亮不如把每个环节的边界条件列清楚逐条写测试用例尤其是那些正常情况下不会发生的分支。另外分享一个小习惯每次上线新版本之前我会拿历史区块做一次全量回放把过去一周的真实交易重新跑一遍对比新旧两版系统的判定结果。这个方法能在几分钟内暴露大部分逻辑改动带来的回归问题比在生产环境上观察半天有效得多。如果你们团队还没有回放环境强烈建议搭一个成本不高收益很大。 
长河君 · 2026/10/28 22:51:43 · 阅读 1.2k TRC20收款系统开发：区块监听、交易确认与回调幂等
上个月帮朋友排查一个TRC20收款系统的故障现象很典型用户拿着转账成功的截图来催单订单状态却一直停在待支付。客服手工去链上核对记录确实存在金额也对但系统就是没认。顺着日志往回翻发现监听器在节点抖动的几分钟里跳过了两个区块而补偿任务只扫最近十个块中间那段刚好成了盲区。这件事让我意识到TRC20收款系统的开发链条虽然不长——区块监听、交易确认、回调机制三件事——但每一环都有需要自己拿主意的地方选错一个细节后面就是无穷无尽的用户说付了、系统说没收到的工单。这篇内容想聊的就是这三件事怎么落地。适合已经能跑通基础RPC调用、准备把收款功能真正推到线上的开发者也适合接手了一个半成品系统、正被各种边角情况折磨的同学。我不会只给一段查询事件然后比对地址的示例代码而是把每个环节里那些文档上不写、但踩过的人都知道的取舍讲清楚包括确认数怎么定、游标怎么存、回调怎么做幂等、对账怎么兜底。1. 把到账这件事拆开TRC20收款链路真实长什么样1.1 一笔TRC20转账在链上留下的痕迹很多人对收款系统的第一印象是监听转账这个说法不太准确。TRC20代币并不是原生资产它本质上是某个智能合约内部维护的一张余额映射表。用户点转账的时候做的是一次合约调用合约把发送方那一栏的数字减掉把接收方那一栏的数字加上然后抛出一个事件日志作为凭证。整个过程里没有任何币在地址之间移动你要找的只是这张表被修改的证据。这个认知很重要因为它决定了你能观察到什么。你能看到的只有三样东西交易本身谁发起的、调用了哪个合约、带了多少参数、交易执行产生的日志事件、以及合约当前的余额查询结果。反过来你看不到的东西也很多看不到用户的意图看不到交易所内部的归集动作看不到某笔转账背后是不是有另一个系统在做批量分发。所以一套收款系统的核心工作就是把链上发生了事件翻译成业务上这笔订单收到了钱。中间要跨越三道坎第一道是发现也就是区块监听你得知道链上出现了哪些新交易第二道是判定也就是交易确认你得确定这笔交易不会被回滚、金额和收款地址都对得上第三道是通知也就是回调机制你得把这个结论可靠地告诉订单系统而且只告诉一次。1.2 收款系统必须自己回答的四个问题在动手写代码之前有几个问题必须先有明确答案否则写到一半一定会返工。第一个问题是监听范围。是只监听某一个代币合约还是监听所有合约只监听固定收款地址还是监听所有转入答案通常取决于业务形态如果你只收一种稳定币那只监听这个合约就够了如果你要支持多种代币就得维护一张合约白名单并且每个合约的小数位数、事件签名可能都不一样。第二个问题是什么时候算到账。是交易一进块就算还是等若干个确认这个数字直接决定了资金风险敞口和用户体验之间的平衡点。等得太少遇到链上回滚或者极端情况会出问题等得太多用户付款后要盯着页面转圈。第三个问题是通知语义。回调是尽力而为还是至少一次链上事件是事实但网络请求不是回调失败是常态。系统必须接受同一笔交易可能被通知多次这个前提然后在接收方做幂等。第四个问题是漏了怎么办。任何监听系统都会有漏块、宕机、节点不可用的时刻必须有一个独立于实时链路的补偿机制定期回扫历史区间把断档补上。这四个问题如果没有提前想清楚后面每个功能都会变成临时打补丁。关键决策常见选项影响监听范围单合约 单地址 / 多合约 多地址决定解析复杂度与白名单维护成本确认数1 块 / 19 块 / 自定义阈值决定资金风险与到账延迟回调语义至多一次 / 至少一次决定是否需要幂等表补偿策略定时回扫 / 手动触发决定故障恢复能力2. 区块监听轮询、事件查询和节点推送怎么选2.1 全量拉块的笨办法反而是最可靠的基线监听链上数据有三条主流路径按块号全量拉取、按合约事件查询、以及订阅节点推送。三条路各有各的适用场景我建议先用最笨的那条把系统跑通再考虑优化。全量拉块的逻辑很直白从游标记录的上次扫描高度开始逐块调用获取区块详情的接口拿到块里的交易列表再针对每笔交易查询执行回执从回执的日志里筛出目标合约的Transfer事件。这个方案的优点是语义最完整——你不仅能看到成功的事件还能看到失败的交易能看到块时间戳、块内交易顺序排查问题时信息量充足。缺点也很明显每个块可能包含几十到上百笔交易逐笔查回执会让RPC调用量成倍增长节点扛不住你自己也扛不住。实际落地时一般会做一层优化先用块里的交易列表做粗筛只对调用了目标合约的交易去查回执。这样能把大部分无关交易挡在外面。如果业务量不大这个方案完全够用而且它的确定性最强出问题时你手里有完整的块数据可以复现。2.2 按事件查询效率高但边界条件必须小心更常见的做法是直接查事件日志接口允许你指定合约地址、事件名、块高范围一次返回一批匹配的日志。这个方案的优势是请求次数少一批能拿回几百条记录适合交易量大的场景。但它有几个边界必须提前处理。第一是分页单次返回条数有上限块高跨度大的时候必须循环翻页直到返回为空或者条数小于上限。第二是块高范围不能太大跨度几千个块以上节点可能直接拒绝或者超时稳妥的做法是切成固定大小的窗口比如每批五百到一千个块逐窗口推进。第三是别用时间戳查询时间戳查询在跨节点时行为不完全一致边界块容易重复或遗漏用块高最稳。还有一点容易被忽略事件查询接口返回的通常是成功执行的事件但不同节点实现在极端情况下可能有细微差异。所以拿到事件之后我仍然建议对关键交易再做一次回执查询确认交易状态字段是成功这一步多花一次请求换来的是判定逻辑的确定性。2.3 事件订阅的断连、漏块和重放节点推送看起来最优雅——连上之后有新区块就推给你不用反复问。但推送通道的稳定性取决于网络和节点断线重连是家常便饭。这里最容易出问题的是重连之后的起点如果你从当前最新块开始断线期间产生的块就永久丢失了如果你从上次处理的块开始又可能重复处理一批已经处理过的数据。正确的做法是把游标持久化每次处理完一批就更新游标重连时从游标位置继续。重复的部分靠下游的唯一约束去重。另外推送通道本身不保证顺序尤其是在多实例部署时A实例收到块100B实例可能先收到块101所以处理逻辑不能假设后到的块一定更高。2.4 一个能跑的监听器骨架下面这段是我实际用过的一个简化版本思路是游标持久化加批量事件查询加地址过滤去掉业务代码之后大概长这样。import time import requests from decimal import Decimal NODE https://api.trongrid.io # 换成自己的节点地址 CONTRACT TContractAddressHere # 目标代币合约 MERCHANT TYourReceiveAddressHere # 你的收款地址 WINDOW 500 # 每批扫描的块数 DECIMALS 6 # 代币小数位 def fetch_events(from_block, to_block): 按块高窗口拉取 Transfer 事件自动翻页 url f{NODE}/v1/contracts/{CONTRACT}/events page 0 while True: params { event_name: Transfer, from_block: from_block, to_block: to_block, size: 200, page: page, } resp requests.get(url, paramsparams, timeout15) resp.raise_for_status() data resp.json().get(data, []) if not data: break for item in data: yield item page 1 def normalize(item): 把原始事件整理成业务字段注意金额用 Decimal result item.get(result, {}) return { txid: item.get(transaction_id), block_number: item.get(block_number), block_ts: item.get(block_timestamp), from_addr: result.get(from), to_addr: result.get(to), amount: Decimal(result.get(value, 0)) / (10 ** DECIMALS), } def scan_once(cursor): latest get_latest_block() start cursor while start latest: end min(start WINDOW - 1, latest) for raw in fetch_events(start, end): ev normalize(raw) if ev[to_addr] ! MERCHANT: continue # 进入确认队列不在这里直接入账 enqueue_for_confirm(ev) cursor end 1 save_cursor(cursor) # 每批都落盘别等全部跑完 start end 1 return cursor这段代码有几个点值得注意。金额必须用十进制或者整数处理浮点数在六位小数的代币上会丢精度小额入账对不上账是必然的。游标要每批落盘不能等整轮扫描结束再存否则中途挂掉就白跑了。事件进入确认队列而不是直接入账是为了把发现和判定两件事解耦后面确认逻辑可以独立演进。提示游标表的更新一定要加行锁或者用乐观锁版本号多实例时防止两个进程同时推进同一个游标导致跳块。3. 交易确认几个块才算真的到账3.1 确认数的经验值从哪来确认数的本质是在赌这笔交易所在的那个块不会被换掉。链上共识机制决定了最终一致性需要时间不同网络的出块节奏不同确认数的经验值也不同。TRC20所在的网络出块间隔大约三秒常见的经验区间是十九到二十个块折算下来一分钟左右。这个数字不是拍脑袋来的大型平台在长期运行中逐步收敛到这个量级既能覆盖绝大多数极端情况又不至于让用户等太久。当然这个值需要根据单笔金额做分层几百块的小额订单三到五个块就可以先给用户一个已确认的中间态提示上万的大额订单建议等到三十个块以上再标记为可结算。这里有个实用技巧把确认过程设计成多阶段状态而不是非黑即白的布尔值。订单可以依次经过已发现已打包确认中已确认可结算几个状态前端可以展示进度业务侧也可以根据金额自行决定在哪个状态放开权益。这样即使用户催单客服也有东西可看。3.2 交易回执里必须逐个校验的字段拿到一笔候选交易之后校验清单比想象中长。下面这几项是我踩过坑之后固定下来的检查顺序。校验项说明漏掉的后果交易状态回执里的执行结果必须是成功失败交易被当成成功入账日志合约地址事件必须来自白名单合约假币合约伪造同名事件事件签名必须是标准 Transfer 签名其他事件被误解析接收地址与订单绑定的收款地址完全一致转给同合约其他地址被误认金额精度用十进制或整数换算小额金额对不上账区块高度达到预设确认数回滚后账实不符特别说一下日志合约地址这一项。有些人写监听逻辑时只看事件名和参数不看日志是哪个合约发出来的。这种做法在早期可能没问题但一旦有人部署一个同名事件的合约往你的地址转一堆毫无价值的代币系统就会把它当成真钱入账。白名单校验是必须的而且要校验到日志级别不能只看交易调用的主合约。3.3 失败交易的花样比想象中多交易失败不等于没上链。在TRC20的场景里合约调用失败依然会消耗手续费交易记录会留在链上回执状态标记为失败事件日志通常为空。常见的失败原因包括资源不足、合约内部主动回退、参数不合法等。资源不足是最常见的一种。TRC20转账需要消耗合约执行资源如果发送方账户没有足够的资源储备交易会以失败告终。这种情况下用户那边可能看到转账失败的提示但有些钱包的提示文案不清晰用户会误以为自己付成功了。所以你的系统在收到这笔交易时必须明确判定为失败并且不产生入账同时把失败原因记录下来方便客服解释。还有一种更隐蔽的情况交易成功事件也有但事件的参数被合约做了手脚。某些非标准合约会在转账时额外扣除手续费或者把金额拆成多笔或者事件里的数值和实际余额变化不一致。对付这种情况唯一的办法是不完全信任事件对高价值订单额外做一次余额差值校验——在交易前后各查一次收款地址的余额用差值来交叉验证。3.4 金额处理的精度陷阱这个坑太常见了值得单独拎出来说。代币的金额在链上是整数单位是最小精度六位小数的代币意味着链上数值 1000000 对应实际的 1 个币。如果代码里用浮点数做除法再比较很容易出现 0.1 0.2 不等于 0.3 这类问题订单金额和实收金额差一个最小单位判定就失败了。正确做法是全程用整数或者高精度十进制类型。订单侧存储的应收金额也用最小单位整数比较的时候直接比整数展示的时候再格式化。这一条看着基础但我见过不止一个系统在金额比较上翻车最后查了半天发现是浮点误差。4. 回调机制把链上事实变成业务事实4.1 回调报文该带哪些字段回调是收款系统和业务系统之间的契约字段设计得好后面能省很多沟通成本。我习惯带上这些商户订单号、交易哈希、日志序号、实付金额、币种合约、区块高度、确认数、通知时间、以及一个签名。日志序号这个字段容易被忽略。同一笔交易里可能有多个Transfer事件比如批量转账光靠交易哈希无法定位到具体是哪一条。把交易哈希和日志序号组合成唯一键才能保证幂等判断的准确性。签名的作用是让接收方确认通知来源可信。做法很简单把关键字段按固定顺序拼接加上双方约定的密钥做一次哈希放在头部或者报文体里。接收方用同样方式计算一遍对比即可。注意拼接时字段顺序和空值处理必须严格一致否则验签会莫名其妙失败。4.2 幂等是回调设计的第一原则链上事件可能被重复处理回调请求可能超时重发业务系统可能重复消费消息。这三点叠加起来同一笔收款被通知多次几乎是必然事件。所以回调的第一原则不是保证送达而是保证重复送达不会出问题。实现方式是在接收方建一张唯一约束表主键用交易哈希加日志序号插入成功才继续处理业务逻辑插入冲突直接返回成功。这样即使通知十次业务只执行一次。发送方这边则要保证每次重试用的是完全相同的内容不要每次重新生成订单号或者时间戳否则接收方没法识别为同一条。4.3 重试策略与死信处理回调失败的原因五花八门接收方服务重启、网络抖动、证书过期、限流。发送方需要一个明确的重试策略我一般用指数退避间隔从几秒开始逐步拉长重试若干次之后转入死信队列由人工或者定时任务处理。这里有个经验重试次数不要设太多也不要设太少。太少了偶发故障就进死信运维压力大太多了会拖长整个通知链路而且对已经挂掉的服务反复请求没有意义。我的习惯是首轮快速重试三次覆盖瞬时抖动之后拉长间隔再试几次总量控制在八到十次左右超过就进死信并触发告警。死信队列必须有配套的处理界面或者脚本能看到失败的订单、失败原因、最后尝试时间并且支持手动重推。没有死信处理机制的回调系统等于把问题藏起来了。4.4 乱序和延迟先到的通知不一定先成交多实例部署时两个监听进程可能同时处理相邻区块导致通知到达业务系统的顺序和链上顺序不一致。如果业务逻辑对顺序敏感比如同一地址的多笔收款要按时间累计额度就需要在通知里带上区块高度和块内序号接收方按这个顺序做排序或者缓冲。还有一种情况是补偿任务和实时链路同时工作补偿任务扫到一笔历史交易实时链路也扫到了同一笔两条路径几乎同时发出通知。这时候幂等约束会挡住重复但要注意补偿任务发出的通知里确认数可能已经很高不要让业务侧误以为是新交易。解决办法是在报文里带上是否补偿的标记或者干脆让补偿任务也走同一个确认队列统一出口。5. 上线前必须做的对账和压测5.1 每日对账用余额快照给账本做体检再严密的监听也可能漏所以必须有一个独立于实时链路的对账任务。做法是每天固定时间查一次收款地址在合约里的余额和系统账本里累计入账金额做比对差额超过阈值就告警。对账的难点在于收款地址通常有资金转出余额不等于累计入账。解决办法是维护一张资金流水表入账和转出都记录对账时用累计入账减累计转出得到应有余额再去和链上查到的余额比较。如果差额不为零就按时间倒序逐笔核对通常能很快定位到漏掉的那笔。5.2 几个真实踩过的故障场景第一个是节点切换导致的游标回退。某次主节点不可用系统自动切到备用节点备用节点的最新块高比主节点低了几百个块监听器按备用节点的高度推进游标结果那几百个块被当成未来跳过了。修复方式是切换节点时校验新节点的块高不低于当前游标低于就等它同步上来。第二个是时间窗口查询的边界重复。早期用时间戳做补偿扫描每批的起止时间有重叠导致边界上的交易被重复处理。虽然幂等表挡住了重复入账但确认队列里堆了一堆重复任务拖慢了整体处理速度。改成块高窗口之后问题消失。第三个是回调签名因为字段顺序变化失败。业务方升级了一次接口把报文字段重新排了序签名逻辑没跟着改导致所有回调验签失败全部进了死信。这件事之后我在双方约定里加了一条签名只针对固定的核心字段新增字段不影响签名计算。5.3 值得常驻的监控指标系统跑起来之后几个指标建议做成看板常驻。扫描高度和链上最新高度的差值正常应该稳定在很小的范围持续拉大说明监听卡住了。从事件发现到确认完成的中位耗时突然变长可能是节点变慢或者队列积压。回调成功率和死信数量反映下游健康状况。每日对账差额正常情况下应该恒为零。这些指标不需要多复杂能画出趋势线就够了。真正出问题的时候趋势线比日志更快告诉你哪里不对。6. 写在最后的一点个人经验做这类系统这些年我最大的体会是链上数据是可信的但你对链上数据的理解不一定可信。监听漏块、确认数不够、事件伪造、精度误差、回调重复这些问题没有一个来自链本身全部来自实现细节。所以与其追求架构多漂亮不如把每个环节的边界条件列清楚逐条写测试用例尤其是那些正常情况下不会发生的分支。另外分享一个小习惯每次上线新版本之前我会拿历史区块做一次全量回放把过去一周的真实交易重新跑一遍对比新旧两版系统的判定结果。这个方法能在几分钟内暴露大部分逻辑改动带来的回归问题比在生产环境上观察半天有效得多。如果你们团队还没有回放环境强烈建议搭一个成本不高收益很大。