Files
usdt/docs/rental/history-service.md
T

16 KiB

云端内置 TRON 历史资源证明服务

本功能随现有 Java 8 云端服务启动,复用 MySQL 和只读 TRON RPC,不需要另起一个 Java 服务,也不需要供应商运行 TRON 节点。默认关闭;不持有钱包私钥,不签名、不广播、不执行自动出金。

业务16表保持不变,新增4张独立历史表,总计20张租赁相关表。安装脚本为 rent_history_init.sql,业务基础脚本仍为 rent_init.sql。没有对现有数据库执行这些脚本。

1. 实现范围与可信前提

普通 HTTP RPC 不支持任意历史高度的完整账户/全网资源状态。内置实现采用“实时确认状态采集 + 完整区块事件归档 + 地址对重放”,从启用时开始积累可用的历史证据,不是完整 TRON 归档节点,也不能凭空恢复上线前的历史资源参数。

采集必须使用由运营信任、状态一致的固定 RPC 节点。walletsolidity 读的是最后确认状态,不能用 wallet 当前状态替代。公共负载均衡服务即使前后两次确认头相同,也无法证明中间请求一定落在同一后端;生产应使用自己的固定节点或有一致性保证的服务。需要支持以下 POST 接口:

接口 用途
/walletsolidity/getnowblock 获取确认头高度、区块哈希
/walletsolidity/getaccountresource 获取该确认状态的能量/带宽全网额度和权重
/walletsolidity/getdelegatedresourcev2 读取指定地址对的锁定、非锁定 Stake 2.0 本金
/walletsolidity/getblockbynum 按高度读取确认区块及按序交易、执行回执

示例RPC地址仅表示接口来源,不能据此认为公共服务已通过生产验收。不支持某接口、返回参数不完整或限流时,采集会失败,不用空值伪造成功。

全网参数是交易所在区块执行完成后的确认状态,不是交易在区块内执行前的瞬时参数,也不是保证整个租期内用户可用资源恒定不变。资源被用户消耗、全网参数后续变化不由这份历史证明保证。

2. 业务流程

  1. 采集器读取确认头 H1,读取全网资源参数,再次读取确认头 H2。只有高度和哈希均一致才把参数绑定到该区块。变化时最多重试3次,仍不稳定则放弃这次采样。
  2. 首次采集从当前确认头开始;已有派单前基线时,从最早基线的下一高度开始。以后从数据库游标下一高度补采确认区块。
  3. 每个区块按原交易顺序解析成功的 DelegateResourceContract 和 UnDelegateResourceContract,保存全网委托/回收事件。相关交易没有完整回执时整个区块不推进。
  4. 写入区块事件、标记区块完整和推进游标在同一事务中完成;父哈希不连续、重复高度哈希不同、同高度参数冲突时拒绝覆盖。
  5. 平台派单前对候选供应钱包/接收地址/资源类型采集确认关系基线,同样使用确认头夹读。锁定与非锁定本金合计必须为0,失败时订单仍等待派单,不先发送任务再补证据。原有当前关系检查继续保留。
  6. 本地 Agent 按原流程执行,云端原有核验继续检查真实交易、owner/receiver、网络、资源类型、非锁定、SUN、回执、确认深度及当前关系。
  7. 内置服务查找目标交易之前最近的关系基线,验证从基线到交易区块的所有区块连续且事件完整,按区块高度和交易序号重放本金变化。目标交易必须真实存在于归档,不能用请求的本金代替事件。
  8. 从目标区块读取当时保存的额度和权重,返回目标交易前后本金及资源参数。云端以原有精确整数公式换算资源,达标且租期未结束时才扣款、记供应商收入。
  9. 完整历史证明进入 rent_transaction.evidence JSON,供审计查看;不会把额外证明字段当作交易表的新列写入。
派单前确认基线 B
       ↓
连续归档 B+1 … H 的成功委托/回收事件
       ↓
