Files
usdt/docs/rental-address-onchain.md

21 KiB
Raw Permalink Blame History

地址上链订单:固定转入 1 TRX

业务与费用

同一网络、同一接收地址只能存在一笔待处理的地址上链订单,限制跨应用、跨用户生效。WAITING、EXECUTING、VERIFYING、MANUAL_REVIEW 均占用名额;只有 SUCCESS、FAILED、CANCELLED 释放。相同商户订单号及参数重试仍返回原单,不重复冻结。失败或取消后可重试,但仍须通过链上未激活校验。数据库唯一索引防止并发绕过检查。

已有数据库需先执行 sql/rent_onchain_pending_migration.sql;若有历史重复待处理订单,脚本拒绝升级,需人工核实交易和资金状态后处理,禁止直接删除或批量取消。

用户在“我的套餐”或“我的订单”中的“地址上链”卡片输入网络、接收地址及应用凭证,获取报价后确认。即使没有资源套餐,也能创建地址上链订单。供应商通过原有 rent_node 及已证明所有权的 rent_wallet 执行,不需要供应商创建 rent_app。

地址上链使用独立路径 /api/rental/v1/address-onchain/quote、/create、/query,订单类型由路径固定为 ADDRESS_ONCHAIN,请求可省略order_type;若提交只能为ADDRESS_ONCHAIN。原 /api/rental/v1/quote、/create、/query 仅处理 RESOURCE_RENTAL,拒绝混用订单类型。两者复用签名、应用归属、商户单号幂等、账务及回调机制。原地址上链接入方需同时更新请求URL和HMAC签名中的完整路径,不能用旧路径签名请求新接口;已有订单可通过新的query路径按原商户单号查询。

每笔固定转出 1 TRX = 1000000 SUN。USDT 本金折价 = ceil6(1 × trx-price-usdt);固定服务费 = ceil6(service-fee-usdt);总金额为两者之和。示例汇率0.15、固定服务费0.05,总冻结0.200000 USDT。所有运算使用 BigDecimal,不使用浮点数。NILE 和 MAINNET 汇率、服务费分别配置,未配置不允许下单,不自动取另一网络价格。

这里固定服务费使用 USDT 配置,不是实际链上燃烧的 TRX。本金全额补偿供应商,只有服务费参与百分比分成。实际网络交易/激活费用由供应商承担,不能在执行后追加扣用户资金。运营定价时应覆盖激活成本;fee-limit-sun 是链上操作本地预算,不计入用户报价第二次收费,也不是原生TRX交易的协议硬上限。

供应商与平台分账

platform-fee-percent 表示平台占服务费的百分比,20表示20%,允许0至100、最多4位小数,两种网络必须分别显式配置。未配置时拒绝新单,不影响原订单幂等恢复。用户支付总额不因分成比例改变。

平台收入 = round6(服务费 × platform-fee-percent / 100),四舍五入
供应商服务收入 = 服务费 - 平台收入
供应商净应收 = 1TRX折价本金 + 供应商服务收入
用户支付总额 = 供应商净应收 + 平台收入

例如本金0.150000、服务费0.050000 USDT、平台比例20:用户扣0.200000,供应商净得0.190000(本金0.150000+服务收入0.040000),平台得0.010000。比例0表示服务费全归供应商,100表示服务费全归平台,本金始终归供应商。只对平台份额舍入一次,供应商取差额,保证金额守恒。

下单保存 supplier_amount=用户总额、supplier_fee_percent=平台百分比、supplier_fee_amount=平台收入、supplier_net_amount=供应商净应收,完整报价保存到package_snapshot。历史订单不重算,同一商户单号重试使用原快照;客户端不可覆盖分成参数。资源租赁订单继续按原有套餐规则计算。

链上独立确认成功才在同一事务写CHARGE、SUPPLIER_EARN和SUPPLIER_FEE流水:先登记供应商毛收入,再扣平台份额并写入 rent_ledger.delta_platform_fee;供应商待结算余额只增加净额。平台收入不是用户可用余额,平台统计沿用平台流水汇总。重复确认不重复入账,失败/未知不会确认收入。结算使用净应收,不二次扣费;退款/冲正仍走现有审核流程,平台退费累计上限为订单快照supplier_fee_amount,不随当前配置变化。

