payments-tron-trc20-removed
Historical reference (removed feature). TRC-20 USDT autopay was removed; cryptocurrency deposits/withdrawals now route through Plisio. See servers_v2/wallet_service/app/api/routes/plisio.py. Original spec retained for audit / reactivation reference only.
1. 系统总体目标
- 通过主助记词（HD Wallet）派生唯一的 TRC20 (USDT) 地址；
- 用户仅保存 index 即可恢复充值地址；
- 同一订单支持多次充值自动累计；
- 系统自动检测到账并执行归集；
- 运行中 零 Gas 手续费（能量统一由质押钱包供应）；
- 新钱包激活由初始化钱包完成。
2. 核心角色及配置信息
| 角色 | 功能 | 所需信息 |
|---|
| HD 派生模块 (HD Seed) | 从主助记词派生用户充值地址 | 助记词、路径 m/44'/195'/0'/0/<index> |
| 用户地址 (Derived User Wallet) | 用户充值地址，可接收 USDT 并被归集 | 用户 index |
| 归集钱包 (Collector Wallet) | 签名归集交易、接收入账资金 | 地址 + 私钥（加密存储） |
| 质押钱包 (Staking Wallet) | 冻结 TRX 以获取 Energy，委托给归集地址或子地址 | 地址 + 私钥（加密存储） |
| 初始化钱包 (Initializer Wallet) | 执行地址激活或初始化操作（发送 0.000001 TRX、首笔授权、测试交易等），可与主/归集钱包为同一地址 | 地址 + 私钥（加密存储） |
| TronGrid API | 查询链上交易及资源状态 | URL + API Key |
| 数据库 | 存储索引、地址映射、充值记录等 | DSN、凭证、AES/KMS 密钥 |
3. 钱包体系关系
| 钱包 | 职责 | 说明 |
|---|
| 质押钱包 | 冻结 TRX → 获取 Energy → 委托能量 | 主要提供能量，与主钱包可分离 |
| 归集钱包 | 负责 USDT 归集与出账 | 可由质押钱包委托 Energy |
| 初始化钱包 | 激活新地址（发送 0.000001 TRX）或进行初始授权 | 可与主钱包/归集钱包同一地址 |
| 主助记词（HD 钱包） | 仅用于派生充值地址 | 不参与转账，安全隔离 |
设计建议：
- 初始化钱包余额维持极低，仅存放可控 TRX 用于激活；
- 质押钱包&归集钱包&初始化钱包，这三个钱包可为一个钱包
4. 地址激活流程（Initializer Wallet 支持）
| 步骤 | 动作 | 来源钱包 | 数额 | 说明 |
|---|
| 1 | 检测地址是否存在 | — | — | 未存在则需激活 |
| 2 | 发送 0.000001 TRX 至新地址 | 初始化钱包（或主钱包） | 0.000001 TRX | 激活账户 |
| 3 | 等待 confirmed | — | — | 激活成功 |
| 4 | 记录 TX hash 和 激活时间 | — | — | 用于审计 |
✅ 初始化钱包可由质押或归集钱包代理执行，但建议独立管理以便限权、限额。
5. 初始化钱包新增配置
| 参数 | 示例 | 说明 |
|---|
| initializer_address | TABC...xyz | 初始化钱包地址 |
| initializer_privkey | 加密私钥 | 加密后仅系统可用 |
| activation_amount | 0.000001 | 激活 TRX 额度 |
| activation_threshold | 500 TRX | 不足时自动告警或补充 |
| auto_delegate_energy | true | 激活后自动触发能量委托 |
6. 模块结构更新
| 模块 | 职责 | 技术实现 |
|---|
| HD 派生模块 | 派生新地址 | bip32utils + tronpy |
| 地址激活模块 | 使用 Initializer Wallet 激活未注册地址 | tronpy + API 调度 |
| 充值监听模块 | TronGrid 监听 USDT 交易 | aiohttp 轮询 |
| 自动归集模块 | 调用 Collector Wallet 进行归集 USDT 转账 | tronpy |
| 能量委托模块 | 调用 Staking Wallet 委托能量 | tronpy + 定时任务 |
| 初始化模块 | 负责检测、激活、记录激活状态 | tronpy 任务脚本 |
7. 运行流程
- 系统初始化主助记词；
- 生成 质押、归集、初始化 钱包；
- 质押钱包冻结 TRX → 获取 Energy；
- 用户注册 → 分配 index → 生成充值地址；
- 检测地址未激活 → 由初始化钱包 转 0.000001 TRX 激活；
- 激活成功 → 质押钱包委托 Energy 给该地址；
- 用户充值 USDT；
- 系统监听到账并累计金额；
- 达阈值自动归集至归集钱包；
- 归集完成 → 可取消能量委托。