重放到指定交易 → baseline_sun / after_sun
       +
实时采到的区块 H 全网额度 / 权重
       ↓
完整历史证明 → 原有交付核验与资金状态机

公式保持:

交付资源 = floor(委托本金SUN × 当时全网资源额度 ÷ (当时全网资源权重 × 1,000,000))

3. 四张表的具体设计

rent_history_cursor:采集进度和网络租约

字段 类型 功能
network VARCHAR(16),主键 NILE/MAINNET,各自独立
scanned_height BIGINT,可空 已完整入库事件的最后区块高度,首次采集前为空
scanned_block_id VARCHAR(64),可空 游标区块哈希,下一块必须引用它
lease_owner VARCHAR(64),可空 本轮采集实例随机令牌
lease_until DATETIME(3),可空 以数据库 UTC 时钟计算的60秒租约
last_success_at DATETIME(3),可空 最近完整区块成功入库时间
last_error VARCHAR(255),可空 脱敏状态,不保存RPC原始异常或密钥
updated_at DATETIME(3) 最近更新UTC时间

每网络一次只允许一个实例采集。RPC结束后、落库前持锁检查租约,过期实例不得写入或推进游标;释放租约也匹配原令牌,不能释放新实例的租约。

rent_history_block:区块事实和历史参数

字段 类型 功能
network + block_height VARCHAR(16) + BIGINT,复合主键 唯一定位网络内区块
block_id / parent_id VARCHAR(64) 当前/父区块哈希,检查连续性
block_time BIGINT 链上区块时间戳,毫秒
events_complete TINYINT 1表示本块全部相关成功事件已完整归档
energy_limit / energy_weight BIGINT,可空 该区块确认状态的全网能量参数
bandwidth_limit / bandwidth_weight BIGINT,可空 该区块确认状态的全网带宽参数
parameters_at DATETIME(3),可空 实时夹读参数成功的UTC时间
created_at DATETIME(3) 首次记录UTC时间

唯一索引 (network, block_id) 防止同哈希被绑定不同高度。参数全部为空且 parameters_at 为空表示该高度资源参数漏采,即使区块交易成功补齐也不能把后来参数填入该行。

rent_history_event:全网成功 Stake 2.0 委托事件

字段 类型 功能
network + tx_id VARCHAR(16) + VARCHAR(64),复合主键 同网络交易幂等去重
block_height / tx_index BIGINT / INT 所在区块及原始交易顺序
owner_address / receiver_address VARCHAR(64) 统一小写41前缀十六进制地址
resource_type VARCHAR(16) ENERGY/BANDWIDTH,分别重放
operation VARCHAR(16) DELEGATE/UNDELEGATE
amount_sun BIGINT 正整数本金,SUN单位
locked TINYINT 是否锁定;目标交付交易必须非锁定
created_at DATETIME(3) 归档UTC时间

唯一索引 (network, block_height, tx_index) 保证位置唯一;关系重放索引为 (network, owner_address, receiver_address, resource_type, block_height)。失败交易不改变关系,不记录为成功事件。

rent_history_anchor:派单前关系基线

字段 类型 功能
network VARCHAR(16) 所属网络
owner_address / receiver_address VARCHAR(64) 规范化十六进制地址对
resource_type VARCHAR(16) 资源类型
block_height BIGINT 真实采样的确认区块高度
block_id VARCHAR(64) 基线区块哈希
balance_sun BIGINT 锁定及非锁定Stake2.0本金合计
created_at DATETIME(3) 采样UTC时间

复合主键 (network, owner_address, receiver_address, resource_type, block_height)。当前派单只接纳余额0的基线;相同主键的事实必须一致,不能修改旧基线以通过结算。

表之间及与业务表的协作

