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

140 lines
14 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 地址上链订单:固定转入 1 TRX
## 业务与费用
用户在“我的套餐”或“我的订单”中的“地址上链”卡片输入网络、接收地址及应用凭证,获取报价后确认。即使没有资源套餐,也能创建地址上链订单。供应商通过原有 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位小数,两种网络必须分别显式配置。未配置时拒绝新单,不影响原订单幂等恢复。用户支付总额不因分成比例改变。
```text
平台收入 = 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`:
```yaml
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签名与资源租赁一致:
```json
{"network":"NILE","receiver_address":"TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf"}
```
`POST /api/rental/v1/address-onchain/create`:
```json
{"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、原始凭证帧和带认证信息的响应禁止打印。
### 节点在线但未收到地址上链订单
地址上链不依赖能量/带宽出租开关、可委托质押本金、历史资源证明或资源快照有效期。供应钱包必须在订单对应网络、状态为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核对部署状态:
```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-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增量脚本、未部署、未连接真实钱包、未执行真实支付或链上广播;实际两网联调应在配置完成后进行。