113 lines
11 KiB
Markdown
113 lines
11 KiB
Markdown
# 地址上链订单:固定转入 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串联云端及本地日志。云端打印冻结金额拆分、候选余额不足(DEBUG)、派单、节点事件、独立证明、扣款及明确失败。Node打印PREFLIGHT、预算、BUILT_PERSISTED、BROADCASTED/UNKNOWN;Java打印任务阶段、原交易恢复及RPC路径耗时。密钥、签名交易、API Secret、原始凭证帧和带认证信息的响应禁止打印。
|
||
|
||
## 验证记录(2026-10-29)
|
||
|
||
追加服务费分账后,JDK8云端租赁测试95项通过,包含H2真实事务、唯一键、无套餐下单、重复冻结防护、分成边界及舍入守恒、历史快照不重算、平台单次入账、净额结算、UNKNOWN隔离和独立链上参数证明。公开API文档ESLint通过。此前Node Agent14项、Java17 Agent41项测试通过,Java Agent完成package构建,Vue模板编译及staging生产构建通过(现有3项无关API导出警告及2项包大小警告);此次分账未修改Agent。
|
||
|
||
本次未运行生产MySQL增量脚本、未部署、未连接真实钱包、未执行真实支付或链上广播;实际两网联调应在配置完成后进行。
|