到账核对与延迟处理
同步中断、维护或数据核验可能使到账记录晚于交易出现;恢复后补录的有效到账仍使用正常到账对象和通知协议。
正确区分时间
| 字段 | 含义 |
|---|---|
block_time | 交易所在区块的时间,不能用距离当前时间超过几分钟判断到账无效。 |
created_at | 平台首次保存这条到账的时间。首次补录可能明显晚于区块时间;恢复已有记录保留原时间。 |
回调外层 timestamp | 本次通知发送时间,用于校验本次消息,不是交易发生时间。 |
不要因交易时间较早丢弃认证成功的通知。确认类型表示认可到账的规则,不是通知时效承诺。
去重和状态更新
- 用
network + contract + txid + log_index标识链上转账。一笔交易可含多条转账,不能仅用txid去重。 - 用到账
id关联自己的资金记录。已有到账的恢复保留原 ID。 - 用
event_id去重回调消息,同一事件可能再次发送。 - 同一到账只应用更高的
revision。相同或较旧版本应答成功,但不得再次记账。 deposit.confirmed表示满足当前确认规则;deposit.reverted表示到账已撤销。重新确认沿用原到账 ID,版本递增。
详情、列表和通知解密正文共用同一到账对象。同一 id + revision 的业务内容一致,查询返回当前版本,历史通知保留对应版本。
主动核对到账
- 用到账列表查询本账户记录,可按收款地址筛选。
- 用到账详情核对已知 ID 的最新状态和版本。
- 按链上转账标识比对平台和本地记录,区分缺失、重复及状态变化。
- 定位问题时提供网络、合约、收款地址、交易哈希和日志索引。
列表按 ID 降序分页,不是固定快照。查询期间有新记录时可能出现跨页重复,应去重并在下一轮重新覆盖查询范围。不能仅用最后见到的区块时间截断查询,补录可能属于更早区块。已有记录恢复保留原 ID,只查询更大的 ID 也不能替代完整对账。
暂时查不到记录不代表链上转账失败。到账补录不应被当成新的归集请求。
通知与补录
首次补录会创建正常到账通知。继续遵循回调规则:每轮最多 20 次、请求开始时间至少间隔 30 秒、10 分钟截止。已有过期轮次不会因服务恢复自动重置。
重复核验正常到账不会重复创建通知。人工重推保持事件 ID;接收方完成持久化处理后返回 HTTP 200 和 {"code":"SUCCESS"}。