来源 去向 协作
rent_wallet、rent_order rent_history_anchor 派单前按钱包地址、接收地址、网络和资源建立基线
rent_history_cursor rent_history_block 确定下一采集高度、校验父哈希及网络租约
rent_history_block rent_history_event 同事务写入该块全部相关事件后才标记完整
rent_history_anchor + block + event 内置证明 连续区块重放出目标交易前后本金,读取目标区块参数
内置证明 rent_transaction、rent_order、rent_account、rent_ledger 复用既有核验、证据JSON、订单及资金事务,不直接修改业务余额

历史表按网络和链上事实归属,不存在 user_id;不生成普通用户任意增删改接口。采用逻辑外键,不影响旧业务表结构。

4. 安装与同进程部署

  1. 检查并备份目标数据库;新环境先执行 sql/rent_init.sql,再执行 sql/rent_history_init.sql。既有业务库只需执行后者,不要重建业务表。
  2. 使用JDK8执行 mvn -o -pl ruoyi-admin -am package -DskipTests。当前项目采用瘦JAR加外部依赖目录:部署时同时更新 ruoyi-admin/target/ruoyi-admin.jar 和 ruoyi-admin/target/lib/,不能只替换入口JAR,否则可能继续加载旧的ruoyi-system。仍使用原来的MySQL和启动方式,载入 rental profile,不需要新增独立Java进程。
  3. 设置环境变量,先在NILE验收:
RENT_ENABLED=true
RENT_HISTORY_EMBEDDED_ENABLED=true
RENT_HISTORY_NETWORKS=NILE
RENT_HISTORY_POLL_MS=1000
RENT_HISTORY_BATCH_SIZE=30
RENT_NILE_RPC=https://你的固定且状态一致的TRON-RPC
RENT_RPC_KEY=按所用RPC要求提供

RENT_HISTORY_PROBE_ADDRESS 可设置为该网络已激活的公开TRON地址,只用于读取全网额度/权重,不需要私钥,不发生扣费。默认是TRON零地址;若节点对未激活地址不返回全网参数,应配置已激活的地址。

  1. 保留原有主密钥等业务配置。内置模式不需要设置 RENT_NILE_HISTORY 或 RENT_MAINNET_HISTORY,不要把它们设为本机HTTP地址。 代码直接调用内置Java服务,避免自请求、登录认证及线程池依赖。
  2. 使用具有 rent:manage:audit 的运营账号调用 GET /rental/history/status,确认目标网络产生游标和参数高度,再测试注册、下单、委托及回收。没有新菜单授权要求,复用既有运营核对权限;业务角色不授予这个权限。
  3. 主网验收后显式配置 RENT_HISTORY_NETWORKS=NILE,MAINNET,并提供主网RPC。该配置只启用只读采集,不会打开本地Agent的广播授权。

完整配置项:

配置 默认值 说明
rental.history.embedded-enabled false 开启内置核验;采集器还要求rental.enabled=true
rental.history.networks NILE 逗号分隔,允许NILE、MAINNET;未启用网络不建立派单基线
rental.history.poll-interval-ms 1000 每网络轮询间隔,允许200至60000毫秒
rental.history.batch-size 30 每轮最多补采区块数,允许1至200
rental.history.probe-address TRON零地址 查询全网参数的公开地址
rental.history.nile/mainnet 空 保留外部历史服务兼容;内置开启时不使用

每个启用网络有独立守护线程,正常关闭时停止线程。网络间互不阻塞;多实例利用数据库租约避免重复扫描。既有Agent WebSocket单入口限制不因历史采集多实例而改变。

5. 查询接口

两接口都要求若依登录态和 rent:manage:audit,没有匿名开放,没有供应商写入历史数据的接口。

GET /rental/history/status

标准若依AjaxResult,data为每网络采集状态:network、scanned_height、scanned_block_id、last_success_at、last_error、last_parameter_height、parameter_gap_count。

parameter_gap_count 为已有完整事件区块中参数为空的区块数,不代表遗漏区块没有交易,也不代表所有订单都会受影响。应监控游标停滞、错误和参数缺口。

