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. 业务流程
- 采集器读取确认头 H1,读取全网资源参数,再次读取确认头 H2。只有高度和哈希均一致才把参数绑定到该区块。变化时最多重试3次,仍不稳定则放弃这次采样。
- 首次采集从当前确认头开始;已有派单前基线时,从最早基线的下一高度开始。以后从数据库游标下一高度补采确认区块。
- 每个区块按原交易顺序解析成功的
DelegateResourceContract和UnDelegateResourceContract,保存全网委托/回收事件。相关交易没有完整回执时整个区块不推进。 - 写入区块事件、标记区块完整和推进游标在同一事务中完成;父哈希不连续、重复高度哈希不同、同高度参数冲突时拒绝覆盖。
- 平台派单前对候选供应钱包/接收地址/资源类型采集确认关系基线,同样使用确认头夹读。锁定与非锁定本金合计必须为0,失败时订单仍等待派单,不先发送任务再补证据。原有当前关系检查继续保留。
- 本地 Agent 按原流程执行,云端原有核验继续检查真实交易、owner/receiver、网络、资源类型、非锁定、SUN、回执、确认深度及当前关系。
- 内置服务查找目标交易之前最近的关系基线,验证从基线到交易区块的所有区块连续且事件完整,按区块高度和交易序号重放本金变化。目标交易必须真实存在于归档,不能用请求的本金代替事件。
- 从目标区块读取当时保存的额度和权重,返回目标交易前后本金及资源参数。云端以原有精确整数公式换算资源,达标且租期未结束时才扣款、记供应商收入。
- 完整历史证明进入
rent_transaction.evidenceJSON,供审计查看;不会把额外证明字段当作交易表的新列写入。
派单前确认基线 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. 安装与同进程部署
- 检查并备份目标数据库;新环境先执行
sql/rent_init.sql,再执行sql/rent_history_init.sql。既有业务库只需执行后者,不要重建业务表。 - 使用JDK8执行
mvn -o -pl ruoyi-admin -am package -DskipTests。当前项目采用瘦JAR加外部依赖目录:部署时同时更新ruoyi-admin/target/ruoyi-admin.jar和ruoyi-admin/target/lib/,不能只替换入口JAR,否则可能继续加载旧的ruoyi-system。仍使用原来的MySQL和启动方式,载入rentalprofile,不需要新增独立Java进程。 - 设置环境变量,先在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零地址;若节点对未激活地址不返回全网参数,应配置已激活的地址。
- 保留原有主密钥等业务配置。内置模式不需要设置
RENT_NILE_HISTORY或RENT_MAINNET_HISTORY,不要把它们设为本机HTTP地址。 代码直接调用内置Java服务,避免自请求、登录认证及线程池依赖。 - 使用具有
rent:manage:audit的运营账号调用GET /rental/history/status,确认目标网络产生游标和参数高度,再测试注册、下单、委托及回收。没有新菜单授权要求,复用既有运营核对权限;业务角色不授予这个权限。 - 主网验收后显式配置
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端到端验收;本次未执行数据库迁移或任何链上广播。