Files
usdt/docs/rental-withdraw.md
T
lu7213 f837befe99 提交冻结USDT,同一用户全网络仅允许一笔进行中提现。
支持后台、Telegram审核;拒绝后释放冻结。
支持管理员填写Hash核验到账、链上监听自动到账,记录到账方式和操作日志。
严格核对网络、付款方、收款方、金额及审核后交易时间,防止重复扣款。
已补齐前端申请、记录、审核、扫描状态和交易明细页面。
2026-10-30 03:44:03 -04:00

8.5 KiB

租赁资金账户提现

业务边界

提现只使用当前用户对应网络 rent_account.available_amount,不提取冻结余额或供应商待结算金额。NILE与MAINNET分别记账,但数据库用 active_user_id 唯一槽保证同一用户全网络只能有一笔未完成提现。提交即在同一事务写 WITHDRAW_HOLD 流水:可用余额减少、冻结余额增加。拒绝写 WITHDRAW_RELEASE;链上到账写 WITHDRAW_COMPLETE,只减少冻结,不再次减少可用。

状态为 PENDING_REVIEW → EXECUTING → VERIFYING/MANUAL_REVIEW → COMPLETED,拒绝为 REJECTED。进入执行后不能直接退款,因为管理员可能已经付款;RPC失败、未确认或证据冲突均保持冻结。

后台和Telegram审核调用相同服务。Telegram数字ID除原白名单外,还必须在 telegram-reviewers 映射到具有 rent:withdraw:review 权限且有效的系统用户,不能用昵称授权或虚构系统操作者。审核通过保存当时的付款地址JSON快照,后续修改配置不改变已审核订单。

手动与自动到账

管理员手动:完成外部钱包付款后填写交易Hash、可选日志索引和执行备注。系统独立查询TRON交易及收据,核验成功才能到账,不能强制改变余额。

自动监听:按网络持久化扫描已固化区块,RPC确认深度由 rental.confirmations 再次限制。逐块读取完整交易收据,发现审核快照付款地址发出的真实USDT Transfer,保存 rent_withdraw_transaction 后匹配提现。匹配同时要求网络、USDT合约、付款地址、收款地址、6位金额完全相同,并且链上区块时间严格晚于 approved_at。不拼接多笔、不接受多付少付;多单歧义转人工核对。

两种入口最终调用同一个 complete 事务。提现单行锁、链上事件唯一键、withdraw_id唯一认领及账本business_key共同防止并发重复扣款。到账记录 arrival_mode=MANUAL/AUTO、Hash、日志索引、区块与时间。自动扫描游标仅在整块事件保存完成后推进,多实例使用短租约;故障重启会重扫,幂等约束防重复。

部署

  1. 执行 sql/rent_withdraw_migration.sql,再执行 sql/rent_withdraw_menu.sql;不删除或重算历史余额。
  2. 配置每个启用网络的付款地址、额度、Telegram映射;先保持 enabled=false 和 scan-enabled=false。
  3. 部署前后端,赋予运营角色 rent:withdraw:list/review/execute;申请角色由脚本获得 rent:withdraw:create。
  4. 打开提现但暂不开扫描,使用小额单验证后台审核及人工Hash核验。
  5. 验证RPC支持 /wallet/gettransactioninfobyblocknum 后开启扫描,观察后台页面游标和服务日志,再扩大额度。
rental:
  withdraw:
    enabled: ${RENT_WITHDRAW_ENABLED:false}
    min-amount-usdt: ${RENT_WITHDRAW_MIN_USDT:1}
    max-amount-usdt: ${RENT_WITHDRAW_MAX_USDT:10000}
    scan-enabled: ${RENT_WITHDRAW_SCAN_ENABLED:false}
    poll-interval-ms: ${RENT_WITHDRAW_POLL_MS:10000}
    scan-batch-blocks: ${RENT_WITHDRAW_SCAN_BATCH_BLOCKS:5}
    telegram-reviewers: ${RENT_WITHDRAW_TELEGRAM_REVIEWERS:}
    nile:
      payout-addresses: ${RENT_WITHDRAW_NILE_PAYOUT_ADDRESSES:}
    mainnet:
      payout-addresses: ${RENT_WITHDRAW_MAINNET_PAYOUT_ADDRESSES:}

服务不保存付款私钥、不自动广播。配置多个地址用英文逗号分隔;地址与Telegram映射属于敏感运营配置,不提交代码仓库。日志打印提现ID、网络、金额、Hash、日志索引、模式和脱敏异常定位,不打印凭证、私钥、签名原文或完整RPC响应。

页面及接口