地址上链仅允许当前网络尚未激活的地址。创建新单前,云端调用所选网络最新节点的 /wallet/getaccount,已存在账户(即使余额为0)拒绝创建;RPC异常或响应异常时中止,不生成订单、不冻结USDT。报价只计算费用,不保证下单时仍未激活。原商户单号幂等重试仍返回原单,不会因原单执行后地址已激活而失败。合约地址由本地Agent拒绝;网络由请求明确指定,不通过地址推断。此检查不构成对外部链上交易的锁定,检查之后地址仍可能被第三方激活。

流程与失败处理

  1. /api/rental/v1/address-onchain/quote 校验当前网络配置及地址,计算USDT报价,不冻结资金。
  2. /api/rental/v1/address-onchain/create 锁定应用,按 app_id + merchant_order_no 幂等,保存价格快照、冻结用户USDT可用余额。重试命中原单不重读价格、不再次冻结;expected_amount 不匹配拒绝。网络、接收者、订单类型变化拒绝复用原商户单号。
  3. 云端只选择当前在线、审核通过、钱包所有权已证明、明确声明 transfer_enabled 的供应节点。检查候选TRX余额,持有钱包TRX执行槽,签发 TRANSFER_TRX 原生任务。旧Agent未声明能力,不会收到转账任务。
  4. Agent确认 RENT_TRANSFER_ENABLED=true、总广播授权、同网络、本地钱包owner、固定1000000 SUN、接收者、余额、权限、当前带宽费率、未激活地址创建费及留存。构建单个TransferContract,独立检查原始protobuf与授权一致后本地签名,先加密落盘再广播。
  5. 云端在订单网络独立查交易与确认回执,核对交易类型、唯一合约、owner、to、1000000 SUN、授权时间及确认深度。节点自报SUCCESS/RESULT不能触发扣款。
  6. 独立确认成功后:冻结USDT扣除、生成供应商待结算收入、订单SUCCESS、回调SUCCESS。reclaim_status=NOT_REQUIRED,不产生租期或回收任务;供应商结算沿用现有结算功能。
  7. 明确未执行的拒绝或链上已证明失败:同一订单最多4次任务尝试且不超过派单截止;终结释放冻结。未派单超时取消。断线、超时、查不到交易及UNKNOWN都不能证明未执行:保留任务槽、冻结资金和原签名交易,不自动退款或改派。

Agent暂停后未签名任务会明确拒绝;已经签名的任务始终只查原txID或重播同一原交易。禁止删除任务日志、用新单号重复提交来处理未知结果。管理员可通过现有原交易补证操作核对原始转账,不能用人工改余额代替核验。

表设计与协同

表 本功能数据与职责
rent_order 新增order_type、transfer_sun、trx_price_usdt、principal_usdt、service_fee_usdt;package_id允许NULL,package_snapshot复用保存费用预算及完整报价;resource_type=TRX,资源数量/租期=0
rent_node 新增transfer_enabled,由认证SYNC_STATE同步能力及本地授权;默认0,旧Agent关闭
rent_wallet 复用节点关联、网络、所有权证明、状态;无需创建私钥字段,实时余额由RPC及Agent校验
rent_task task_type=TRANSFER_TRX,resource_type=TRX,delegate_sun复用保存固定转账本金1000000,换算额度/权重为0;钱包TRX执行槽隔离资源任务
rent_transaction 一任务一原交易,transaction_type=TRANSFER_TRX,amount_sun=1000000,保存独立确认区块、时间和证据;网络+txID唯一防重复认领
rent_account / rent_ledger USDT冻结、扣款、释放以及供应商收入均同事务入账,沿用不可变business_key去重
rent_settlement / rent_settlement_item 复用订单净应收来源及人工付款授权,包含本金折价和服务收入
rent_app / rent_credential 用户应用及APP签名凭证;供应商使用NODE凭证,与应用凭证隔离
rent_webhook / rent_event 复用回调重试、签名验签、操作与节点审计

本功能不新增独立订单/账户表,避免两套余额与幂等。历史资源订单默认RESOURCE_RENTAL,委托及回收行为保持现有规则。

升级与配置

已有库执行 sql/rent_address_onchain_migration.sql,全新库用更新后的 sql/rent_init.sql。增量脚本支持重复执行;它不会删表、改历史金额或真实广播。升级期间停止租赁worker及Agent,先迁移,再部署云端和两个Agent,最后开启功能。

在application-rental.yml中已添加 rental.address-onchain:

