自行建设,补充这部分功能,给出具体的表设计和代码实现,同云端服务端一起部署
This commit is contained in:
1 parent
cab8056412
commit
b3419aa389
15 files changed
+1369
-14
No files matched your search
@@ -0,0 +1,228 @@
|
||||
# 云端内置 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 不支持任意历史高度的完整账户/全网资源状态。内置实现采用“实时确认状态采集 + 完整区块事件归档 + 地址对重放”,从启用时开始积累可用的历史证据,不是完整 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,供审计查看;不会把额外证明字段当作交易表的新列写入。
|
||||
|
||||
```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端到端验收;本次未执行数据库迁移或任何链上广播。
|
||||
Reference in new issue
Block a user