# 云端内置 TRON 历史资源证明服务 本功能随现有 Java 8 云端服务启动,复用 MySQL 和只读 TRON RPC,不需要另起一个 Java 服务,也不需要供应商运行 TRON 节点。默认关闭;不持有钱包私钥,不签名、不广播、不执行自动出金。 业务16表保持不变,新增4张独立历史表,总计20张租赁相关表。安装脚本为 [rent_history_init.sql](../../sql/rent_history_init.sql),业务基础脚本仍为 [rent_init.sql](../../sql/rent_init.sql)。没有对现有数据库执行这些脚本。 ## 1. 实现范围与可信前提 普通 HTTP RPC 不支持任意历史高度的完整账户/全网资源状态。内置实现采用“FullNode实时状态采样、等待确认 + 完整区块事件归档 + 地址对重放”,从启用时开始积累可用的历史证据,不是完整 TRON 归档节点,也不能凭空恢复上线前的历史资源参数。 采集必须使用**由运营信任、状态一致的固定 RPC 节点**。Nile公共服务没有`/walletsolidity/getaccountresource`,不能用该路径,也不能把最新参数标记为当前确认头参数。当前实现先用最新头夹读绑定采样高度,待该高度进入确认链并核对哈希后才归档。公共负载均衡服务即使前后两次头相同,也不能证明中间请求来自同一后端;生产应使用自己的固定节点或有一致性保证的服务。需要支持以下 POST 接口: | 接口 | 用途 | | --- | --- | | `/walletsolidity/getnowblock` | 获取确认头高度、区块哈希 | | `/wallet/getnowblock` | FullNode最新头,夹读以绑定实时采样高度 | | `/wallet/getaccountresource` | 该最新高度的能量/带宽全网额度和权重 | | `/wallet/getdelegatedresourcev2` | 该最新高度指定地址对的 Stake 2.0 本金 | | `/walletsolidity/getblockbynum` | 按高度读取确认区块及按序交易、执行回执 | 示例RPC地址仅表示接口来源,不能据此认为公共服务已通过生产验收。不支持某接口、返回参数不完整或限流时,采集会失败,不用空值伪造成功。 全网参数是**交易所在区块执行完成后的确认状态**,不是交易在区块内执行前的瞬时参数,也不是保证整个租期内用户可用资源恒定不变。资源被用户消耗、全网参数后续变化不由这份历史证明保证。 ## 2. 业务流程 1. 采集器读取FullNode最新头 H1,读取全网资源参数及所需关系,再次读取最新头 H2。仅高度和哈希一致才绑定该高度。最多尝试3次。不立即写入历史证据;内存保留最多10000份、最长10分钟的未确认采样,每轮继续采集后续高度。确认头到达采样高度后,使用确认区块查询核对原采样哈希,再归档。分叉、超时或重启丢失的采样不补造。 2. 首次采集从当前确认头开始;已有派单前基线时,从最早基线的下一高度开始。以后从数据库游标下一高度补采确认区块。 3. 每个区块按原交易顺序解析成功的 `DelegateResourceContract` 和 `UnDelegateResourceContract`,保存全网委托/回收事件。相关交易没有完整回执时整个区块不推进。 4. 写入区块事件、标记区块完整和推进游标在同一事务中完成;父哈希不连续、重复高度哈希不同、同高度参数冲突时拒绝覆盖。 5. 平台派单前对候选供应钱包/接收地址/资源类型采集关系基线,同样使用最新头夹读并等待对应区块确认。锁定与非锁定本金合计必须为0,等待确认时订单仍等待派单,后续调度重试,不先发送任务再补证据。原有当前关系检查继续保留。首次启动需要等待确认预热;不要因此关闭确认校验。 6. 本地 Agent 按原流程执行,云端原有核验继续检查真实交易、owner/receiver、网络、资源类型、非锁定、SUN、回执、确认深度及当前关系。 7. 内置服务查找目标交易之前最近的关系基线,验证从基线到交易区块的所有区块连续且事件完整,按区块高度和交易序号重放本金变化。目标交易必须真实存在于归档,不能用请求的本金代替事件。 8. 从目标区块读取当时保存的额度和权重,返回目标交易前后本金及资源参数。云端以原有精确整数公式换算资源,达标且租期未结束时才扣款、记供应商收入。 9. 完整历史证明进入 `rent_transaction.evidence` JSON,供审计查看;不会把额外证明字段当作交易表的新列写入。 ```text 派单前确认基线 B ↓ 连续归档 B+1 … H 的成功委托/回收事件 ↓ 重放到指定交易 → baseline_sun / after_sun + 实时采到的区块 H 全网额度 / 权重 ↓ 完整历史证明 → 原有交付核验与资金状态机 ``` 公式保持: ```text 交付资源 = 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验收: ```text 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零地址;若节点对未激活地址不返回全网参数,应配置已激活的地址。 4. 保留原有主密钥等业务配置。**内置模式不需要设置 `RENT_NILE_HISTORY` 或 `RENT_MAINNET_HISTORY`,不要把它们设为本机HTTP地址。** 代码直接调用内置Java服务,避免自请求、登录认证及线程池依赖。 5. 使用具有 `rent:manage:audit` 的运营账号调用 `GET /rental/history/status`,确认目标网络产生游标和参数高度,再测试注册、下单、委托及回收。没有新菜单授权要求,复用既有运营核对权限;业务角色不授予这个权限。 6. 主网验收后显式配置 `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 请求: ```json { "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隔离测试 | 运行: ```shell 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端到端验收;本次未执行数据库迁移或任何链上广播。