rental:
  address-onchain:
    enabled: ${RENT_ADDRESS_ONCHAIN_ENABLED:false}
    nile:
      trx-price-usdt: ${RENT_ADDRESS_ONCHAIN_NILE_TRX_PRICE_USDT:}
      service-fee-usdt: ${RENT_ADDRESS_ONCHAIN_NILE_FEE_USDT:}
      platform-fee-percent: ${RENT_ADDRESS_ONCHAIN_NILE_PLATFORM_FEE_PERCENT:}
      fee-limit-sun: ${RENT_ADDRESS_ONCHAIN_NILE_FEE_LIMIT_SUN:3000000}
    mainnet:
      trx-price-usdt: ${RENT_ADDRESS_ONCHAIN_MAINNET_TRX_PRICE_USDT:}
      service-fee-usdt: ${RENT_ADDRESS_ONCHAIN_MAINNET_FEE_USDT:}
      platform-fee-percent: ${RENT_ADDRESS_ONCHAIN_MAINNET_PLATFORM_FEE_PERCENT:}
      fee-limit-sun: ${RENT_ADDRESS_ONCHAIN_MAINNET_FEE_LIMIT_SUN:3000000}

仅在计划使用的网络配置正汇率、非负服务费。供应商Agent新增 RENT_TRANSFER_ENABLED=false,明确同意转账后改为true并重新连接。RENT_MAX_SUN至少1000000;RENT_MAX_FEE_SUN不小于订单fee-limit-sun;余额覆盖转出本金、保守链上费用与RENT_TRX_RETAIN_SUN。这两个限额单位均为SUN。JavaFX每次启动仍默认关闭总广播,必须手动开启。

使用原有应用凭证调用新的地址上链独立API,无需额外菜单权限。网页公开API文档访问 /rental-api,所有独立接口及示例统一列在接口列表中。

API 示例

POST /api/rental/v1/address-onchain/quote,请求头及HMAC签名与资源租赁一致:

{"network":"NILE","receiver_address":"TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf"}

POST /api/rental/v1/address-onchain/create:

{"network":"NILE","receiver_address":"TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf","merchant_order_no":"ADDR-DEMO-001","expected_amount":"0.200000"}

查询:POST /api/rental/v1/address-onchain/query,请求 {"merchant_order_no":"ADDR-DEMO-001"}。

不得传入package_id、resource_type、resource_quantity、duration_seconds、transfer_sun。金额示例不是实际配置价格。query按merchant_order_no查询;响应及回调增加order_type、transfer_sun、principal_usdt、service_fee_usdt、transaction_id,金额单位USDT。transaction_id仅在云端独立确认转账后提供,确认前为空。回调接收方照旧验签、按event_no去重、仅在业务落库成功后返回正文ok。

日志排查

使用orderId、taskId、nodeId、network、txID串联云端及本地日志。云端打印冻结金额拆分、无合格候选、候选余额不足(INFO,包含本金及费用上限SUN)、同地址跳过、状态变化/执行槽占用、派单、节点事件、独立证明、扣款及明确失败。Node打印PREFLIGHT、预算、BUILT_PERSISTED、BROADCASTED/UNKNOWN;Java打印任务阶段、原交易恢复及RPC路径耗时。密钥、签名交易、API Secret、原始凭证帧和带认证信息的响应禁止打印。

节点在线但未收到地址上链订单

快照更新时间长期不变时,先检查启动日志“租赁快照定时扫描已启用”。扫描每轮结束后延迟15秒再次运行,每批最多20个ACTIVE且快照缺失/过期的钱包;游标走到末尾后下一轮从头开始,因此不是每个钱包严格每15秒更新。刷新成功输出INFO(walletId、网络、旧快照时间、耗时),失败输出WARN及安全异常因果链;批次汇总输出成功/失败数量。无候选和区块夹读明细为DEBUG。失败不会推进snapshot_at或有效期。

链上采集失败日志stage含义:BEFORE_BLOCK/AFTER_BLOCK为区块RPC,ACCOUNT_RESOURCE为资源RPC,ENERGY_DELEGATABLE/BANDWIDTH_DELEGATABLE为对应可委托本金RPC,BLOCK_CONSISTENCY为前后区块一致性检查,GLOBAL_PARAMETERS为全网参数检查。BLOCK_CHANGED_OR_INVALID显示前后高度;STALE_OR_CONCURRENT显示钱包版本、新旧高度及快照屏障。RPC另记录路径和非成功HTTP状态码,不记录认证头或响应原文。请按walletId、网络、地址和相邻时间关联日志。