本人资金账户页提供申请、记录和时间线:POST /rental/withdraw/create、GET /rental/withdraw/list、GET /rental/withdraw/{id}。管理员菜单页面使用 /rental/manage/withdraw 下的列表、详情、审核及transaction接口;只读交易明细接口便于定位未匹配事件。用户ID始终来自登录上下文。

申请示例(使用已登录后台身份,不使用租赁应用API凭证):

{"network":"NILE","receiver_address":"你的TRON地址","amount":"30.000000","client_request_no":"客户端唯一请求号","remark":"提现说明"}

client_request_no重试必须保持不变。相同用户与请求号、相同内容返回原申请;变更金额或地址需要新请求号,并且原在途申请必须先结束。金额以十进制字符串传递,最多6位小数;初版不收提现手续费,申请金额等于链上应付USDT金额。

管理员审核:POST /rental/manage/withdraw/{id}/review,请求 {"approve":true,"reason":"审核意见"}。手动到账:POST /rental/manage/withdraw/{id}/transaction,请求 {"transaction_id":"64位Hash","log_index":0,"remark":"付款执行说明"};日志索引可省略,但同一交易存在多个符合条件的事件时必须明确指定。核验未通过时返回保留冻结的当前状态及last_error,前端不得仅根据HTTP成功提示到账。

交易排查:GET /rental/manage/withdraw/transactions?network=NILE&page=1&hash=可选完整Hash。本人列表固定每页20条,管理员列表支持network/status/page;本人详情禁止跨用户访问。相同区块发现多笔符合单张提现申请的付款时转人工核对,不自动选择第一笔。

数据表职责

表 关键字段与职责
rent_withdraw_order user_id/account_id/network确定资金归属;amount/frozen_amount记录申请与冻结金额;active_user_id唯一约束防全网络重复申请;client_request_no/request_hash保证重试幂等;approved_at与payout_sender_snapshot固定匹配边界;arrival_mode/arrival_transaction_id/completed_at记录到账结果
rent_withdraw_transaction network+transaction_id+log_index唯一标识真实链上事件;保存合约、付款方、收款方、6位USDT金额、最小单位、区块Hash/时间和证据;withdraw_id唯一约束防止一笔付款核销两次
rent_withdraw_scan_cursor 每网络一个持久扫描位置,last_block只在整块处理成功后推进;lock_owner/lock_until支持多实例租约;last_error记录可排查故障
rent_ledger 新增nullable withdraw_id关联提现;WITHDRAW_HOLD/RELEASE/COMPLETE与余额更新同事务,不更改既有充值和租赁流水
rent_event 保存申请、审核、手动核验、MANUAL/AUTO到账操作轨迹和操作者
telegram_audit_record及推送队列 沿用项目现有Telegram审核模型,业务类型RENT_WITHDRAW;创建申请时与冻结一并持久化,机器人推送失败不丢审核单

排查及运行边界

管理员详情突出展示本单网络的允许付款钱包,并在通过审核前再次确认网络、付款地址、收款地址与金额。待审核使用当前配置,通过后展示审核时的地址快照;地址未配置或详情未加载完成时禁止点击通过。提示同时适用于后续手动Hash核验与自动到账。

按withdrawId/withdrawNo、network、Hash检索日志;扫描日志包含cursor、confirmedHead及backlog。余额不足、重复申请、本人审核、权限映射无效均拒绝;网络异常、未确认、付款方/金额不匹配均不解冻。管理员不能审核自己的提现。

首次扫描从最早有效审核时间前定位区块,之后按持久断点追赶。默认每10秒最多扫描5块,积压时可调大batch(上限100),并观察RPC限流。RPC必须支持整块回执接口,不支持或回执缺失时停止推进并保留冻结;不会降级成忽略交易。服务使用已有TRON网络配置和对应USDT合约,不能把测试网交易用于主网到账。

增量脚本需先于新服务执行,因为公共账本插入已包含withdraw_id。脚本仅新增结构和菜单,不会付款、不重算余额、不删除历史数据。真实MySQL、Telegram机器人及NILE钱包仍需部署后小额联调。

本地验证记录

  • JDK8执行Rental*Test:108项通过,0失败、0错误,其中提现专项12项。
  • 覆盖冻结/拒绝释放、跨网络并发申请、幂等重试、手动与自动并发核销、未知链上结果保留冻结、重复付款歧义、Telegram真实审核路由和重复回调、RPC失败后恢复,以及真实USDT日志解码和确认边界。
  • 前端staging构建完成;存在项目原有的3个API导出缺失告警以及资源体积告警。提现相关Vue模板与脚本解析通过。
  • 新建表在初始化、独立建表和增量脚本中的定义一致。数据库测试使用H2 MySQL兼容模式,未执行生产MySQL脚本,未发送Telegram消息或广播交易。