← 文档索引
pangolin-pay 单地址 + 唯一金额收款模型
2026-07-09 · 阅读版 · 执行真相源 docs/superpowers/plans/2026-07-09-pay-single-address.md · #34/34A 收款模型定稿
定稿:单个固定收款地址 + 每单唯一金额。 归集 = 1 个地址(激活一次、扫一笔),成本最省;订单靠金额区分,不靠地址。前端契约不变(POST /order 返回 address+expect_amount)→ 以后升多地址/GasFree 是纯后端换实现,前端零改动。
唯一金额:expect_amount = base + tail,base=价格×1e6(micro-USDT),tail∈[1,9999] micro(偏差<0.01 USDT,价格几乎不变),迟到窗口内不复用。匹配=精确 ==:找"到收款地址、value==expect_amount、block_ts>建单"的转入 → paid。支付页显示可复制的精确金额。付错/迟到抹尾数 → 孤儿人工对账。
Phase A — 数据模型
- A.1 pay_orders 加 user_ref / expect_amount(唯一金额)/ matched_tx_id;address 恒为收款地址。
- A.2 tail 分配支撑:活跃订单已用 tail + 近期冷却(迟到窗口不复用)。
- A.3 orphan_payments(tx_id唯一/value/block_ts/handled)。
- A.4 配置 PAY_RECEIVE_ADDRESS(或从 xpub 派生 index 0)。
Phase B — 建单
- B.1 CreateOrder(user, sku, price):同用户无活跃单 → 分配唯一金额 → 写 pending(TTL 15min)。
- B.2 tail 分配(活跃间不撞 + 迟到窗口不复用);GetOrder。
Phase C — watcher
- C.1 匹配:pending 单查收款地址转入,value==expect_amount 且 block_ts>created → paid + tx。
- C.2 超时 → expired。
- C.3 孤儿:到账不匹配任何活跃订单 → orphan_payments(去重)。
- C.4 幂等 + 崩溃恢复;TronGrid 取 block_timestamp。
Phase D — 归集
- D.1 扫收款地址余额 → 冷钱包(能量租赁);一地址一笔。
Phase E — 验证
- E.1 单测:唯一金额不撞、精确匹配、付错/迟到成孤儿、超时、同用户单订单、幂等、时间戳过滤。
- E.2 真链:两并发订单不同金额同地址各 paid;付错成孤儿;归集。
不在本轮
- 多地址/地址池、GasFree(#35)、能量租赁自动化、发货侧 —— 以后需要纯后端切,前端不动。
相关:加密货币交易引擎(已实现钱包/tron/sweep) · 渠道选型