区块夹读不一致时,在本轮立即整套重采集,最多3次(含首次);每次重新查询前后区块、资源和两类可委托本金,绝不复用失败尝试的数据。日志包含attempt/maxAttempts、每次耗时,重试成功或耗尽时输出总耗时。3次均失败则不更新旧快照及时间,等待后续扫描。RPC错误、本金响应无效、全网参数缺失不作为跨区块错误盲目重试;数据库版本及快照屏障校验保持不变。持续跨区块应检查RPC延迟及节点一致性,重试不能保证慢RPC一定取得快照。

地址上链不依赖能量/带宽出租开关、可委托质押本金、历史资源证明或资源快照有效期。供应钱包必须在订单对应网络、状态为ACTIVE且已完成控制权验证;节点必须ACTIVE、ONLINE、心跳未过期,并由Agent在连接恢复同步时上报转账授权。仅打开能量/带宽出租并不会授予转账权限。

Agent配置 RENT_TRANSFER_ENABLED=true 后需重启或重连;数据库中的 rent_node.transfer_enabled 应由Agent同步上报,不应手工改成1绕过本地授权。Java Agent还需要打开总广播授权。云端实时查询余额至少覆盖固定1TRX与订单快照中的fee-limit-sun,Agent执行前还会检查实际创建费、带宽费用及本地留存。

修复后的转账任务 conversion_block_height=0 表示不适用质押换算,不代表链上确认高度。委托/回收任务仍使用可信资源高度。无需为此修改数据库结构或生成虚假资源快照。

可使用以下只读SQL核对部署状态:

SELECT o.id, o.order_no, o.network, o.status, o.dispatch_deadline,
       t.task_no, t.task_type, t.status AS task_status
FROM rent_order o LEFT JOIN rent_task t ON t.order_id=o.id
WHERE o.order_type='ADDRESS_ONCHAIN' ORDER BY o.id DESC LIMIT 20;

SELECT w.id AS wallet_id, w.network, w.status AS wallet_status,
       w.ownership_verified_at, n.id AS node_id, n.status AS node_status,
       n.connection_status, n.heartbeat_expires_at, n.transfer_enabled
FROM rent_wallet w JOIN rent_node n ON n.id=w.node_id
ORDER BY w.id;

WAITING且没有任务表示尚未派单;已有PENDING任务则继续检查Socket推送和Agent接收日志。EXECUTING/UNKNOWN已有在途任务时,不允许手动重置订单或另建交易。更新服务端后,仍在派单期限内的WAITING订单由扫描自动重试;已超时取消的订单不会自动恢复。

回调未到达排查(2026-11-02)

持续405的实际HTTP探测证据、关联日志和Nginx精确代理配置见回调405定位。

调试接收端验签

WebhookDebugController的POST /api/webhook/debug仅接收application/json。使用原始UTF-8正文和X-Rent-Key/Timestamp/Nonce/Signature请求头,复用租赁WEBHOOK域HMAC-SHA256协议,允许时间偏差小于60秒;正文上限512KiB。GET返回405,CONFIGURED模式缺凭证或存储故障503,认证失败401,事件JSON无效400,nonce重放409;仅验签及持久化nonce成功返回纯文本ok。不更新业务订单,不用于正式记账,合法事件重投携带新nonce时可再次观察。

rental:
  webhook-debug:
    credential-source: ${RENT_WEBHOOK_DEBUG_CREDENTIAL_SOURCE:APP}
    api-key: ${RENT_WEBHOOK_DEBUG_API_KEY:}
    api-secret: ${RENT_WEBHOOK_DEBUG_API_SECRET:}
    signature-path: ${RENT_WEBHOOK_DEBUG_SIGNATURE_PATH:}

默认APP模式按请求X-Rent-Key查询本系统ACTIVE且未过期的APP凭证并解密Secret验签,不需要填写固定api-key/api-secret;未知、NODE、停用或过期凭证拒绝。适用于同系统调试,能够验证各应用轮换后的真实签名,不能作为外部商户生产回调的身份授权模型。CONFIGURED模式使用上面的固定凭证,必须与发送器当前选择的APP有效凭证一致;轮换后同步更新接收端。路径必须与外部notify_url路径逐字一致:例如回调地址为http://192.168.3.103/api/api/webhook/debug,Nginx移除一层/api后,设置RENT_WEBHOOK_DEBUG_SIGNATURE_PATH=/api/api/webhook/debug。留空使用后端实际请求URI,不能从不可信转发头推断路径。不将Secret、签名、完整正文或异常原文写日志;成功记录事件号、订单号、事件类型及状态摘要。修改配置后重启服务。此接口映射不能修复Nginx静态服务产生的405,仍需确保POST转发到后端2020端口。