POST /rental/resource-proof

请求:

{
  "network": "NILE",
  "tx_id": "64位十六进制交易哈希",
  "block_height": 12345678,
  "owner": "供应商Base58地址",
  "receiver": "租赁接收Base58地址",
  "resource_type": "ENERGY"
}

成功直接返回证明对象,兼容既有数据字段,另外包含 network、block_id、owner、receiver、resource_type、anchor_height 和 source=EMBEDDED_SOLIDITY_REPLAY_V1。不会接受请求方指定的 baseline_sun、after_sun、额度或权重。

该接口用于运营排查,自动核验不通过此HTTP接口。它不是原外部无登录RPC模式的替换地址。内部本金、区块高度为精确Java long;HTTP继续复用租赁响应转换器,将BIGINT转为十进制字符串、UTC时间转为ISO8601,并设置no-store。运营脚本应保留精度,不用浮点数解析。

6. 失败处理与运维边界

场景 行为
扫描游标尚未到交易高度 核验抛出待重试错误,原有后台核验下轮继续
交易高度没有实时历史参数 不出具证明;已确认委托进入原有MANUAL_REVIEW,保留冻结资金
无交易之前的基线 不出具证明;不能用交易之后的状态倒造基线
缺区块、父哈希断裂、目标区块哈希与RPC不符 拒绝核验,保留占用和资金,等待运营检查
同区块同关系在目标交易后继续变化 若最终本金不等于目标交易后本金则拒绝证明
目标交易锁定、交易不存在、资源类型不符 拒绝证明
重放本金为负或整数溢出 拒绝证明
基线到目标区块跨度超过10000 拒绝自动重放,避免无界查询
停机后重启 从持久游标补交易;已错过的全网参数保持NULL

采集间隔小于出块间隔不保证每个高度都能捕获:节点确认头跳跃、网络慢、RPC限流和采集停机均可能造成参数缺口。生产需要低延迟且有容量保障的RPC,并根据状态接口告警;本实现不会声称公共RPC轮询等同完整历史归档节点。需要任意历史补录能力时,应另外建设可回放状态的归档节点/节点侧采集,而不是手工向历史表填当前参数。

历史数据没有自动删除策略。单网络每天约有28800个三秒区块,事件量取决于全网委托交易;应评估磁盘、备份与索引容量,保留覆盖所有在途订单和审计周期的数据,不得随意删除基线和重放区块。状态接口中的缺口统计可能随数据规模增加成本,应控制调用频率。

7. 代码与测试

文件 职责
ruoyi-system/.../rental/RentalHistoryService.java 确认状态夹读、不可变入库、网络租约、区块解析、关系重放、证明
ruoyi-system/.../rental/RentalHistoryCollector.java 独立后台线程、分网络轮询、关闭
ruoyi-system/.../rental/RentalHistoryController.java 受保护的状态/证明查询
RentalChain.java 内置/外部证明选择,原链上核验保留
RentalTasks.java 派单前采集基线,完整证明写入evidence JSON
ruoyi-system/src/test/.../rental/RentalHistoryTest.java H2真实DDL与SQL、可控RPC隔离测试

运行:

mvn -o -pl ruoyi-system -am test -Dtest=RentalHistoryTest,RentalBusinessTest,RentalRolePermissionTest -Dsurefire.failIfNoSpecifiedTests=false

Windows PowerShell需要给含逗号的 -Dtest=... 参数加引号。H2不支持MySQL的UTC_TIMESTAMP,测试仅为该时钟函数注册等价UTC实现,不改变生产SQL。

本次JDK8验证:历史服务29项全部通过,云端全回归119项无失败(4项原有外网/手动测试跳过),SQL/文档12项通过,云端package成功;已核对打包lib中的ruoyi-system与本次构建产物一致且包含历史服务类。隔离测试不等同MySQL、固定RPC以及真实NILE端到端验收;本次未执行数据库迁移或任何链上广播。