认证诊断不再合并为“通知认证参数无效”:分别记录KEY_MISSING、KEY_MISMATCH、ACTIVE_APP_CREDENTIAL_NOT_FOUND、NONCE_INVALID、TIMESTAMP_NOT_UNIX_MILLIS、TIMESTAMP_OUT_OF_WINDOW及SIGNATURE_MISMATCH_CHECK_SECRET_PATH_AND_BODY。日志提供Key不可逆摘要、时间差毫秒数、nonce长度,不记录认证原文。HTTP时间戳是Unix毫秒,与DATETIME存储时区无关,不允许手工加8小时或取消时间窗验证。独立demo接收端仍使用其固定配置,并返回具体参数校验说明。

在服务端日志中按 webhookId 或 orderId 查询“租赁回调”。日志依次包含领取次数/正文字节数、目标主机/路径、有效凭证记录ID、POST请求开始、HTTP响应状态/长度和最终状态;异常包含失败阶段及安全的异常类型/代码位置,不输出Secret、签名、请求正文或响应正文。rent_webhook.last_error同步保存固定阶段和原因码。

  • TARGET_NOT_PUBLIC:目标被地址策略拒绝。开启内网配置后允许192.168/10/172.16~31及IPv6 ULA;回环、链路本地、未指定及组播仍拒绝。关闭内网配置时192.168.x.x等也会被拒绝。
  • TLS_CERTIFICATE_OR_HANDSHAKE_FAILED:HTTPS握手或证书验证失败。
  • DNS_RESOLUTION_FAILED、CONNECTION_FAILED、TIMEOUT_OR_INTERRUPTED:分别核对DNS、端口和网络超时。
  • NO_VALID_CREDENTIAL_OR_LOOKUP_FAILED:检查订单所属应用是否有ACTIVE且未过期凭证及数据库状态。
  • HTTP_STATUS_301/302/404/401/...:请求已收到HTTP响应,检查代理路由/登录拦截;不会自动跟随重定向。/api/api/webhook/debug是否正确取决于Nginx前缀转发,不自动删减路径。
  • ACK_BODY_NOT_EXACT_OK:要求HTTP200且响应正文严格为小写ok,JSON包装、HTML或多余换行均不确认。

扫描每5秒执行,仅领取已到next_attempt_at且租约可用的PENDING/SENDING记录。失败退避重试,累计10次进入DEAD;管理员通过已有回调重投功能重新投递DEAD事件,不直接修改订单或删除回调记录。没有回调URL时沿用既有跳过发送并确认的行为,日志标记EMPTY_NOTIFY_URL。

内网回调配置为rental.webhook.allow-private-network: ${RENT_WEBHOOK_ALLOW_PRIVATE_NETWORK:true},按当前需求默认开启,修改后重启服务生效;设为false恢复仅公网策略。支持http://192.168.3.103/api/api/webhook/debug,也支持http://192.168.3.103:2020/api/webhook/debug等内网HTTP自定义端口;路径由Nginx或后端实际路由决定。HTTP按发送时DNS解析结果逐个校验,仅可连接私网,禁止代理及重定向;公网HTTP仍拒绝。HTTPS仍限定443且校验证书链及IP SAN。

诊断定向测试3项通过,覆盖内网开关、私网及IPv6 ULA放行、特殊地址继续拒绝和网络/凭证错误分类;未连接实际回调目标或操作生产数据。

验证记录(2026-10-29)

地址上链派单修复回归:JDK8离线执行 RentalBusinessTest,RentalOnchainTest,67项通过、0失败、0错误。新增覆盖无资源快照派单并完成独立核验扣款、过期快照不阻止转账但阻止资源委托,以及无快照下身份/网络/在线心跳/授权/余额保护。本次未进行真实链上广播或生产部署。

追加服务费分账后,JDK8云端租赁测试95项通过,包含H2真实事务、唯一键、无套餐下单、重复冻结防护、分成边界及舍入守恒、历史快照不重算、平台单次入账、净额结算、UNKNOWN隔离和独立链上参数证明。公开API文档ESLint通过。此前Node Agent14项、Java17 Agent41项测试通过,Java Agent完成package构建,Vue模板编译及staging生产构建通过(现有3项无关API导出警告及2项包大小警告);此次分账未修改Agent。

本次未运行生产MySQL增量脚本、未部署、未连接真实钱包、未执行真实支付或链上广播;实际两网联调应在配置完成后进行。