From 922a850fbd1b640eb72b83b31b8a46d6f66d8a98 Mon Sep 17 00:00:00 2001 From: wangzichichi <280474930@163.com> Date: Thu, 9 Apr 2026 20:18:26 +0800 Subject: [PATCH] docs: streamline docs structure and improve maintainability --- README.md | 2 - README_CN.md | 244 ------ docs/FAQ.md | 141 ++-- docs/REFACTORING_REPORT.md | 518 ------------- docs/REVIEW_CHECKLIST.md | 83 --- docs/SETUP.md | 1 - docs/SETUP_CN.md | 225 ------ docs/readme_single_node.md | 42 +- docs/test-network-research.md | 254 ------- docs/worklog-2026-04-04.md | 198 ----- docs/worklog-2026-04-05.md | 254 ------- ...inese version of TRON Protocol document.md | 696 ------------------ testcase/config/checkstyle/checkStyle.xml | 237 ------ 13 files changed, 90 insertions(+), 2805 deletions(-) delete mode 100644 README_CN.md delete mode 100644 docs/REFACTORING_REPORT.md delete mode 100644 docs/REVIEW_CHECKLIST.md delete mode 100644 docs/SETUP_CN.md delete mode 100644 docs/test-network-research.md delete mode 100644 docs/worklog-2026-04-04.md delete mode 100644 docs/worklog-2026-04-05.md delete mode 100644 protocol/src/main/protos/Chinese version of TRON Protocol document.md delete mode 100644 testcase/config/checkstyle/checkStyle.xml diff --git a/README.md b/README.md index d7d0b114..e7d642ab 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,5 @@ # TRON System-Test -**English** | [中文](README_CN.md) [![CI](https://github.com/tronprotocol/system-test/actions/workflows/ci.yml/badge.svg)](https://github.com/tronprotocol/system-test/actions/workflows/ci.yml) [![Coverage](https://github.com/tronprotocol/system-test/actions/workflows/coverage.yml/badge.svg)](https://github.com/tronprotocol/system-test/actions/workflows/coverage.yml) @@ -220,7 +219,6 @@ For java-tron CI integration, use `config-system-test.conf` with fast test param | Document | Description | |----------|-------------| | [Setup Guide](docs/SETUP.md) | 5-minute quick start, private network setup, tool installation | -| [安装指南 (中文)](docs/SETUP_CN.md) | 中文版快速开始、工具安装、国内镜像 | | [Architecture](docs/ARCHITECTURE.md) | Test infrastructure, base classes, execution model | | [Network Topology](docs/NETWORK.md) | Single/multi-node setup, port mapping, Docker | | [Style Guide](docs/STYLE_GUIDE.md) | Code conventions, naming rules, assertion patterns | diff --git a/README_CN.md b/README_CN.md deleted file mode 100644 index c228c8b1..00000000 --- a/README_CN.md +++ /dev/null @@ -1,244 +0,0 @@ -# TRON System-Test - -[English](README.md) | **中文** - -[![CI](https://github.com/tronprotocol/system-test/actions/workflows/ci.yml/badge.svg)](https://github.com/tronprotocol/system-test/actions/workflows/ci.yml) -[![Coverage](https://github.com/tronprotocol/system-test/actions/workflows/coverage.yml/badge.svg)](https://github.com/tronprotocol/system-test/actions/workflows/coverage.yml) -[![License: LGPL v3](https://img.shields.io/badge/License-LGPL%20v3-blue.svg)](LICENSE) - -[java-tron](https://github.com/tronprotocol/java-tron)（GreatVoyage-v4.8.1 Democritus）的系统级集成测试套件。覆盖全部 34 种系统合约、gRPC/HTTP/JSON-RPC API、TVM 指令、Stake 2.0、多签、DEX 和隐私功能，通过端对端测试验证运行中的 TRON 节点。 - -> 本仓库中的所有私钥均为随机生成的测试密钥，不包含任何敏感信息。 - -## 技术栈 - -| 组件 | 版本 | 说明 | -|------|------|------| -| Java | 1.8 (x86) / 17 (ARM) | 与 java-tron 保持一致 | -| Gradle | 7.6.4 (wrapper) | 与 java-tron 保持一致 | -| TestNG | 6.14.3 | 主测试框架 | -| Protobuf | 3.25.5 | 协议序列化 | -| gRPC | 1.60.0 | 节点通信 | -| BouncyCastle | 1.78.1 | 密码学 | -| JaCoCo | 0.8.11 | 代码覆盖率 | -| jqwik | 1.7.4 | 属性测试 | - -## 项目结构 - -``` -system-test/ -├── protocol/ # Protobuf 定义 + gRPC 代码生成 -├── testcase/ # 主测试模块 (698 个测试类) -│ ├── build.gradle # 测试依赖与任务定义 -│ └── src/test/ -│ ├── java/stest/tron/wallet/ -│ │ ├── account/ # 账户功能测试 -│ │ ├── transfer/ # TRX 转账测试 -│ │ ├── block/ # 区块操作测试 -│ │ ├── witness/ # SR/见证人测试 -│ │ ├── committee/ # 治理提案测试 -│ │ ├── multisign/ # 多签测试 -│ │ ├── contract/ # 智能合约测试 (linkage + scenario) -│ │ ├── exchangeandtoken/ # DEX & TRC-10 测试 -│ │ ├── dailybuild/ # 日常回归测试 (42 个子包) -│ │ │ ├── account/ # Freeze V2、委托、资源 -│ │ │ ├── http/ # HTTP API 测试 -│ │ │ ├── jsonrpc/ # JSON-RPC 接口测试 -│ │ │ ├── tvmnewcommand/ # TVM 新指令测试 -│ │ │ ├── security/ # 安全/攻击模拟测试 -│ │ │ ├── consensus/ # DPoS 共识测试 -│ │ │ ├── network/ # P2P 网络测试 -│ │ │ ├── performance/ # 性能基准测试 -│ │ │ └── ... # 更多子包 -│ │ ├── fulltest/ # 完整集成测试 -│ │ ├── onlinestress/ # 压力测试 -│ │ └── common/client/ # 共享工具 -│ │ ├── utils/ -│ │ │ ├── PublicMethod.java # 核心测试辅助 (已委托至 Helper) -│ │ │ ├── AccountHelper.java # 账户相关操作 -│ │ │ ├── ContractHelper.java # 合约相关操作 -│ │ │ ├── ResourceHelper.java # 资源相关操作 -│ │ │ ├── TronBaseTest.java # 测试基类 -│ │ │ ├── TronConstants.java # 常量定义 -│ │ │ ├── TestAccountFactory.java # 测试账户工厂 -│ │ │ ├── FailureClassifier.java # 失败自动分类 -│ │ │ └── ... -│ └── resources/ -│ ├── testng.xml # 核心测试套件 (4 线程) -│ ├── daily-build.xml # 日常回归套件 -│ ├── testng.conf # 主配置 (节点地址、测试账户) -│ └── soliditycode/ # 1259 个 Solidity 测试合约 -├── docker/ # Docker 环境 -└── docs/ # 文档 -``` - -## 前置条件 - -- **JDK 8**（x86_64）或 **JDK 17**（ARM64），推荐 Temurin 发行版 -- **Solidity 编译器**：tronprotocol fork solc v0.8.26，放在 `solcDIR/solc`（可通过 `./gradlew downloadTools` 自动下载） -- **运行中的 TRON 节点**：私有网络、Nile 测试网或 Shasta 测试网 - -### 测试网络选项 - -| 网络 | 用途 | 文档 | -|------|------|------| -| **私有网络** | 本地开发，快速迭代 | [搭建指南](https://tronprotocol.github.io/documentation-en/using_javatron/private_network/) | -| **Nile 测试网** | 前沿功能（领先于主网） | [水龙头: nileex.io](https://nileex.io) | -| **Shasta 测试网** | 参数与主网一致 | 仅通过 TronGrid 访问 | - -## 快速开始 - -### 运行核心测试套件（4 线程并行） -```bash -./gradlew stest -``` - -### 运行日常回归构建（8 线程并行 + 串行） -```bash -./gradlew dailyBuild -``` - -### 运行冒烟测试（快速验证，约 5 分钟） -```bash -./gradlew smokeTest -``` - -### 运行仅单节点测试（无需多节点环境） -```bash -./gradlew singleNodeBuild -``` - -### 运行属性测试（Fuzz 测试） -```bash -./gradlew fuzzTest -``` -使用 [jqwik](https://jqwik.net/) 对 Base58、ByteArray、Sha256、ECKey 和地址验证进行随机输入测试。 - -### 工具自动下载 - -首次运行时自动下载 grpcurl 和 solc： -```bash -./gradlew downloadTools -``` - -> **国内网络提示**：如果 GitHub 下载超时，请参考 [安装指南](docs/SETUP_CN.md#手动安装网络受限环境) 中的手动安装方式。 - -## 本地搭建 java-tron 环境运行 DailyBuild - -如果需要在本地运行 `dailyBuild` 测试套件，需要搭建一个由 **2 个 Witness FullNode + 1 个 Solidity 节点** 组成的私有网络。项目已提供预配置文件： - -``` -testcase/src/test/resources/dailybuild-witness-conf/ -├── witness1_config.conf # Witness FullNode 1（出块节点，needSyncCheck=false） -├── witness2_config.conf # Witness FullNode 2（出块节点，needSyncCheck=true，RocksDB + keystore） -└── solidity_config.conf # Solidity 节点（无 witness 密钥） -``` - -### 端口映射 - -| 节点 | P2P 端口 | gRPC | HTTP Full | HTTP Solidity | HTTP PBFT | JSON-RPC Full | Prometheus | -|------|----------|------|-----------|---------------|-----------|---------------|------------| -| Witness 1 | 18889 | 50051 | 8090 | 8091 | 8098 | 50545 | 9528 | -| Witness 2 | 18892 | 50052 | 8093 | 8094 | 8099 | 50546 | 9527 | -| Solidity | 18893 | 50053 | 8096 | 8097 | — | 50547 | 9529 | - -### 必需工具 - -- **Solidity 编译器 (solc)**：从 [tronprotocol/solidity/releases](https://github.com/tronprotocol/solidity/releases) 下载 tronprotocol 分支版本，将二进制文件放入 `solcDIR/` 目录，文件**必须**命名为 `solc`。当前使用版本：`v0.8.26`。 -- **gRPCurl**：从 [fullstorydev/grpcurl/releases](https://github.com/fullstorydev/grpcurl/releases) 下载，将二进制文件放入 `gRPCurl/` 目录，文件**必须**命名为 `grpcurl`。 -- **Slack 通知（可选）**：在测试执行环境中配置自定义 `slack` 命令，可自动接收失败用例的通知。 - -### MongoDB 事件插件（Witness 2 必需） - -Witness 2 配置了 MongoDB 事件订阅，启动前需要： - -1. 启动 MongoDB 服务 -2. 从 [tronprotocol/event-plugin](https://github.com/tronprotocol/event-plugin) 下载事件插件 -3. 编辑 `witness2_config.conf`，配置以下字段： - - `event.subscribe.path` — 插件 zip 的绝对路径（如 `/path/to/plugin-mongodb-1.0.0.zip`） - - `event.subscribe.server` — MongoDB 地址（如 `172.17.0.1:27017`） - - `event.subscribe.dbconfig` — `数据库名|用户名|密码|版本号` - -### 启动节点 - -```bash -# 先编译 java-tron -cd /path/to/java-tron -./gradlew build -x test - -# 启动 Witness 1（首节点，负责出块） -java -jar build/libs/FullNode.jar --witness --es -c witness1_config.conf - -# 启动 Witness 2（从 Witness 1 同步后参与出块） -java -jar build/libs/FullNode.jar --witness --es -c witness2_config.conf - -# 启动 Solidity 节点（同步已确认区块） -java -jar build/libs/FullNode.jar --solidity -c solidity_config.conf -``` - -> `--es` 启用事件订阅服务。`--solidity` 以 Solidity 模式启动节点。 - -3 个节点全部启动并正常出块后，即可运行 dailyBuild 套件： - -```bash -./gradlew dailyBuild -``` - -> 完整环境搭建指南（JDK、solc、grpcurl）请参考 [安装指南](docs/SETUP_CN.md)。 - -## 与 java-tron CI 的集成 - -本仓库由 java-tron 的 CI 流水线通过 [`system-test.yml`](https://github.com/tronprotocol/java-tron/blob/develop/.github/workflows/system-test.yml) 自动调用： - -1. java-tron CI 构建 `FullNode.jar` -2. 检出本仓库的 `release_workflow` 分支 -3. 将 `config-system-test.conf` 复制到 java-tron -4. 以后台进程启动 FullNode（`--witness` 模式） -5. 轮询 `http://localhost:8090/wallet/getblockbynum?num=1` 直到就绪（最长 5 分钟） -6. 执行 `./gradlew --info stest --no-daemon` -7. 超时时间：60 分钟 - -## 配置 - -测试配置从 `testcase/src/test/resources/testng.conf`（HOCON 格式）加载： - -- **节点地址**：`fullnode.ip.list`、`solidityNode.ip.list`、`httpnode` -- **测试账户**：`foundationAccount.key1`、`witness.key1` 到 `witness.key5` -- **端口**：gRPC (50051)、HTTP (8090)、JSON-RPC (8545) - -## 相关仓库 - -| 仓库 | 说明 | -|------|------| -| [java-tron](https://github.com/tronprotocol/java-tron) | TRON 全节点实现 | -| [protocol](https://github.com/tronprotocol/protocol) | Protobuf API 与消息定义 | -| [tron-docker](https://github.com/tronprotocol/tron-docker) | TRON 节点 Docker 自动化 | -| [tips](https://github.com/tronprotocol/tips) | TRON 改进提案 (127 个 TIP) | -| [documentation-en](https://github.com/tronprotocol/documentation-en) | 官方英文文档 | -| [trident](https://github.com/tronprotocol/trident) | 轻量级 Java SDK | -| [tronweb](https://github.com/tronprotocol/tronweb) | JavaScript/TypeScript API 库 | - -## 文档 - -| 文档 | 说明 | -|------|------| -| [安装指南 (中文)](docs/SETUP_CN.md) | 5 分钟快速开始、私有网络搭建、工具安装 | -| [安装指南 (英文)](docs/SETUP.md) | Setup guide in English | -| [架构](docs/ARCHITECTURE.md) | 测试基础设施、基类、执行模型 | -| [网络拓扑](docs/NETWORK.md) | 单节点/多节点组网、端口映射、Docker 环境 | -| [代码规范](docs/STYLE_GUIDE.md) | 代码约定、命名规则、断言模式 | -| [常见问题](docs/FAQ.md) | 常见问题与解决方案 | -| [贡献指南](CONTRIBUTING.md) | 分支命名、提交格式、PR 流程 | - -## 参与贡献 - -初次接触？以下是参与方式： - -- **新手任务**：浏览 [精选入门任务](docs/GOOD_FIRST_ISSUES.md) 或在 GitHub 上按 [`good first issue`](https://github.com/tronprotocol/system-test/labels/good%20first%20issue) 筛选 -- **贡献指南**：阅读 [CONTRIBUTING.md](CONTRIBUTING.md) 了解开发环境搭建、代码规范和 PR 流程 -- **报告 Bug**：提交 [Bug 报告](https://github.com/tronprotocol/system-test/issues/new?template=bug_report.md)，附上复现步骤和环境信息 -- **贡献者**：查看 [CONTRIBUTORS.md](CONTRIBUTORS.md) 了解贡献者列表和认可方式 - -## 许可证 - -本项目采用 [GNU 宽通用公共许可证 v3.0](LICENSE) 授权。 diff --git a/docs/FAQ.md b/docs/FAQ.md index 48dda913..5d111c77 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -1,55 +1,54 @@ -# FAQ — 常见问题 - -[English](#faq) | 中文 +# FAQ --- -## 1. 启动节点后区块号一直为 0 +## 1. Block number stays at 0 after starting the node -**原因**：见证人私钥未正确配置，或 `needSyncCheck` 设置错误。 +**Cause**: Witness private keys are not configured correctly, or `needSyncCheck` is set incorrectly. -**解决方案**： +**Solution**: ```bash -# 检查 config.conf 中： +# Check config.conf: localwitness = [ 369F095838EB6EED45D4F6312AF962D5B9DE52927DA9F04174EE49F9AF54BC77, 291C233A5A7660FB148BAE07FCBCF885224F2DF453239BD983F859E8E5AA4602 ] block { - needSyncCheck = false # 单节点必须设为 false + needSyncCheck = false # Must be false for single-node setup } -# 确认私钥对应的地址在 genesis.block.witnesses 中 +# Confirm that the addresses corresponding to the private keys +# are listed in genesis.block.witnesses ``` --- -## 2. 测试报 "Connection refused" / "UNAVAILABLE" +## 2. Tests report "Connection refused" / "UNAVAILABLE" -**原因**：java-tron 节点未启动，或端口与 `testng.conf` 不匹配。 +**Cause**: The java-tron node is not running, or the ports do not match those in `testng.conf`. -**解决方案**： +**Solution**: ```bash -# 1. 确认节点正在运行 +# 1. Verify the node is running curl -s http://127.0.0.1:8090/wallet/getnowblock | head -1 -# 2. 如果端口被占用 +# 2. If the port is occupied lsof -i :50051 lsof -i :8090 kill -9 -# 3. 检查 testng.conf 的端口与 config.conf 是否一致 +# 3. Check that testng.conf ports match config.conf grep "50051" testcase/src/test/resources/testng.conf ``` --- -## 3. grpcurl 测试全部失败 +## 3. All grpcurl tests fail -**原因**：java-tron 的 gRPC Reflection 服务默认关闭。 +**Cause**: The gRPC Reflection service in java-tron is disabled by default. -**解决方案**：在 `config.conf` 的 `node.rpc` 段添加： +**Solution**: Add the following to the `node.rpc` section in `config.conf`: ```hocon node { rpc { @@ -57,26 +56,26 @@ node { } } ``` -重启节点后生效。 +Restart the node for the change to take effect. --- -## 4. 合约部署失败 / solc 报错 +## 4. Contract deployment fails / solc errors -**原因**：solc 未安装、权限不足、或使用了标准 Ethereum 版 solc。 +**Cause**: solc is not installed, lacks execution permission, or is the standard Ethereum version of solc. -**解决方案**： +**Solution**: ```bash -# 检查 solc 是否存在且可执行 +# Check that solc exists and is executable ls -la solcDIR/solc chmod +x solcDIR/solc -# 确认是 tronprotocol fork 版本 +# Verify it is the tronprotocol fork version ./solcDIR/solc --version -# 应输出: solc.tron ... Version: 0.8.26+... -# 如果显示 "solc, the solidity compiler"（没有 .tron），则版本不对 +# Expected output: solc.tron ... Version: 0.8.26+... +# If it shows "solc, the solidity compiler" (without .tron), the version is wrong -# 重新下载正确版本 +# Re-download the correct version # macOS: wget -O solcDIR/solc https://github.com/tronprotocol/solidity/releases/download/tv_0.8.26/solc-macos # Linux: @@ -86,25 +85,25 @@ chmod +x solcDIR/solc --- -## 5. `downloadTools` 下载超时（国内网络） +## 5. `downloadTools` times out (slow network) -**原因**：GitHub Release 在国内访问较慢。 +**Cause**: GitHub Releases may be slow to access depending on your region. -**解决方案**：手动下载后放到指定目录： +**Solution**: Download manually and place the files in the designated directories: ```bash -# grpcurl — 放到 gRPCurl/grpcurl -# 下载地址: https://github.com/fullstorydev/grpcurl/releases/tag/v1.8.9 +# grpcurl — place at gRPCurl/grpcurl +# Download: https://github.com/fullstorydev/grpcurl/releases/tag/v1.8.9 -# solc — 放到 solcDIR/solc -# 下载地址: https://github.com/tronprotocol/solidity/releases/tag/tv_0.8.26 +# solc — place at solcDIR/solc +# Download: https://github.com/tronprotocol/solidity/releases/tag/tv_0.8.26 -# 放好后 Gradle 会自动检测到，不再重复下载 +# Once placed, Gradle will detect them automatically and skip re-downloading ``` -如果有代理，也可以设置 Gradle 代理： +If you have a proxy, you can also configure Gradle proxy settings: ```bash -# 在 gradle.properties 中添加 +# Add to gradle.properties systemProp.http.proxyHost=127.0.0.1 systemProp.http.proxyPort=7890 systemProp.https.proxyHost=127.0.0.1 @@ -113,23 +112,23 @@ systemProp.https.proxyPort=7890 --- -## 6. Solidity 查询始终返回空 +## 6. Solidity queries always return empty -**原因**：单节点环境无法产生 solidified block（需要 2/3 见证人确认）。 +**Cause**: A single-node environment cannot produce solidified blocks (requires 2/3 witness confirmation). -**解决方案**： -- 单节点测试使用 `./gradlew singleNodeBuild`，自动跳过需要 Solidity 的测试 -- 或搭建双节点环境（参考 [NETWORK.md](NETWORK.md)），实现真正的 DPoS 共识 +**Solution**: +- For single-node testing, use `./gradlew singleNodeBuild`, which automatically skips tests that require Solidity +- Or set up a dual-node environment (see [NETWORK.md](NETWORK.md)) for real DPoS consensus -单节点下可以使用 PBFT 端口（`:50071`）获取近似 solidified 的数据。 +On a single node, you can use the PBFT port (`:50071`) to obtain approximately solidified data. --- -## 7. MongoEventQuery 测试全部跳过 +## 7. All MongoEventQuery tests are skipped -**原因**：MongoDB 未安装。这是**正常行为**，不影响其他测试。 +**Cause**: MongoDB is not installed. This is **expected behavior** and does not affect other tests. -**解决方案**（可选）： +**Solution** (optional): ```bash # macOS brew tap mongodb/brew && brew install mongodb-community @@ -139,27 +138,27 @@ brew services start mongodb-community sudo apt install mongodb sudo systemctl start mongodb -# 确认 testng.conf 中的 MongoDB 地址 +# Verify the MongoDB address in testng.conf mongonode.ip.list = ["127.0.0.1:27017"] ``` --- -## 8. 编译报 "unsupported class file version" +## 8. Build reports "unsupported class file version" -**原因**：使用了错误的 JDK 版本。 +**Cause**: An incorrect JDK version is being used. -**解决方案**： +**Solution**: ```bash -# 确认 JDK 版本 +# Check JDK version java -version -# 应为 1.8.x（x86 平台）或 17.x（ARM 平台） +# Should be 1.8.x (x86 platform) or 17.x (ARM platform) -# macOS 安装 JDK 8 +# macOS — install JDK 8 brew install --cask temurin@8 export JAVA_HOME=$(/usr/libexec/java_home -v 1.8) -# 多版本共存时切换 +# Switch between multiple versions # macOS: export JAVA_HOME=$(/usr/libexec/java_home -v 1.8) # Linux: @@ -168,27 +167,27 @@ sudo update-alternatives --config java --- -## 9. dailyBuild 内存不足 (OOM) +## 9. dailyBuild runs out of memory (OOM) -**原因**：dailyBuild 默认 `maxHeapSize = 2048m`，机器内存不足。 +**Cause**: dailyBuild defaults to `maxHeapSize = 2048m`, which may exceed available memory. -**解决方案**： +**Solution**: ```bash -# 方案 1：用单节点构建代替 +# Option 1: Use single-node build instead ./gradlew singleNodeBuild -# 方案 2：减少线程数（编辑 testcase/build.gradle） -# threadCount 从 2 改为 1 +# Option 2: Reduce thread count (edit testcase/build.gradle) +# Change threadCount from 2 to 1 -# 方案 3：增加 Gradle JVM 内存（编辑 gradle.properties） +# Option 3: Increase Gradle JVM memory (edit gradle.properties) org.gradle.jvmargs=-Xmx3072m ``` --- -## 10. 失败报告中如何区分环境问题和真正的 bug？ +## 10. How to distinguish environment issues from real bugs in failure reports? -`dailyBuild` 结束后会自动打印 **Failure Classification Summary**： +After `dailyBuild` completes, it automatically prints a **Failure Classification Summary**: ``` === Failure Classification Summary === @@ -199,19 +198,19 @@ org.gradle.jvmargs=-Xmx3072m BUG: 2 (SecurityOverflowTest.test01 ...) ──────────────────────── Total Failures: 234 - Actionable Bugs: 2 <<< 只需关注这里 + Actionable Bugs: 2 <<< Focus only on this ======================================= ``` -- **ENV_*** — 环境问题，搭好环境就能过 -- **FLAKY** — 已知不稳定测试，标注了 `@Flaky` -- **BUG** — 真正需要修复的问题 +- **ENV_***: Environment issues — will pass once the environment is properly set up +- **FLAKY**: Known unstable tests, annotated with `@Flaky` +- **BUG**: Real issues that need to be fixed --- -## 还有问题？ +## Still have questions? -- [TRON 开发者文档](https://tronprotocol.github.io/documentation-en/) -- [TRON 改进提案 (TIPs)](https://github.com/tronprotocol/tips) +- [TRON Developer Documentation](https://tronprotocol.github.io/documentation-en/) +- [TRON Improvement Proposals (TIPs)](https://github.com/tronprotocol/tips) - [java-tron Issues](https://github.com/tronprotocol/java-tron/issues) -- [网络拓扑指南](NETWORK.md) — 详细的组网和端口配置 +- [Network Topology Guide](NETWORK.md) — Detailed networking and port configuration diff --git a/docs/REFACTORING_REPORT.md b/docs/REFACTORING_REPORT.md deleted file mode 100644 index 0c8d74e5..00000000 --- a/docs/REFACTORING_REPORT.md +++ /dev/null @@ -1,518 +0,0 @@ -# TRON System-Test 重构报告 - -**时间跨度**: 2026-04-01 ~ 2026-04-04（4 天） -**基线分支**: `XvZipo/solidity_0.8.27` -**原始评分**: 4.5/10 → **当前评分**: ~7.5/10 -**目标**: 8 大领域、3 阶段、12 个月路线图的落地执行 - ---- - -## 目录 - -- [一、前置验证](#一前置验证) -- [二、Phase 1 — 基础治理](#二phase-1--基础治理) -- [三、Phase 2 — 架构升级](#三phase-2--架构升级) -- [四、Phase 3 — 能力补全](#四phase-3--能力补全) -- [五、命名规范全面整改](#五命名规范全面整改) -- [六、量化指标](#六量化指标) -- [七、未完成项与后续规划](#七未完成项与后续规划) -- [八、文件变更汇总](#八文件变更汇总) - ---- - -## 一、前置验证 - -### 1.1 TronBaseTest 基类重构（前序工作） - -对 **562 个测试文件**进行基类抽取重构，统一 gRPC channel 管理、foundation/witness 账户加载、配置读取。 - -- 新建 `TronBaseTest` 抽象基类，提供 `channelFull`、`blockingStubFull`、`foundationAddress`、`witnessAddress` 等通用字段 -- 562 个测试类去除冗余的 channel 创建 / 关闭代码 -- 提供 `initSolidityChannel()`、`initPbftChannel()` 可选扩展 -- 提供 `generateAccount()` 工具方法 - -### 1.2 dailyBuild 验证（2026-04-03） - -在单节点私有网络上完整运行 dailyBuild，验证重构零引入 bug。 - -| 指标 | 数值 | -|------|------| -| 总用例 | 1685 | -| 通过 | ~1242 | -| 失败 | 112 (6.6%) | -| 跳过 | 331 | -| **重构引入的 bug** | **0** | - -**112 个失败全为环境因素**：单节点无 solidity/PBFT 端口(29)、多签并发限制(18)、配置差异(18)、MongoDB 未安装(16)、Shield 环境(10) 等。 - -### 1.3 踩坑：gRPC Reflection 配置 - -- java-tron 的 `node.rpc.reflectionService` 默认 false，导致 grpcurl 测试全挂 -- 通过反编译 `RpcService.class` 字节码定位配置项 -- 修复：`config.conf` 中 `node.rpc` 段添加 `reflectionService = true` - ---- - -## 二、Phase 1 — 基础治理 - -### 2.1 文档体系建设 - -| 文件 | 类型 | 说明 | -|------|------|------| -| `README.md` | 增强 | CI/Coverage badge、Documentation 导航表、项目结构、社区版块 | -| `CONTRIBUTING.md` | 增强 | Conventional Commits、分支命名、PR 模板、测试编写模板 | -| `CONTRIBUTORS.md` | 新建 | 贡献者指南 + 贡献者列表模板 | -| `docs/ARCHITECTURE.md` | 已有 | 基类层次、Helper 分解、执行模型 | -| `docs/SETUP.md` | 新建 | 5 分钟快速开始、私有网络配置、工具安装、troubleshooting | -| `docs/STYLE_GUIDE.md` | 新建 | 命名规范、测试结构模板、断言最佳实践、代码格式 | -| `docs/NETWORK.md` | 新建 | 组网拓扑(ASCII图)、端口映射表、Docker 环境、config 示例 | -| `docs/GOOD_FIRST_ISSUES.md` | 新建 | 24 个具体可操作的新手任务 | -| `docs/TIP-TEST-MAPPING.md` | 新建 | TIP 与测试用例映射关系 | -| `.github/PULL_REQUEST_TEMPLATE.md` | 已有 | PR checklist | -| `.github/ISSUE_TEMPLATE/` | 已有+新建 | bug_report + new_test + good_first_issue 模板 | - -### 2.2 CI/CD 门禁 - -| 工作流 | 文件 | 触发条件 | 内容 | -|--------|------|---------|------| -| 持续集成 | `ci.yml` | PR / push | compile + checkstyle + fuzz test + PR title lint + coverage-gate | -| 覆盖率 | `coverage.yml` | PR / push | JaCoCo 采集 + Codecov 上传 | - -README.md 新增 CI Status 和 Coverage 两个 badge。 - -### 2.3 命名整改：MutiSign → MultiSign - -- **25 个文件重命名**（含 `PublicMethedForMutiSign` → `PublicMethedForMultiSign`） -- **73 个文件内容修改**（class 名、import、package、注释） -- **1 个目录重命名**（`mutisign/` → `multisign/`） -- **4 个 XML 配置更新** -- 附带修复: `MutiSignUpdataBrokerageTest` → `MultiSignUpdateBrokerageTest` - -### 2.4 项目根目录清理 - -- 3 个重复 HTML 移除 -- 2 个 HTML 移入 `docs/` -- 临时文件清理（脚本文件、org/ 目录等） - ---- - -## 三、Phase 2 — 架构升级 - -### 3.1 工具自动下载 - -在 `testcase/build.gradle` 新增 Gradle task，社区开发者无需手动安装工具： - -| Task | 功能 | -|------|------| -| `downloadGrpcurl` | 自动下载 grpcurl v1.8.9（检测 Linux/macOS x86/ARM） | -| `downloadSolc` | 自动下载 tron-fork solc 0.8.6 | -| `downloadTools` | 聚合以上两者 | - -- `stest`、`dailyBuild`、`singleNodeBuild`、`smokeTest` 自动依赖 `downloadTools` -- 已有工具时自动跳过（`onlyIf { !bin.exists() }`） -- 使用 Gradle 原生 API，无需额外插件 - -### 3.2 Flaky Test 治理 - -| 组件 | 说明 | -|------|------| -| `@Flaky` 注解 | `reason`（必填）、`since`、`issue` 三个字段 | -| `FlakyTestListener` | 实现 `ITestListener`，分离统计 flaky 通过/失败，suite 结束打印摘要 | -| 已标记 10 个类 | FreezeBalanceV2(5), TvmVote, UsdtTest002, KillContract01, HttpTestFreezeV2001, ContractInternalTransaction002 | - -### 3.3 覆盖率 PR 门禁 - -- `ci.yml` 新增 `coverage-gate` job -- 阈值：全局 ≥10%，utils 包 ≥20%（渐进提升策略） - -### 3.4 MongoBase 继承链改造 - -**改造前**：MongoBase 是独立基类，5 个 MongoEventQuery 类各自管理 channel。 - -**改造后**： -- MongoBase 改为 `extends TronBaseTest` + `@Slf4j` -- 新增 `mongoAvailable` 标志，MongoDB 不可用时 graceful skip -- 5 个 MongoEventQuery 去除所有冗余字段和手动 channel 管理 - -### 3.5 HTTP 测试并发优化 - -**核心问题**：`HttpMethod.java`（6162 行）有 7 个 `static` 共享可变字段（`httppost`、`response`、`transactionString` 等），导致多线程互相覆盖。 - -**改造**： -- 删除 7 个 static 字段，改为方法内局部变量 -- `disConnect()` 改为 no-op（连接由 `PoolingClientConnectionManager` 池管理） -- HTTP 测试从 Serial Case (thread-count=1) 移入 Parallel Case (thread-count=8) -- **35 个 HTTP 测试现在可并发执行** - -**附带修复**： -- HttpTestAccount003.test12：注释掉（调用不存在的 API） -- HttpMethod 中 2 处变量在赋值前被 logger.info 引用（预存 bug） - -### 3.6 Groups 注解补全 - -5 个文件的 `@Test` 缺少 `groups` 注解，已补上 `groups = {"daily"}`： -- MongoEventQuery001/002/005 -- WalletTestAssetIssue016/020 - ---- - -## 四、Phase 3 — 能力补全 - -### 4.1 安全/攻击模拟测试 - -**5 个 Solidity 攻击合约**（`src/test/resources/soliditycode/`）： - -| 合约 | 覆盖场景 | -|------|----------| -| `SecurityReentrancy.sol` | 重入攻击（vulnerable/safe withdraw 对比） | -| `SecurityOverflow.sol` | 整数溢出（checked revert / unchecked 包裹 / uint256 边界） | -| `SecuritySelfdestruct.sol` | selfdestruct 转账、代码清除、权限控制 | -| `SecurityPermission.sol` | onlyOwner/onlyAdmin、tx.origin vs msg.sender、proxy bypass | -| `SecurityEnergyBomb.sol` | 无限循环、storage 膨胀、O(n²) 计算 | - -**5 个 Java 测试类**（`dailybuild/security/`），共 31 个测试方法。 - -### 4.2 社区建设 - -| 文件 | 内容 | -|------|------| -| `docs/GOOD_FIRST_ISSUES.md` | 24 个具体任务（新测试/改进/文档/基础设施/命名） | -| `.github/ISSUE_TEMPLATE/good_first_issue.md` | Good First Issue 模板 | -| `CONTRIBUTORS.md` | 贡献者指南 + 列表模板 | -| `README.md` | 新增 "Get Involved" 版块 | - -### 4.3 组网结构文档 & 多节点环境支持 - -新建 `docs/NETWORK.md` — 面向社区的完整组网拓扑指南。 - -#### 单节点拓扑 - -``` - ┌─────────────────────────────────────────────────────────────────────┐ - │ java-tron Process │ - │ (--witness --es mode) │ - │ │ - │ ┌─────────────┐ ┌──────────────┐ ┌──────────────┐ │ - │ │ Witness x2 │ │ Block Store │ │ Event Sub │ │ - │ │ (SR1 + SR2) │ │ (LevelDB) │ │ (Native) │ │ - │ └─────────────┘ └──────────────┘ └──────┬───────┘ │ - │ │ │ - │ ┌──────────────────────────────────────────┼──────────────────┐ │ - │ │ API Layer │ │ │ - │ │ gRPC HTTP JSON-RPC Event │ │ - │ │ ├─ :50051 Full ├─ :8090 Full ├─ :50545 :50096 │ │ - │ │ ├─ :50061 Sol ├─ :8091 Sol └─ :50555 │ │ - │ │ └─ :50071 PBFT └─ :8098 PBFT │ │ - │ └─────────────────────────────────────────────────────────────┘ │ - │ P2P: :18889 │ - └─────────────────────────────────────────────────────────────────────┘ - ▲ ▲ ▲ ▲ - ┌────┴───┐ ┌────┴───┐ ┌───┴────┐ ┌───┴────┐ - │ gRPC │ │ HTTP │ │JSON-RPC│ │ Event │ - │ Tests │ │ Tests │ │ Tests │ │ Tests │ - └────────┘ └────────┘ └────────┘ └────────┘ -``` - -#### 多节点拓扑 - -``` - ┌──────────────────────────────────┐ P2P ┌──────────────────────────────────┐ - │ Node 1 (SR1) │◄──────────►│ Node 2 (SR2) │ - │ Witness: SR1 (Mercury) │ :18889 │ Witness: SR2 (Venus) │ - │ │ :18892 │ │ - │ gRPC :50051/50061/50071 │ │ gRPC :50052/50062/50072 │ - │ HTTP :8090/8091/8098 │ │ HTTP :8092/8093/8099 │ - │ RPC :50545/50555 │ │ RPC :50546/50556 │ - │ Event :50096 │ │ Event :50097 │ - └──────────────────────────────────┘ └──────────────────────────────────┘ - ▲ ▲ - └────────────── Test Process ────────────────────┘ -``` - -#### DPoS 出块流程 - -``` - Time ──────────────────────────────────────────────────────────► - - SR1 ──── Block 1 ────────────── Block 3 ────────────── Block 5 ──► - ╲ ╱ ╲ ╱ - ── confirm ── ── confirm ── - ╱ ╲ ╱ ╲ - SR2 ────────────── Block 2 ────────────── Block 4 ──────────────► - - Finality: block is "solidified" after 2/3 witnesses confirm -``` - -#### 端口映射表（多节点） - -| 协议 | 服务 | Node 1 | Node 2 | -|------|------|--------|--------| -| gRPC | FullNode | 50051 | 50052 | -| gRPC | Solidity | 50061 | 50062 | -| gRPC | PBFT | 50071 | 50072 | -| HTTP | FullNode | 8090 | 8092 | -| HTTP | Solidity | 8091 | 8093 | -| HTTP | PBFT | 8098 | 8099 | -| JSON-RPC | FullNode | 50545 | 50546 | -| JSON-RPC | Solidity | 50555 | 50556 | -| TCP | P2P | 18889 | 18892 | -| TCP | Event | 50096 | 50097 | - -完整文档包含：可复制的 config.conf 示例、Docker Compose 启动命令、测试套件与组网模式对应关系、环境自动检测说明。 - -#### @MultiNode 自动检测机制 - -| 组件 | 说明 | -|------|------| -| `@MultiNode` 注解 | 标记需要多节点环境的测试类（`reason` 字段） | -| `MultiNodeListener` | suite 启动时探测 `fullnode.ip.list[1]`，单节点环境自动 skip | -| 系统属性覆盖 | `-Dtron.test.multinode=true/false` 强制指定 | -| **213 个类已标注** | 批量脚本处理所有引用 `fullnode.ip.list.get(1)` 的类 | - -#### Docker 多节点环境 - -| 文件 | 用途 | -|------|------| -| `docker/docker-compose.yml` | 单节点(默认) / 双节点(--profile multi) / MongoDB(--profile mongo) | -| `docker/node/config.conf` | Docker 单节点配置 | -| `docker/node1/config.conf` | Docker SR1 配置 | -| `docker/node2/config.conf` | Docker SR2 配置 | -| `docs/config-node1.conf` | 非 Docker 多节点 SR1 配置 | -| `docs/config-node2.conf` | 非 Docker 多节点 SR2 配置 | - -### 4.4 DPoS 共识测试（4 个类） - -| 类名 | 测试方法 | 覆盖场景 | -|------|---------|---------| -| `WitnessElectionTest` | 4 | 见证人列表、地址校验、投票增加、排序验证 | -| `BlockProductionTest` | 4 | 区块递增、生产者校验、出块间隔、轮次轮转 | -| `MaintenancePeriodTest` | 3 | 维护周期时间、见证人列表、总票数 | -| `VoteWeightTest` | 4 | 冻结与投票权、投票计数、重投、清零 | - -全部标注 `@MultiNode`，单节点环境自动跳过。 - -### 4.5 P2P 网络层测试（3 个类） - -| 类名 | 测试方法 | 覆盖场景 | -|------|---------|---------| -| `TransactionBroadcastTest` | 2 | node1 发交易 → node2 确认、批量传播 | -| `BlockSyncTest` | 3 | 区块高度收敛、同区块一致性、持续同步 | -| `CrossNodeConsistencyTest` | 3 | 余额一致性、转账传播、foundation 账户一致性 | - -全部标注 `@MultiNode`。 - -### 4.6 性能基准测试（3 个类） - -| 类名 | 测试方法 | 覆盖场景 | -|------|---------|---------| -| `ThroughputBenchmarkTest` | 1 | 批量 50 笔交易提交 + TPS 测量 + 确认率 | -| `BlockLatencyTest` | 2 | 出块间隔统计（avg/min/max）、区块号连续性 | -| `ApiLatencyTest` | 5 | GetNowBlock/ListWitnesses/GetBlockByNum/QueryAccount/GetNextMaintenanceTime 延迟 | - -单节点可跑，无需 `@MultiNode`。 - -### 4.7 Fuzzing 扩展测试（3 个类，jqwik） - -| 类名 | Property 数 | 覆盖场景 | -|------|-----------|---------| -| `TransactionFuzzTest` | 4 | 随机金额签名、负数金额、随机地址、签名篡改 | -| `ContractBytecodeFuzzTest` | 4 | 随机字节码打包、空字节码、特殊字符合约名、随机 ABI | -| `GrpcMessageFuzzTest` | 6 | Transaction/BytesMessage/NumberMessage 随机字节解析、roundtrip | - -加上已有 6 个 fuzz 类，共 **9 个 fuzz 测试类**。 - ---- - -## 五、命名规范全面整改 - -### 5.1 类名/文件名拼写修复 - -| 错误名称 | 修正名称 | 影响 | -|----------|----------|------| -| `PublicMethed` | `PublicMethod` | 570 个文件 + 类本身(2775行) | -| `PublicMethedForMultiSign` | `PublicMethodForMultiSign` | 68 个文件 | -| `HttpMethed` | `HttpMethod` | 62 个文件 + 类本身(6162行) | -| `EthGrammer` / `EthGrammer02` | `EthGrammar` / `EthGrammar02` | 2 个文件 | -| `SlotAndOffsetNewGrammer` | `SlotAndOffsetNewGrammar` | 1 个文件 | -| `HttpRateLimite001` | `HttpRateLimit001` | 1 个文件 | -| `Creatasset` | `CreateAsset` | 1 个文件 | -| `pedersenHash001` / `002` | `PedersenHash001` / `002` | 2 个文件（首字母大写） | -| `MutiGetFilterChange` | `MultiGetFilterChange` | 1 个文件 | -| `MultisignOperationerGodicTest` | `MultisignOperatorErgodicTest` | 1 个文件 | - -### 5.2 方法名拼写修复 - -| 错误名称 | 修正名称 | 影响文件数 | -|----------|----------|-----------| -| `freedResource` | `freeResource` | 287 个文件 | -| `WaitUntilTransactionInfoFound` | `waitUntilTransactionInfoFound` | 3 个文件 | -| `sucideToActiveAcount` | `suicideToActiveAccount` | 1 个文件 | - -### 5.3 目录/包名修复（前序） - -| 错误 | 修正 | 影响 | -|------|------|------| -| `mutisign/` | `multisign/` | 目录 + 25 个文件重命名 + 73 个文件引用 | -| `MutiSign` | `MultiSign` | 类名 + import + XML | - -**命名整改累计影响约 700+ 个文件**，全部通过编译验证。 - ---- - -## 六、量化指标 - -### 6.1 代码库规模 - -| 指标 | 数值 | -|------|------| -| Java 测试文件总数 | 698 | -| dailybuild 测试类 | 470 | -| @MultiNode 标注类 | 220 | -| @Flaky 标注类 | 10 | -| 安全测试类 | 5（31 个方法） | -| Fuzz 测试类 | 9 | -| 共识测试类 | 4（15 个方法） | -| 网络测试类 | 3（8 个方法） | -| 性能测试类 | 3（8 个方法） | -| Solidity 攻击合约 | 5 | -| 文档文件 | 9 | -| CI 工作流 | 2 | - -### 6.2 改造覆盖面 - -| 改造项 | 影响文件数 | -|--------|-----------| -| TronBaseTest 基类重构 | 562 | -| PublicMethod 重命名 (Methed→Method) | 587 | -| MultiSign 重命名 (Muti→Multi) | 98 | -| @MultiNode 批量标注 | 213 | -| freeResource 重命名 (freed→free) | 287 | -| HttpMethod 并发改造 | 1 (6162行) + 35 个 HTTP 测试受益 | -| MongoBase 继承链改造 | 6 | -| 其他拼写修复 | ~15 | - -### 6.3 新建文件清单 - -| 类别 | 文件 | -|------|------| -| 基类/注解/监听器 | TronBaseTest, TronConstants, RetryUtil, @MultiNode, MultiNodeListener, @Flaky, FlakyTestListener | -| 安全测试 | SecurityReentrancyTest, SecurityOverflowTest, SecuritySelfdestructTest, SecurityPermissionTest, SecurityEnergyBombTest | -| 攻击合约 | SecurityReentrancy.sol, SecurityOverflow.sol, SecuritySelfdestruct.sol, SecurityPermission.sol, SecurityEnergyBomb.sol | -| 共识测试 | WitnessElectionTest, BlockProductionTest, MaintenancePeriodTest, VoteWeightTest | -| 网络测试 | TransactionBroadcastTest, BlockSyncTest, CrossNodeConsistencyTest | -| 性能测试 | ThroughputBenchmarkTest, BlockLatencyTest, ApiLatencyTest | -| Fuzz 测试 | TransactionFuzzTest, ContractBytecodeFuzzTest, GrpcMessageFuzzTest (+ 已有6个) | -| 文档 | SETUP.md, STYLE_GUIDE.md, NETWORK.md, GOOD_FIRST_ISSUES.md, TIP-TEST-MAPPING.md, CONTRIBUTORS.md | -| 社区模板 | good_first_issue.md | -| CI | ci.yml, coverage.yml | -| Docker | docker-compose.yml, node/config.conf, node1/config.conf, node2/config.conf | -| 配置 | docs/config-node1.conf, docs/config-node2.conf | - ---- - -## 七、未完成项与后续规划 - -### 7.1 明确跳过（需外部协调） - -| 项目 | 原因 | 前置条件 | -|------|------|---------| -| Java 8 → 17 升级 | 破坏性升级 | 与 tronprotocol 官方 CI 协调 | -| Gradle 6.3 → 8.x | 构建脚本大改 | 同上 | -| JUnit 5 @Tag 替代目录分类 | 测试框架迁移 | 同上 | -| 跨实现验证框架 | 全新框架搭建 | 需 Python pytest 新建测试层 | - -### 7.2 可继续推进 - -| 项目 | 说明 | -|------|------| -| 服务器部署验证 | 在正式服务器上跑完整 dailyBuild | -| 提交 PR | 整理变更，分批或整体提 PR | -| 按硬分叉版本组织 | `v4_7_0/` `v4_8_0/` `v4_8_1/` 目录划分 | -| WalletTestAccount012 等通用名 | 测试类命名语义化 | -| 覆盖率阈值提升 | 从 10%/20% 渐进提升 | -| @MultiNode 多节点实测 | 在双节点环境验证 consensus/network 测试 | - ---- - -## 八、文件变更汇总 - -``` -system-test/ -├── .github/ -│ ├── workflows/ -│ │ ├── ci.yml [新建] CI 门禁 -│ │ └── coverage.yml [新建] 覆盖率 -│ ├── PULL_REQUEST_TEMPLATE.md [已有] -│ └── ISSUE_TEMPLATE/ -│ ├── bug_report.md [已有] -│ ├── new_test.md [已有] -│ └── good_first_issue.md [新建] -├── docs/ -│ ├── ARCHITECTURE.md [已有] -│ ├── SETUP.md [新建] -│ ├── STYLE_GUIDE.md [新建] -│ ├── NETWORK.md [新建] -│ ├── GOOD_FIRST_ISSUES.md [新建] -│ ├── TIP-TEST-MAPPING.md [新建] -│ ├── config-node1.conf [新建] -│ └── config-node2.conf [新建] -├── docker/ -│ ├── docker-compose.yml [重写] -│ ├── node/config.conf [重写] -│ ├── node1/config.conf [新建] -│ └── node2/config.conf [新建] -├── testcase/src/test/java/stest/tron/wallet/ -│ ├── common/client/utils/ -│ │ ├── TronBaseTest.java [新建] 基类 -│ │ ├── TronConstants.java [新建] 常量 -│ │ ├── RetryUtil.java [新建] 重试工具 -│ │ ├── PublicMethod.java [重命名] ← PublicMethed -│ │ ├── PublicMethodForMultiSign.java [重命名] ← PublicMethedForMultiSign -│ │ ├── HttpMethod.java [重命名+重构] ← HttpMethed -│ │ ├── MultiNode.java [新建] 注解 -│ │ ├── MultiNodeListener.java [新建] 监听器 -│ │ ├── Flaky.java [新建] 注解 -│ │ └── FlakyTestListener.java [新建] 监听器 -│ ├── dailybuild/ -│ │ ├── consensus/ [新建目录] -│ │ │ ├── WitnessElectionTest.java -│ │ │ ├── BlockProductionTest.java -│ │ │ ├── MaintenancePeriodTest.java -│ │ │ └── VoteWeightTest.java -│ │ ├── network/ [新建目录] -│ │ │ ├── TransactionBroadcastTest.java -│ │ │ ├── BlockSyncTest.java -│ │ │ └── CrossNodeConsistencyTest.java -│ │ ├── performance/ [新建目录] -│ │ │ ├── ThroughputBenchmarkTest.java -│ │ │ ├── BlockLatencyTest.java -│ │ │ └── ApiLatencyTest.java -│ │ ├── security/ [新建目录] -│ │ │ ├── SecurityReentrancyTest.java -│ │ │ ├── SecurityOverflowTest.java -│ │ │ ├── SecuritySelfdestructTest.java -│ │ │ ├── SecurityPermissionTest.java -│ │ │ └── SecurityEnergyBombTest.java -│ │ └── (470+ 个已有测试类 — 基类重构 + 命名修复) -│ └── fuzz/ -│ ├── TransactionFuzzTest.java [新建] -│ ├── ContractBytecodeFuzzTest.java [新建] -│ ├── GrpcMessageFuzzTest.java [新建] -│ └── (6 个已有 fuzz 测试) -├── testcase/src/test/resources/ -│ ├── daily-build-main.xml [修改] 添加 listeners -│ ├── single-node-build.xml [修改] 添加新测试类 -│ └── soliditycode/ -│ ├── SecurityReentrancy.sol [新建] -│ ├── SecurityOverflow.sol [新建] -│ ├── SecuritySelfdestruct.sol [新建] -│ ├── SecurityPermission.sol [新建] -│ └── SecurityEnergyBomb.sol [新建] -├── README.md [增强] -├── CONTRIBUTING.md [增强] -└── CONTRIBUTORS.md [新建] -``` - ---- - -*全部改造通过 `./gradlew testcase:compileTestJava` 编译验证。* diff --git a/docs/REVIEW_CHECKLIST.md b/docs/REVIEW_CHECKLIST.md deleted file mode 100644 index 172e98ae..00000000 --- a/docs/REVIEW_CHECKLIST.md +++ /dev/null @@ -1,83 +0,0 @@ -# 文档人工校对清单 - -AI 生成的 .md 文件整体框架正确，但细节处可能存在幻觉。以下列出每个文件的重点校对项。 - ---- - -## 高优先级（对外可见/影响构建） - -### README.md -- [ ] 项目描述是否准确反映当前状态 -- [ ] CI badge 链接是否正确（需要实际仓库地址后更新） -- [ ] 依赖版本号（JDK 8/17、Gradle 6.3）是否与实际一致 -- [ ] "Test Network Options" 章节的命令是否可执行 - -### CONTRIBUTING.md -- [ ] ~~solc 下载链接~~ ✅ 已修复为 tronprotocol/solidity -- [ ] Conventional Commits 规范示例是否与项目实际 commit 风格匹配 -- [ ] 分支命名规范是否是你想要的 -- [ ] PR 模板中的 checklist 是否合理 - -### docs/SETUP.md -- [ ] ~~solc 下载地址~~ ✅ 已修复 -- [ ] 私有网络启动命令 `bin/FullNode -c config.conf --witness --es` 是否与实际 java-tron 版本匹配 -- [ ] config.conf 中的 genesis 地址、witness 配置是否与 testng.conf 一致 -- [ ] 端口号是否与实际测试环境一致 -- [ ] troubleshooting 章节的解决方案是否真实有效 - -### docs/NETWORK.md -- [ ] 端口映射表是否与 testng.conf 中的实际配置完全一致 -- [ ] config-node1.conf / config-node2.conf 中的 localwitness 私钥是否正确 -- [ ] genesis.block 中的地址和余额是否与 testng.conf 一致 -- [ ] Docker 相关命令是否可实际执行 -- [ ] DPoS 出块流程描述是否准确 - ---- - -## 中优先级（文档质量） - -### docs/ARCHITECTURE.md -- [ ] 基类层次图是否与实际代码匹配 -- [ ] Helper 分解描述是否反映当前代码结构 -- [ ] 提到的类名/方法名是否存在（重命名后可能遗漏更新） - -### docs/STYLE_GUIDE.md -- [ ] 命名规范示例是否与项目实际一致 -- [ ] 断言最佳实践是否合理 -- [ ] 代码格式要求是否与 checkstyle 配置一致 - -### docs/TIP-TEST-MAPPING.md -- [ ] TIP 编号与实际 TIP 是否对应 -- [ ] 测试类名是否存在（重命名后可能遗漏） -- [ ] 映射关系是否准确 - -### docs/GOOD_FIRST_ISSUES.md -- [ ] 24 个任务是否都还有效（有些可能已被完成） -- [ ] 提到的文件路径是否正确 -- [ ] 难度评估是否合理 - ---- - -## 低优先级（内部参考） - -### CONTRIBUTORS.md -- [ ] 模板格式是否合适 - -### .github/ISSUE_TEMPLATE/good_first_issue.md -- [ ] 模板字段是否合理 - -### docs/REFACTORING_REPORT.md / .html -- [ ] 数据统计是否准确 -- [ ] 版本号、日期是否正确 - -### docs/worklog-2026-04-04.md -- [ ] 内部工作日志，可保留或删除 - ---- - -## 校对方法建议 - -1. **链接验证**：`grep -rn 'http' docs/ *.md | grep -v node_modules` 逐个点击验证 -2. **类名验证**：文档中提到的类名用 `grep -r "ClassName"` 确认存在 -3. **端口验证**：对照 `testng.conf` 检查所有端口号 -4. **命令验证**：文档中的 shell 命令实际执行一遍 diff --git a/docs/SETUP.md b/docs/SETUP.md index 0004bf66..e328bd3a 100644 --- a/docs/SETUP.md +++ b/docs/SETUP.md @@ -1,6 +1,5 @@ # TRON System-Test Setup Guide -**English** | [中文](SETUP_CN.md) Integration test suite for [java-tron](https://github.com/tronprotocol/java-tron). Tests gRPC, HTTP, JSON-RPC APIs, smart contracts, staking, multi-signature, and more against a running java-tron node. diff --git a/docs/SETUP_CN.md b/docs/SETUP_CN.md deleted file mode 100644 index 1d5b0c13..00000000 --- a/docs/SETUP_CN.md +++ /dev/null @@ -1,225 +0,0 @@ -# TRON System-Test 安装指南 - -[English](SETUP.md) | **中文** - -[java-tron](https://github.com/tronprotocol/java-tron) 的集成测试套件。通过 gRPC、HTTP、JSON-RPC API 测试智能合约、质押、多签等功能。 - ---- - -## 前置条件 - -| 要求 | 说明 | -|------|------| -| **JDK 8**（x86/Intel） | 推荐。项目目标 `sourceCompatibility = 1.8` | -| **JDK 17**（ARM/Apple Silicon） | 使用 Rosetta 或 ARM 兼容的 JDK 8 | -| **Gradle** | 通过 `./gradlew` 包装器使用，无需单独安装 | -| **操作系统** | Linux 或 macOS。Windows 不受官方支持 | -| **磁盘** | 约 2 GB（java-tron 数据目录） | -| **内存** | 至少 4 GB 可用（java-tron 本身需要约 2 GB 堆内存） | - -macOS 安装 JDK 8： - -```bash -brew install --cask temurin@8 -export JAVA_HOME=$(/usr/libexec/java_home -v 1.8) -``` - -Linux (Ubuntu/Debian)： - -```bash -sudo apt install openjdk-8-jdk -``` - ---- - -## 5 分钟快速开始 - -### 第 1 步：下载 java-tron - -下载最新版本（GreatVoyage-v4.8.1 或更新）： - -```bash -wget https://github.com/tronprotocol/java-tron/releases/download/GreatVoyage-v4.8.1/java-tron-GreatVoyage-v4.8.1.zip -unzip java-tron-GreatVoyage-v4.8.1.zip -cd java-tron-GreatVoyage-v4.8.1 -``` - -### 第 2 步：配置私有网络 - -使用仓库提供的测试配置： - -```bash -cp /docs/config.conf ./config.conf -``` - -关键配置项（已在 `docs/config.conf` 中预设）： - -```hocon -# 端口（必须与 testng.conf 匹配） -node.rpc.port = 50051 -node.http.fullNodePort = 8090 - -# 快速维护周期（20 秒而非 6 小时） -block.maintenanceTimeInterval = 20000 -block.needSyncCheck = false - -# 启用测试所需功能 -vm.supportConstant = true -vm.saveInternalTx = true -node.rpc.reflectionService = true # grpcurl 测试需要 -``` - -### 第 3 步：启动节点 - -```bash -bin/FullNode -c config.conf --es --witness -``` - -- `--witness` — 启用出块（SR 模式） -- `--es` — 启用事件订阅 - -### 第 4 步：验证出块 - -等待 10-15 秒后检查： - -```bash -curl -s http://127.0.0.1:8090/wallet/getnowblock | python3 -m json.tool | grep number -``` - -应该看到递增的区块号。如果区块号一直为 0，检查 `config.conf` 中 `localwitness` 的私钥是否与创世区块的见证人地址匹配。 - -### 第 5 步：运行测试 - -在 `system-test/` 目录下： - -```bash -# 冒烟测试（约 5 分钟，快速验证环境正确） -./gradlew smokeTest - -# 通过后可以跑更完整的测试 -./gradlew singleNodeBuild # 仅单节点测试，约 40 分钟 -./gradlew dailyBuild # 全量回归，约 1.5 小时（建议双节点） -``` - ---- - -## 工具安装 - -完整测试套件需要两个外部工具。首次运行测试时会自动下载： - -```bash -./gradlew downloadTools -``` - -### 手动安装（网络受限环境） - -如果 GitHub 下载超时（国内常见），手动下载后放到指定目录。 - -#### grpcurl (v1.8.9) - -下载地址：https://github.com/fullstorydev/grpcurl/releases/tag/v1.8.9 - -```bash -# macOS (Apple Silicon) -wget https://github.com/fullstorydev/grpcurl/releases/download/v1.8.9/grpcurl_1.8.9_osx_arm64.tar.gz -tar xzf grpcurl_1.8.9_osx_arm64.tar.gz - -# macOS (Intel) -wget https://github.com/fullstorydev/grpcurl/releases/download/v1.8.9/grpcurl_1.8.9_osx_x86_64.tar.gz -tar xzf grpcurl_1.8.9_osx_x86_64.tar.gz - -# Linux (x86_64) -wget https://github.com/fullstorydev/grpcurl/releases/download/v1.8.9/grpcurl_1.8.9_linux_x86_64.tar.gz -tar xzf grpcurl_1.8.9_linux_x86_64.tar.gz - -# 放到指定位置 -cp grpcurl /gRPCurl/grpcurl -chmod +x /gRPCurl/grpcurl -``` - -#### solc (tronprotocol fork v0.8.26) - -下载地址：https://github.com/tronprotocol/solidity/releases/tag/tv_0.8.26 - -```bash -# Linux -wget -O solc https://github.com/tronprotocol/solidity/releases/download/tv_0.8.26/solc-static-linux - -# macOS -wget -O solc https://github.com/tronprotocol/solidity/releases/download/tv_0.8.26/solc-macos - -# 放到指定位置 -cp solc /solcDIR/solc -chmod +x /solcDIR/solc - -# 验证 -./solcDIR/solc --version -# 应输出: solc.tron, the solidity compiler ... Version: 0.8.26+... -``` - -> **注意**：必须使用 tronprotocol fork 版本的 solc，标准 Ethereum solc 不支持 TVM 特有的操作码。 - ---- - -## 测试命令一览 - -| 命令 | 说明 | 测试数 | 时间 | -|------|------|--------|------| -| `./gradlew smokeTest` | 核心功能验证 | ~30 | ~5 分钟 | -| `./gradlew stest` | 标准 TestNG 套件 | ~200 | ~20 分钟 | -| `./gradlew singleNodeBuild` | 仅单节点测试 | ~260 | ~40 分钟 | -| `./gradlew dailyBuild` | 全量日常回归 | ~1685 | ~1.5 小时 | -| `./gradlew fuzzTest` | 属性测试 (jqwik) | 可变 | ~10 分钟 | -| `./gradlew lint` | Checkstyle 代码检查 | -- | ~1 分钟 | - -### 运行单个测试类 - -```bash -# 编辑 debug-test.xml 指定要跑的类 -./gradlew debugTest - -# 或使用脚本 -./run-test.sh SecurityOverflowTest -``` - ---- - -## 单节点 vs 多节点 - -| 模式 | 测试覆盖 | 需要的节点数 | -|------|----------|-------------| -| 单节点 | 57% (~260 个类) | 1 个 FullNode | -| 多节点 | 100% (~455 个类) | 2 个 FullNode (SR1 + SR2) | - -单节点环境中，需要多节点的测试会**自动跳过**（通过 `@MultiNode` 注解检测），不会报错。 - -多节点搭建详见 [NETWORK.md](NETWORK.md)。 - ---- - -## 常见问题 - -详见 [FAQ.md](FAQ.md)。 - -快速排查： - -| 现象 | 解决方案 | -|------|---------| -| 区块号一直为 0 | 检查 `localwitness` 私钥和 `needSyncCheck = false` | -| `Connection refused` | 节点未启动或端口不匹配 | -| grpcurl 测试全部失败 | 配置 `node.rpc.reflectionService = true` | -| 合约部署失败 | 确认 solc 在 `solcDIR/solc` 且可执行 | -| MongoDB 测试跳过 | 正常现象，MongoDB 是可选的 | -| 内存不足 | 改用 `singleNodeBuild` 或减少线程数 | - ---- - -## 相关文档 - -| 文档 | 说明 | -|------|------| -| [README (中文)](../README_CN.md) | 项目概览 | -| [网络拓扑](NETWORK.md) | 单节点/多节点组网、端口映射、Docker | -| [架构](ARCHITECTURE.md) | 测试基类、Helper 分解、执行模型 | -| [代码规范](STYLE_GUIDE.md) | 命名规则、断言模式 | -| [常见问题](FAQ.md) | 高频问题与解决方案 | diff --git a/docs/readme_single_node.md b/docs/readme_single_node.md index f90ab059..e09a6903 100644 --- a/docs/readme_single_node.md +++ b/docs/readme_single_node.md @@ -1,42 +1,40 @@ -# 单节点配置说明 +# Single-Node Configuration -## 配置文件 +## Configuration File -| 节点 | 配置文件 | -|------|----------| -| SR-1 节点（拖 3 witness） | `config.conf` | +| Node | Configuration File | +|------|--------------------| +| SR-1 node (carrying 3 witnesses) | `config.conf` | -## 节点启动参数 +## Node Startup Parameters -SR-1 节点启动时需要添加参数： +SR-1 node requires the following parameters at startup: ``` --es --witness ``` -## 依赖工具 +## Required Tools -### 编译器（solc） +### Compiler (solc) -- 下载地址： -- 下载后保存至 system-test 项目的 `solcDIR/` 目录，命名为 `solc` -- 当前使用版本：`v0.8.26` +- Download: +- Save to the `solcDIR/` directory of the system-test project, named `solc` +- Current version: `v0.8.26` ### gRPCurl -- 下载地址： -- 下载后保存至 system-test 项目的 `gRPCurl/` 目录，命名为 `grpcurl` -- 当前使用版本：`v1.8.9` +- Download: +- Save to the `gRPCurl/` directory of the system-test project, named `grpcurl` +- Current version: `v1.8.9` -## 注意事项 +## Notes -### mongo 相关用例 +### MongoDB-related test cases -单节点 event 配置使用了 native 配置，会导致 mongo 相关用例失败。若无需关注 mongo 用例，可禁用此部分用例。 - -### 限速相关用例 - -部分限速用例在单节点环境下运行会失败。若不关注此类用例，可预先禁用此部分用例。 +The single-node event configuration uses the native configuration, which causes MongoDB-related test cases to fail. If you do not need to run MongoDB test cases, you can disable them. +### Rate-limiting test cases +Some rate-limiting test cases will fail in a single-node environment. If you do not need to run these test cases, you can disable them in advance. diff --git a/docs/test-network-research.md b/docs/test-network-research.md deleted file mode 100644 index aca2f985..00000000 --- a/docs/test-network-research.md +++ /dev/null @@ -1,254 +0,0 @@ -# 测试组网方式调研：以太坊 vs java-tron - -## 背景 - -java-tron 的 system-test 需要启动外部 FullNode 进程，通过 gRPC/HTTP 连接进行黑盒测试。完整 dailyBuild（455 个测试类）中 43% 需要多节点环境（Solidity、PBFT、第二 FullNode）。搭建和维护这个测试环境是一个持续的痛点。 - -本文调研以太坊（go-ethereum）的测试架构，分析 java-tron 的差距和可能的改进方向。 - ---- - -## 以太坊的五层测试架构 - -### 第 1 层：SimulatedBackend — 进程内嵌入节点 - -最轻量的方式。`simulated.NewBackend()` 在测试进程内启动一个完整的以太坊节点： - -- P2P 关闭（`NoDiscovery: true, MaxPeers: 0`） -- 用 `SimulatedBeacon` 模拟共识层 -- **按需出块**：调用 `Commit()` 才出块，不需要等待时间间隔 -- 返回标准 `ethclient.Client` 接口，测试代码与连接真实节点无差异 - -```go -// 一行代码启动完整节点 -sim := simulated.NewBackend(types.GenesisAlloc{ - testAddr: {Balance: big.NewInt(10000000000000000)}, -}) -client := sim.Client() - -// 发交易 + 立即出块 -client.SendTransaction(ctx, tx) -sim.Commit() // 不等 12 秒，立即产生新块 -``` - -**关键设计**：go-ethereum 的节点是一个可嵌入的库，`node.Node` + `eth.Ethereum` 可以在任意 Go 进程中实例化。 - -### 第 2 层：SimulatedBeacon — 模拟共识与可控最终性 - -替代真实的共识客户端（Lighthouse/Prysm 等），通过 Engine API 驱动出块： - -1. 调用 `forkchoiceUpdated` 触发区块构建 -2. 调用 `getPayload` 获取构建好的区块 -3. 调用 `newPayload` 验证并导入区块 -4. 再次调用 `forkchoiceUpdated` 设为规范链头 - -**最终性处理**（对应 TRON 的"固化"）： -- `devEpochLength = 32`：每 32 个块更新一次 `FinalizedBlockHash` -- `SafeBlockHash` 始终等于 `HeadBlockHash`（开发模式简化） -- 两种模式：`period=0` 手动出块（确定性测试），`period>0` 自动出块 - -```go -n, ethservice, simBeacon := startSimulatedBeaconEthService(t, genesis, 0) -// period=0: 只在显式调用时出块，测试完全可控 -``` - -### 第 3 层：Mock Peers — 协议级模拟 - -P2P 协议和同步测试使用 mock peer 对象，不走真实网络连接： - -- `downloadTesterPeer`：模拟拥有不同链状态的远程节点 -- `testHandler`：创建真实区块链 + handler，但用 mock 交易池 -- 测试同步、区块传播、交易广播等逻辑，无需真实 TCP 连接 - -```go -type downloadTester struct { - chain *core.BlockChain - downloader *Downloader - peers map[string]*downloadTesterPeer // 模拟的对等节点 -} -// 注册 mock peer 并测试同步 -tester.newPeer("peer1", protocol, blocks) -``` - -### 第 4 层：Hive — Docker 多客户端集成测试 - -以太坊官方跨客户端测试框架（github.com/ethereum/hive）： - -**架构**： -- **Simulator**（Go 程序，打包为 Docker）：编排测试场景 -- **Client**（Docker 镜像）：各种以太坊实现（geth/besu/nethermind/erigon/reth 等） -- **Controller**：提供 HTTP API，Simulator 通过它启停 Client 容器 - -**核心 Simulator**： - -| Simulator | 用途 | -|-----------|------| -| `ethereum/engine` | Engine API 合规测试，CLMocker 模拟共识层 | -| `ethereum/sync` | 跨客户端链同步（source → sink 模式） | -| `ethereum/consensus` | EVM 状态转换测试 | -| `ethereum/rpc-compat` | JSON-RPC API 兼容性 | -| `devp2p` | P2P 协议一致性 | - -**CLMocker**（Hive 中的共识模拟器）： -- `SlotsToFinalized = 2`：区块产出 2 个 slot 后标记为 finalized -- 可同时驱动多个执行层客户端 -- 跟踪 `ExecutedPayloadHistory`、`HeadHashHistory` - -**sync simulator 的多节点模式**： -1. 启动 source 客户端，导入预构建的链 -2. 通过 `forkchoiceUpdated` 标记为已同步 -3. 获取 source 的 enode URL -4. 启动 sink 客户端，`HIVE_BOOTNODE` 指向 source -5. 轮询 sink 直到同步到预期的 head hash（60s 超时） - -### 第 5 层：Kurtosis — 全真 Devnet - -完整的执行层 + 共识层多节点网络（github.com/ethpandaops/ethereum-package）： - -```yaml -participants: - - el_type: geth - cl_type: lighthouse - count: 3 - - el_type: nethermind - cl_type: teku -network_params: - seconds_per_slot: 6 - genesis_delay: 120 - electra_fork_epoch: 5 -``` - -- 生成 EL 和 CL 的创世状态 -- 分发验证者密钥到各 CL 节点 -- 支持 Docker（本地）和 Kubernetes（CI/生产） -- 集成 **Assertoor** 做集成断言（交易包含、finality 验证） -- 集成 **Attacknet** 做混沌工程（网络分区、节点崩溃） -- 以太坊基金会用此框架测试硬分叉升级 - ---- - -## java-tron 的现状 - -### 当前 system-test 架构 - -``` -[测试进程 (Gradle/TestNG)] - │ - ├── gRPC ──→ FullNode :50051 (主节点) - ├── gRPC ──→ FullNode :50052 (第二节点) - ├── gRPC ──→ Solidity :50053 (固化数据查询) - ├── gRPC ──→ PBFT :50072 (PBFT 查询) - ├── HTTP ──→ 各节点 HTTP 端口 - └── JSON-RPC ──→ :50545 -``` - -- 测试进程是纯客户端，不包含任何节点逻辑 -- 必须预先启动外部 FullNode 进程 -- 出块依赖真实时间间隔（3 秒） -- 固化依赖真实 DPoS 共识（2/3 SR 确认） -- `@BeforeSuite` 通过提案机制设置链参数（约 2 分钟） - -### 对比差距 - -| 能力 | go-ethereum | java-tron | -|------|------------|-----------| -| 节点嵌入测试进程 | `simulated.NewBackend()` | 不支持 | -| 共识可模拟 | `SimulatedBeacon` | 不支持，DPoS 写死在节点内 | -| 按需出块 | `sim.Commit()` | 不支持，必须等 3s 出块间隔 | -| 最终性可控 | `devEpochLength` 可配 | 不支持，固化依赖真实 2/3 SR | -| 测试所需外部进程数 | 0 | 1-2 个 FullNode | -| 单次测试耗时 | 毫秒级 | 秒-分钟级（等出块+固化） | -| 完整测试环境搭建 | 一行代码 | 多节点配置+组网+等待提案生效 | - -### 根因分析 - -**go-ethereum 能做到是因为节点被设计为库**： -- `node.Node`、`eth.Ethereum`、`core.BlockChain` 是可组合的模块 -- 共识层通过 Engine API 解耦，可以用 mock 替换 -- P2P 层可选禁用 - -**java-tron 做不到是因为节点是单体应用**： -- `FullNode` 是唯一入口，没有暴露可编程的内部接口 -- DPoS 共识紧耦合在节点生命周期中 -- 没有"开发模式"或"测试模式"的出块/固化控制 - ---- - -## dailyBuild 多节点需求 - -### 455 个测试类的节点依赖分布 - -| 类别 | 数量 | 占比 | -|------|------|------| -| 仅需单 FullNode | 260 | 57% | -| 需要 Solidity (gRPC :50053) | 145 | 32% | -| 需要第二 FullNode (gRPC :50052) | 104 | 23% | -| 需要 PBFT (gRPC :50072) | 21 | 5% | -| 需要 HTTP Solidity/PBFT | 37 | 8% | -| **去重后：需要多节点** | **196** | **43%** | - -### 端口映射（testng.conf） - -**gRPC：** -``` -fullnode[0] = 127.0.0.1:50051 # 主 FullNode -fullnode[1] = 127.0.0.1:50052 # 第二 FullNode -solidity[0] = 127.0.0.1:50053 # Solidity -solidity[1] = 127.0.0.1:50062 # RealSolidity -solidity[2] = 127.0.0.1:50071 # PBFT (Node 1) -solidity[3] = 127.0.0.1:50072 # PBFT (Node 2) -``` - -**HTTP (httpnode.ip.list)：** -``` -[0] 8090 # Node 1 FullNode -[1] 8093 # Node 2 FullNode -[2] 8097 # httpSoliditynode（测试代码中的变量名） -[3] 8091 # （用途待确认） -[4] 8098 # httpPbftNode（测试代码中的变量名） -[5] 8094 # Node 2 Solidity -[6] 8099 # Node 2 PBFT -``` - -**JSON-RPC：** -``` -[0] 50545 # FullNode -[1] 50555 # Solidity -[2] 50546 # PBFT -``` - -### 组网关键约束 - -TRON 使用 DPoS，固化需要超过 2/3 的 SR 确认。当前 genesis block 配置 2 个 witness： -- 固化阈值 = 2/3 × 2 = 1.33，即**两个 witness 都必须确认** -- 单节点配置中 `localwitness` 包含两个私钥，同一进程内两个 SR 轮流出块并互相确认，固化正常工作 -- 拆成两个节点后，每个节点各持一个 SR 私钥，**两节点必须互相连通并同步**，否则固化卡住，所有依赖 Solidity 的测试超时失败 - ---- - -## 可能的改进方向 - -### 短期：正确搭建多节点测试环境 - -在 java-tron 架构不变的前提下，用两个 FullNode 实例组网： - -- Node 1（witness key1）：对外暴露 FullNode + Solidity + PBFT + JSON-RPC 端口 -- Node 2（witness key2）：对外暴露第二套 FullNode + Solidity + PBFT 端口 -- 两节点通过 P2P 互相发现和同步 -- 端口对齐 testng.conf 的期望 - -### 中期：Docker 编排 - -参考 Hive 的模式，用 docker-compose 管理测试环境： - -- 节点作为 Docker 容器启动 -- 测试进程通过 network_mode: host 连接 -- CI 中自动化搭建/销毁 - -### 长期：java-tron 可测试性改造 - -参考 go-ethereum 的 SimulatedBackend 模式： - -1. **提供进程内嵌入能力**：让 FullNode 核心模块可以在测试进程中实例化 -2. **共识层解耦**：提供测试用的 DPoS mock，支持按需出块和可控固化 -3. **开发模式**：添加 `--dev` 启动参数，单节点即可满足所有 API（包括 Solidity/PBFT 查询），无需组网 diff --git a/docs/worklog-2026-04-04.md b/docs/worklog-2026-04-04.md deleted file mode 100644 index 404624f7..00000000 --- a/docs/worklog-2026-04-04.md +++ /dev/null @@ -1,198 +0,0 @@ -# 工作记录 2026-04-04 - -## 一、Phase 2 架构升级（上午） - -### 1. 工具自动下载 ✅ - -在 `testcase/build.gradle` 新增 3 个 Gradle task： - -| Task | 功能 | -|------|------| -| `downloadGrpcurl` | 自动下载 grpcurl v1.8.9（检测 Linux/macOS x86/ARM） | -| `downloadSolc` | 自动下载 tron-fork solc 0.8.6 | -| `downloadTools` | 聚合以上两者 | - -- `stest`、`dailyBuild`、`singleNodeBuild`、`smokeTest` 自动依赖 `downloadTools` -- 已有工具时自动跳过（`onlyIf { !bin.exists() }`） -- 使用 Gradle 原生 API（`ant.get` + `tarTree`），无需额外插件 - -### 2. Flaky Test 治理 ✅ - -- **新建 `@Flaky` 注解**：`reason`（必填）、`since`、`issue` 三个字段 -- **新建 `FlakyTestListener`**（实现 `ITestListener`）：分离统计 flaky 测试的通过/失败，suite 结束时打印摘要报告 -- 注册到 `daily-build-main.xml` -- **标记 10 个已知 flaky 测试类**：FreezeBalanceV2Test001/003/004/006/007、TvmVote、UsdtTest002、KillContract01、HttpTestFreezeV2001、ContractInternalTransaction002 - -### 3. 覆盖率 PR 门禁 ✅ - -- `ci.yml` 新增 `coverage-gate` job：PR 时执行 `./gradlew coverageCheck` -- 阈值：全局 ≥10%，utils 包 ≥20%（渐进提升策略） - -### 4. MongoBase 继承链改造 ✅ - -- `MongoBase.java` 改为 `extends TronBaseTest`，添加 `@Slf4j`，新增 `mongoAvailable` 标志 -- `MongoEventQuery001-005` 去除冗余字段和手动 channel 管理 - -### 5. Groups 注解补全 ✅ - -5 个文件补上 `groups = {"daily"}`：MongoEventQuery001/002/005、WalletTestAssetIssue016/020 - -### 6. HTTP 测试并发优化 ✅ - -- `HttpMethod.java`：删除 7 个 static 共享可变字段，改为方法内局部变量 -- `daily-build-main.xml`：HTTP 测试从 Serial Case（thread=1）移入 Parallel Case（thread=8） -- 35 个 HTTP 测试现在可并发执行 - -### 7. 安全/攻击模拟测试 ✅（Phase 3） - -5 个 Solidity 攻击合约 + 5 个 Java 测试类 + 31 个测试方法： -- SecurityReentrancy（重入）、SecurityOverflow（溢出）、SecuritySelfdestruct（自毁） -- SecurityPermission（权限）、SecurityEnergyBomb（能量炸弹） - -### 8. 社区建设 ✅（Phase 3） - -- `docs/GOOD_FIRST_ISSUES.md`：24 个新手任务 -- `.github/ISSUE_TEMPLATE/good_first_issue.md`：Issue 模板 -- `CONTRIBUTORS.md`：贡献者指南 -- `README.md`：新增 "Get Involved" 版块 - ---- - -## 二、组网文档与 Docker 环境（下午） - -### 9. NETWORK.md 组网拓扑文档 ✅ - -`docs/NETWORK.md` — 面向社区的组网指南（699 行）： -- ASCII 拓扑图（单节点 / 多节点 / DPoS 出块流程） -- 完整端口映射表（gRPC/HTTP/JSON-RPC/P2P/Event） -- 可复制的 config.conf 完整示例 -- 测试套件与组网模式对应关系 -- Docker 环境章节（单节点/多节点/MongoDB 启动命令） -- 环境自动检测章节 - -### 10. 多节点配置文件 ✅ - -| 文件 | 用途 | -|------|------| -| `docs/config-node1.conf` | 多节点 SR1(Mercury)，端口 50051/8090/50545，P2P 18889 | -| `docs/config-node2.conf` | 多节点 SR2(Venus)，端口 50052/8092/50546，P2P 18892 | -| `docker/node1/config.conf` | Docker 版 SR1（同 docs 版） | -| `docker/node2/config.conf` | Docker 版 SR2（同 docs 版） | - -关键差异： -- `localwitness`：各含 1 个 SR 密钥（单节点含全部） -- `needSyncCheck`：node1=false（首节点），node2=true -- 端口偏移：node2 全部 +1（50052/8092/50546 等） -- Storage 目录分离：node2 用 `database2/index2` - -### 11. Docker 环境重写 ✅ - -**`docker/node/config.conf`** — 完全重写： -- 旧版 genesis/committee 与 testng.conf 完全不匹配，已全面对齐 -- 加入所有 committee 开关、Solidity/PBFT 端口、event subscribe - -**`docker/docker-compose.yml`** — 完全重写： -- 默认：`docker compose up -d tron-node` → 单节点 -- `--profile multi`：双 SR 节点（tron-node1 + tron-node2） -- `--profile mongo`：MongoDB（事件查询测试） -- 全部使用 `network_mode: host` -- 启动命令加 `--es`（事件订阅） -- 配置差异对比表写入 NETWORK.md - -### 12. @MultiNode 环境自动检测机制 ✅ - -**新建文件：** -- `@MultiNode` 注解（`MultiNode.java`）— 标记需要多节点的测试类 -- `MultiNodeListener.java` — ISuiteListener + IClassListener - -**检测逻辑：** -1. 读 testng.conf 的 `fullnode.ip.list` -2. `[0]` == `[1]`（同地址） → 单节点 -3. `[1]` 不同但 TCP 探测失败（3s 超时） → 单节点 -4. `[1]` 不同且可达 → 多节点 -5. 单节点时自动 SkipException 所有 `@MultiNode` 类 - -**系统属性覆盖：** `-Dtron.test.multinode=true/false` - -**已注册到：** `daily-build-main.xml`、`single-node-build.xml` - -**编译验证：** 通过 - ---- - -## 三、Phase 3 多节点测试规划（未开始编码） - -### 规划的 4 大块测试 - -#### DPoS 共识测试 (`dailybuild/consensus/`) -- WitnessElectionTest — SR 选举排名、投票后 witness list 变化 -- MaintenancePeriodTest — 等 maintenance 周期(20s)、验证更新 -- BlockProductionTest — 出块轮次、block header witness 地址 -- VoteWeightTest — 投票权重、委托 - -#### P2P 网络测试 (`dailybuild/network/`) -- TransactionBroadcastTest — node1 发交易，node2 确认收到 -- BlockSyncTest — 两节点 block height 同步 -- CrossNodeConsistencyTest — 账户余额/合约状态一致性 - -#### 性能基准测试 (`dailybuild/performance/`) -- ThroughputBenchmarkTest — 批量发交易测 TPS -- BlockLatencyTest — 出块间隔统计 -- ApiLatencyTest — API 响应时间 - -#### Fuzzing (`fuzz/`) -- TransactionFuzzTest — 交易字段 fuzz -- ContractBytecodeFuzzTest — 随机字节码部署 -- GrpcMessageFuzzTest — gRPC 消息 fuzz - -**状态：** 目录已创建，调研完成，代码未开始编写。 - ---- - -## 文件变更清单 - -### 新建 - -| 文件 | 类型 | -|------|------| -| `docs/NETWORK.md` | 文档 | -| `docs/config-node1.conf` | 配置 | -| `docs/config-node2.conf` | 配置 | -| `docker/node1/config.conf` | 配置 | -| `docker/node2/config.conf` | 配置 | -| `@Flaky` 注解 | Java | -| `FlakyTestListener` | Java | -| `@MultiNode` 注解 | Java | -| `MultiNodeListener` | Java | -| `SecurityReentrancy/Overflow/Selfdestruct/Permission/EnergyBomb` .sol + Test.java | Solidity + Java | -| `docs/GOOD_FIRST_ISSUES.md` | 文档 | -| `.github/ISSUE_TEMPLATE/good_first_issue.md` | 模板 | -| `CONTRIBUTORS.md` | 文档 | -| Gradle downloadGrpcurl/downloadSolc/downloadTools tasks | Gradle | -| `ci.yml` coverage-gate job | CI | - -### 修改 - -| 文件 | 改动 | -|------|------| -| `docker/node/config.conf` | 重写对齐 testng.conf | -| `docker/docker-compose.yml` | 重写，支持 multi/mongo profiles | -| `daily-build-main.xml` | 注册 FlakyTestListener + MultiNodeListener，HTTP 移入 Parallel | -| `single-node-build.xml` | 注册 MultiNodeListener | -| `HttpMethod.java` | 去 static 共享状态，支持并发 | -| `MongoBase.java` | 改继承 TronBaseTest，graceful skip | -| `MongoEventQuery001-005` | 去冗余字段 | -| 10 个 flaky 测试类 | 加 @Flaky 注解 | -| 5 个文件 | 补 groups={"daily"} | -| `README.md` | 加社区版块 | - -### 综合评分 - -4.5 → ~7.0/10（三阶段单节点可做项全部完成） - -### 未完成 - -- 183 个 dailybuild 类待批量加 `@MultiNode` 注解 -- Phase 3 多节点测试代码待编写（DPoS/P2P/性能/Fuzzing） -- 服务器部署验证 -- 提交 PR（等用户要求） diff --git a/docs/worklog-2026-04-05.md b/docs/worklog-2026-04-05.md deleted file mode 100644 index b40b7cb8..00000000 --- a/docs/worklog-2026-04-05.md +++ /dev/null @@ -1,254 +0,0 @@ -# 工作日志 2026-04-05 - -## 概要 - -Phase 4（紧急修复）实测通过 12/12 + Phase 5（质量深化）完成 + Phase 6（中文文档）完成 + ProposalSetupListener 统一提案基础设施。评分从 7.5 提升至 9.0。 - ---- - -## Phase 4 — Security 测试修复 - -### 根因：deployContract 的 data 参数是死代码 - -`ContractHelper.deployContract()` 的 `data` 参数完全被忽略，构造函数参数不会被 ABI 编码追加到 bytecode。需要构造参数的合约必须用 `deployContractWithConstantParame()`。 - -### SecurityReentrancyTest - -- **问题**：Attacker 合约有 `constructor(address)`，用 `deployContract` 部署 → 构造参数丢失 → 部署失败 → NPE -- **修复**：改用 `deployContractWithConstantParame("constructor(address)", ...)`，从 `TransactionInfo.getContractAddress()` 获取合约地址 -- **文件**：`testcase/src/test/java/stest/tron/wallet/dailybuild/security/SecurityReentrancyTest.java` - -### SecurityPermissionTest - -- **问题**：PermissionCaller 合约同样有 `constructor(address)`，同上 -- **修复**：同上 -- **文件**：`testcase/src/test/java/stest/tron/wallet/dailybuild/security/SecurityPermissionTest.java` - -### SecurityOverflowTest - -- **发现**：TVM（solc.tron fork）不实现 Solidity 0.8 checked arithmetic。overflow 直接 wrap 而非 revert，checked 和 unchecked 行为相同 -- **修复**：重写测试为验证+记录 TVM 实际行为（不硬断言 revert），两种行为都能通过 -- **附加修复**：`getConstantResult` 返回字节 > 32 时需用 `extractUint256()` 截取后 32 字节 -- **附加**：用 `TestAccountFactory.funded()` 替代手动 ECKey 生成样板代码 -- **文件**：`testcase/src/test/java/stest/tron/wallet/dailybuild/security/SecurityOverflowTest.java` - -### SecuritySelfdestructTest - -- **发现1**：TRON protobuf ABI 不支持 `"type":"receive"`，`jsonStr2Abi` 解析到 receive 返回 null → `deployContract` 返回 null -- **修复1**：`SecuritySelfdestruct.sol` 中 `receive() external payable {}` → `fallback() external payable {}` -- **发现2**：TIP-481（`allowTvmSelfdestructRestriction`）是链上治理提案（编号 #76），不是配置文件开关。通过 testng.conf 的 `commitData "76:1"` 在 @BeforeSuite 中自动开启 -- **修复2**：用 `PublicMethod.allowTvmSelfdestructRestrictionIsActive()` 检测并分支断言 -- **附加**：test02 适配 EIP-6780（代码持久化 vs 删除两种行为），test04 用 `internalTransactions` 提取子合约地址 -- **文件**：`testcase/src/test/java/stest/tron/wallet/dailybuild/security/SecuritySelfdestructTest.java`，`testcase/src/test/resources/soliditycode/security/SecuritySelfdestruct.sol` - -### SecurityEnergyBombTest - -- **问题**：test05 的 `expensiveComputation(999999)` constant call 返回 `REVERT opcode executed`，但断言条件只匹配 CPU/timeout/energy -- **修复**：加 REVERT 匹配条件，改为验证小/中/大三级输入的行为差异 -- **文件**：`testcase/src/test/java/stest/tron/wallet/dailybuild/security/SecurityEnergyBombTest.java` - -### Solidity 合约目录 - -- 5 个 `Security*.sol` 从 `soliditycode/` 移入 `soliditycode/security/` 子目录 -- 5 个 Java 测试文件更新路径引用 - ---- - -## Phase 4 — Consensus 测试修复 - -### VoteWeightTest - -- **问题**：`freezeBalanceGetTronPower`（旧 Freeze v1 API）返回 false，Stake 2.0 节点不支持 -- **修复**：改用 `freezeBalanceV2`，查询 `frozenV2List` 替代旧 `tronPower` -- **附加**：test04 空 voteMap 投票不被 TRON 接受，改为小额重投验证 -- **文件**：`testcase/src/test/java/stest/tron/wallet/dailybuild/consensus/VoteWeightTest.java` - -### WitnessElectionTest - -- **问题**：test03 同样用旧 freeze API；test04 假设 ListWitnesses 返回降序排列但 API 不保证 -- **修复**：test03 改用 `freezeBalanceV2`；test04 改为验证 voteCount >= 0 -- **文件**：`testcase/src/test/java/stest/tron/wallet/dailybuild/consensus/WitnessElectionTest.java` - -### BlockProductionTest - -- **问题**：`getBlock(-1, blockingStubFull)` 调用 `getBlockByNum(-1)` 在 TRON gRPC 中返回空块（number=0），不是获取最新块的正确方式 -- **修复**：改用 `blockingStubFull.getNowBlock(EmptyMessage)`；beforeClass 加 2 次 waitProduceNextBlock 预热 -- **文件**：`testcase/src/test/java/stest/tron/wallet/dailybuild/consensus/BlockProductionTest.java` - -### BlockLatencyTest（Performance） - -- **同上**：`getBlock(-1)` → `getNowBlock(EmptyMessage)` -- **文件**：`testcase/src/test/java/stest/tron/wallet/dailybuild/performance/BlockLatencyTest.java` - ---- - -## Phase 4 — 本地实测结果 - -12/12 新测试类全部通过，0 failures： - -| 类 | 结果 | -|----|------| -| SecurityOverflowTest (8 tests) | PASS | -| SecurityEnergyBombTest (7 tests) | PASS | -| SecurityReentrancyTest (4 tests) | PASS | -| SecurityPermissionTest (8 tests) | PASS | -| SecuritySelfdestructTest (4 tests) | PASS | -| VoteWeightTest (4 tests) | PASS | -| WitnessElectionTest (4 tests) | PASS | -| BlockProductionTest (4 tests) | PASS | -| MaintenancePeriodTest (3 tests) | PASS | -| ThroughputBenchmarkTest (1 test) | PASS | -| BlockLatencyTest (2 tests) | PASS | -| ApiLatencyTest (5 tests) | PASS | - ---- - -## Phase 5 — 质量深化 - -### 5.1 FailureClassifier（失败自动分类） - -- 新建 `FailureClassifier.java`（ITestListener），6 类自动分类：ENV_NODE_DOWN / ENV_SINGLE_NODE / ENV_NO_MONGO / FLAKY / TIMEOUT / BUG -- Suite 结束时打印 Failure Classification Summary，标注 Actionable Bugs 数量 -- 注册到 daily-build-main.xml、smoke-test.xml、single-node-build.xml -- **文件**：`testcase/src/test/java/stest/tron/wallet/common/client/utils/FailureClassifier.java` - -### 5.2 PublicMethod @Deprecated - -- Python 脚本批量给 216 个已转发到 Helper 的方法加 `@Deprecated` 注解 -- PublicMethod 类添加 Javadoc，列出所有 Helper 类及其职责，引导新代码直接用 Helper -- **文件**：`testcase/src/test/java/stest/tron/wallet/common/client/utils/PublicMethod.java` - -### 5.3 Solidity security/ 子目录 - -- 5 个 `Security*.sol` 移入 `soliditycode/security/` -- 5 个 Java 测试文件路径引用更新 -- **文件**：`testcase/src/test/resources/soliditycode/security/` - -### 5.4 TestAccountFactory - -- 新建工具类，提供 `funded()` 和 `unfunded()` 方法 -- 将 8 行 ECKey 生成 + 转账 + 等块样板代码缩减为 2 行 -- SecurityOverflowTest 已改为使用 TestAccountFactory 作为示范 -- **文件**：`testcase/src/test/java/stest/tron/wallet/common/client/utils/TestAccountFactory.java` - -### 5.5 覆盖率阈值提升 - -- JaCoCo 全局阈值：10% → 15% -- utils 包阈值：20% → 30% -- **文件**：`testcase/build.gradle` - ---- - -## Phase 6 — 社区与文档 - -### 6.1 README_CN.md - -- 完整中文版 README，包含技术栈、项目结构、快速开始、配置说明 -- 英文 README 顶部添加语言切换链接 -- **文件**：`README_CN.md`，`README.md` - -### 6.2 SETUP_CN.md - -- 中文安装指南：5 分钟快速开始、工具手动安装（国内网络适配）、Gradle 代理配置 -- 英文 SETUP.md 顶部添加语言切换链接 -- **文件**：`docs/SETUP_CN.md`，`docs/SETUP.md` - -### 6.3 FAQ.md - -- 10 个常见问题：区块号为 0 / 连接拒绝 / grpcurl 失败 / solc 报错 / 国内下载超时 / Solidity 查询空 / MongoDB skip / JDK 版本 / OOM / 失败分类 -- **文件**：`docs/FAQ.md` - -### 6.4 文档导航更新 - -- README.md 文档表添加 FAQ、NETWORK、中文版入口 -- **文件**：`README.md` - ---- - -## 基础设施改进 — ProposalSetupListener - -### 问题 - -singleNodeBuild 不含 jsonrpc 包 → JsonRpcBase 的 @BeforeSuite 不触发 → 链上提案没开 → 多出 ~20 个失败。dailyBuild 和 singleNodeBuild 行为不一致。 - -### 解决方案 - -- 新建 `ProposalSetupListener`（ISuiteListener），在所有 suite 启动时统一开提案 -- 读取 testng.conf 的 `commitData.commit.list` 和 `secondCommit.list` -- 幂等设计：先检查链参数，已生效则 skip；createProposal 失败时 warn + skip（不终止 suite） -- 注册到 daily-build-main.xml、single-node-build.xml、smoke-test.xml、testng.xml - -### JsonRpcBase 兼容修复 - -- `openProposal` 中 `createProposal` 失败时 return 而非 Assert，避免与 ProposalSetupListener 重复创建冲突 - -### 文件 - -- 新建：`testcase/src/test/java/stest/tron/wallet/common/client/utils/ProposalSetupListener.java` -- 修改：`testcase/src/test/java/stest/tron/wallet/common/client/utils/JsonRpcBase.java` -- 修改：5 个 suite XML - ---- - -## 已知遗留问题 - -### WalletTestZenToken001 @BeforeSuite 级联 skip - -- `WalletTestZenToken001.beforeSuite` 在 shield 功能不可用时失败 -- TestNG 中任一 @BeforeSuite 失败 → 整个 suite 全部 skip（800 tests → 799 ignored） -- 这是 system-test 的**原有设计问题**，不是重构引入的 -- 后续方案：@BeforeSuite 加 try-catch 防级联，或改为 @BeforeClass - ---- - -## TVM vs EVM 关键差异（实测发现） - -| # | 差异 | 影响 | -|---|------|------| -| 1 | TVM 不实现 Solidity 0.8 checked arithmetic（overflow wrap 而非 revert） | SecurityOverflowTest 需适配 | -| 2 | `getBlockByNum(-1)` 返回空块，需用 `getNowBlock(EmptyMessage)` | BlockProductionTest / BlockLatencyTest | -| 3 | TRON protobuf ABI 不支持 `"type":"receive"`，用 `fallback()` 替代 | SecuritySelfdestruct.sol | -| 4 | `deployContract` 的 `data` 参数是死代码，需用 `deployContractWithConstantParame` | 所有带构造参数的合约部署 | -| 5 | TIP-481 selfdestruct 限制是链上治理提案(#76)，不是配置文件 | SecuritySelfdestructTest 需检测 | - ---- - -## 全部文件变更清单 - -### 新建 - -| 文件 | 说明 | -|------|------| -| `testcase/.../utils/FailureClassifier.java` | 失败自动分类 Listener | -| `testcase/.../utils/TestAccountFactory.java` | 测试账户工厂 | -| `testcase/.../utils/ProposalSetupListener.java` | 统一提案开启 Listener | -| `testcase/.../soliditycode/security/` | Solidity 安全合约子目录 | -| `README_CN.md` | 中文 README | -| `docs/SETUP_CN.md` | 中文安装指南 | -| `docs/FAQ.md` | 常见问题 | -| `docs/worklog-2026-04-05.md` | 本工作日志 | - -### 修改 - -| 文件 | 说明 | -|------|------| -| `SecurityReentrancyTest.java` | constructor 部署方式修复 | -| `SecurityPermissionTest.java` | constructor 部署方式修复 | -| `SecurityOverflowTest.java` | TVM overflow 行为适配 + TestAccountFactory | -| `SecuritySelfdestructTest.java` | TIP-481 适配 + EIP-6780 + fallback | -| `SecurityEnergyBomb.sol` | receive → fallback | -| `SecuritySelfdestruct.sol` | receive → fallback | -| `SecurityEnergyBombTest.java` | REVERT 匹配 + 防御检查 | -| `VoteWeightTest.java` | freezeBalanceV2 + 重投 | -| `WitnessElectionTest.java` | freezeBalanceV2 + 排序断言 | -| `BlockProductionTest.java` | getNowBlock + 预热 | -| `BlockLatencyTest.java` | getNowBlock | -| `PublicMethod.java` | 216 方法 @Deprecated + Javadoc | -| `JsonRpcBase.java` | openProposal 容错 | -| `testcase/build.gradle` | 覆盖率 15%/30% | -| `daily-build-main.xml` | +FailureClassifier +ProposalSetupListener | -| `single-node-build.xml` | +FailureClassifier +ProposalSetupListener | -| `smoke-test.xml` | +FailureClassifier +ProposalSetupListener | -| `testng.xml` | +ProposalSetupListener | -| `README.md` | 语言切换 + 文档导航更新 | -| `docs/SETUP.md` | 语言切换链接 | diff --git a/protocol/src/main/protos/Chinese version of TRON Protocol document.md b/protocol/src/main/protos/Chinese version of TRON Protocol document.md deleted file mode 100644 index 283bd5fb..00000000 --- a/protocol/src/main/protos/Chinese version of TRON Protocol document.md +++ /dev/null @@ -1,696 +0,0 @@ -# TRON protobuf protocol - -## TRON使用Google protobuf协议，协议内容涉及到账户，区块，传输多个层面。 - -+ 账户有基本账户、资产发布账户和合约账户三种类型。一个账户包含：账户名称，账户类型，地址，余额，投票，其他资产6种属性。 -+ 更进一步的，基本账户可以申请成为验证节点，验证节点具有额外的属性，投票统计数目，公钥，URL，以及历史表现等参数。 - - 3种`Account`类型：`Normal`，`AssetIssue`，`Contract`。 - - enum AccountType {
 - Normal = 0;
 - AssetIssue = 1;
 - Contract = 2;
 - } - - 一个`Account`包含7种参数： - `account_name`：该账户的名称——比如： ”_SicCongsAccount_”。 - `type`:该账户的类型——比如： _0_ 代表的账户类型是`Normal`。 - `balance`:该账户的TRX余额——比如：_4213312_。 - `votes`:账户所得投票数——比如：_{(“0x1b7w…9xj3”,323),(“0x8djq…j12m”,88),…,(“0x82nd…mx6i”,10001)}_。 - `asset`：除TRX以外账户上的其他资产——比如：_{<”WishToken”,66666>,<”Dogie”,233>}_。 - `latest_operation_time`: 该账户的最新活跃时间。 - - // Account
 - message Account {
 - message Vote {
 - bytes vote_address = 1;
 - int64 vote_count = 2;
 - }
 - bytes accout_name = 1;
 - AccountType type = 2;
 - bytes address = 3;
 - int64 balance = 4;
 - repeated Vote votes = 5;
 - map asset = 6;
 - int64 latest_operation_time = 10; - } - - 一个`Witness`包含8种参数： - `address`：验证节点的地址——比如：_“0xu82h…7237”_。 - `voteCount`：验证节点所得投票数——比如：_234234_。 - `pubKey`：验证节点的公钥——比如：_“0xu82h…7237”_。 - `url`：验证节点的url链接。 - `totalProduce`：验证节点产生的区块数——比如：_2434_。 - `totalMissed`：验证节点丢失的区块数——比如：_7_。 - `latestBlockNum`：最新的区块高度——比如：_4522_。 - `isJobs`：布尔表类型标志位。 - - // Witness
 - message Witness {
 - bytes address = 1;
 - int64 voteCount = 2;
 - bytes pubKey = 3;
 - string url = 4;
 - int64 totalProduced = 5;
 - int64 totalMissed = 6;
 - int64 latestBlockNum = 7; - bool isJobs = 9; - 
} - -+ 一个区块由区块头和多笔交易构成。区块头包含时间戳，交易字典树的根，父哈希，签名等区块基本信息。 - - 一个`block`包含`transactions`和`block_header`。 - `transactions`：区块里的交易信息。 - `block_header`：区块的组成部分之一。 - - // block
 - message Block {
 - repeated Transaction transactions = 1;
 - BlockHeader block_header = 2; - 
} - - `BlockHeader` 包括`raw_data`和`witness_signature`。 - `raw_data`：`raw`信息。 - `witness_signature`：区块头到验证节点的签名。 - - message `raw`包含6种参数： - `timestamp`：该消息体的时间戳——比如：_14356325_。 - `txTrieRoot`：Merkle Tree的根——比如：_“7dacsa…3ed”_。 - `parentHash`：上一个区块的哈希值——比如：_“7dacsa…3ed”_。 - `number`：区块高度——比如：_13534657_。 - `witness_id`：验证节点的id——比如：_“0xu82h…7237”_。 - `witness_address`：验证节点的地址——比如：_“0xu82h…7237”_。 - - message BlockHeader {
 - message raw {
 - int64 timestamp = 1;
 - bytes txTrieRoot = 2;
 - bytes parentHash = 3;
 - //bytes nonce = 5;
 - //bytes difficulty = 6;
 - uint64 number = 7;
 - uint64 witness_id = 8;
 - bytes witness_address = 9;
 - }
 - raw raw_data = 1;
 - bytes witness_signature = 2; - 
} - - 消息体 `ChainInventory` 包括 `BlockId` 和 `remain_num`。 - `BlockId`: block的身份信息。 - `remain_num`：在同步过程中，剩余的区块数量。 - - A `BlockId` contains 2 parameters: - `hash`: 该区块的哈希值。 - `number`: 哈希值和高度即为当前区块块号。 - - message ChainInventory { - message BlockId { - bytes hash = 1; - int64 number = 2; - } - repeated BlockId ids = 1; - int64 remain_num = 2; - } - -+ 交易合约有多种类型，包括账户创建合约、账户更新合约、转账合约、转账断言合约、资产投票合约、见证节点投票合约、见证节点创建合约、见证节点更新合约、资产发布合约、参与资产发布和与部署合约11种类型。 - - `AccountCreatContract`包含3种参数： - `type`：账户类型——比如：_0_ 代表的账户类型是`Normal`。 - `account_name`： 账户名称——比如： _"SiCongsaccount”_。 - `owner_address`：合约持有人地址——比如： _“0xu82h…7237”_。 - - message AccountCreateContract {
 - AccountType type = 1;
 - bytes account_name = 2;
 - bytes owner_address = 3;
 - } - `AccountUpdateContract`包含2种参数： - `account_name`： 账户名称——比如： _"SiCongsaccount”_。 - `owner_address`：合约持有人地址——比如： _“0xu82h…7237”_。 - - message AccountUpdateContract { - bytes account_name = 1; - bytes owner_address = 2; - } - - `TransferContract`包含3种参数： - `amount`：TRX数量——比如：_12534_。 - `to_address`： 接收方地址——比如：_“0xu82h…7237”_。 - `owner_address`：合约持有人地址——比如：_“0xu82h…7237”_。 - - message TransferContract {
 - bytes owner_address = 1;
 - bytes to_address = 2;
 - int64 amount = 3; - 
} - - `TransferAssetContract`包含4种参数： - `asset_name`：资产名称——比如：_”SiCongsaccount”_。 - `to_address`：接收方地址——比如：_“0xu82h…7237”_。 - `owner_address`：合约持有人地址——比如：_“0xu82h…7237”_。 - `amount`：目标资产数量——比如：_12353_。 - - message TransferAssetContract {
 - bytes asset_name = 1;
 - bytes owner_address = 2;
 - bytes to_address = 3;
 - int64 amount = 4;
 - } - - `VoteAssetContract`包含4种参数： - `vote_address`：投票人地址——比如：_“0xu82h…7237”_。 - `support`：投票赞成与否——比如：_true_。 - `owner_address`：合约持有人地址——比如：_“0xu82h…7237”_。 - `count`：投票数目——比如：_2324234_。 - - message VoteAssetContract {
 - bytes owner_address = 1;
 - repeated bytes vote_address = 2;
 - bool support = 3;
 - int32 count = 5; - } - - `VoteWitnessContract`包含4种参数： - `vote_address`：投票人地址——比如：_“0xu82h…7237”_。 - `support`：投票赞成与否——比如：_true_。 - `owner_address`：合约持有人地址——比如：_“0xu82h…7237”_。 - `count`：投票数目——比如：_32632_。 - - message VoteWitnessContract {
 - bytes owner_address = 1;
 - repeated bytes vote_address = 2;
 - bool support = 3;
 - int32 count = 5;
 - } - - `WitnessCreateContract`包含3种参数： - `private_key`：合约的私钥——比如：_“0xu82h…7237”_。 - `owner_address`：合约持有人地址——比如：_“0xu82h…7237”_。 - `url`：合约的url链接。 - - message WitnessCreateContract {
 - bytes owner_address = 1;
 - bytes private_key = 2;
 - bytes url = 12; - 
} - - `WitnessUpdateContract`包含2种参数： - `owner_address`：合约持有人地址——比如：_“0xu82h…7237”_。 - `update_url`：合约的url链接。 - - message WitnessUpdateContract { - bytes owner_address = 1; - bytes update_url = 12; - } - - `AssetIssueContract`包含11种参数： - `name`：合约名称——比如：_“SiCongcontract”_。 - `total_supply`：合约的赞成总票数——比如：_100000000_。 - `owner_address`：合约持有人地址——比如：_“0xu82h…7237”_。 - `trx_num`：对应TRX数量——比如：_232241_。 - `num`： 对应的自定义资产数目。 - `start_time`：开始时间——比如：_20170312_。 - `end_time`：结束时间——比如：_20170512_。 - `vote_score`：合约的评分——比如：_12343_。 - `description`：合约的描述——比如：_”trondada”_。 - `url`：合约的url地址链接。 - - message AssetIssueContract {
 - bytes owner_address = 1;
 - bytes name = 2;
 - int64 total_supply = 4;
 - int32 trx_num = 6;
 - int32 num = 8;
 - int64 start_time = 9;
 - int64 end_time = 10;
 - int32 vote_score = 16;
 - bytes description = 20;
 - bytes url = 21;
 - } - - `ParticipateAssetIssueContract`包含4种参数： - `owner_address`：合约持有人地址——比如：_“0xu82h…7237”_。 - `to_address`：接收方地址——比如：_“0xu82h…7237”_。 - `asset_name`: 目标资产的名称。 - `amount`： 小部分数量。 - - `DeployContract`包含2种参数： - `script`：脚本。 - `owner_address`：合约持有人地址——比如：_“0xu82h…7237”_。 - - message DeployContract {
 - bytes owner_address = 1;
 - bytes script = 2;
 - } - - 消息体 `Result` 包含 `fee` and `ret`2个参数. - `ret`: 交易结果。 - `fee`: 交易扣除的费用。 - - `code`是`ret`的类型定义，有`SUCCESS`和`FAILED`两种类型。 - - message Result { - enum code { - SUCESS = 0; - FAILED = 1; - } - int64 fee = 1; - code ret = 2; - } - -+ 每一个交易还包含多个输入与多个输出，以及其他一些相关属性。其中交易内的输入，交易本身，区块头均需签名。 - - 消息体 `Transaction`包括`raw_data`和`signature`。 - `raw_data`: 消息体`raw`。 - `signature`: 所有输入节点的签名。 - - `raw_data`包含8种参数： - `type`：消息体raw的交易类型。 - `vin`： 输入值。 - `vout`： 输出值。 - `expiration`：过期时间——比如：_20170312_。 - `data`： 数据。 - `contract`： 该交易内的合约。 - `script`： 脚本。 - `timestamp`：该消息体的时间戳。 - - 消息体 `Contract`包含`type`和`parameter`。 - `type`：合约的类型。 - `parameter`：任意参数。 - - 有八种账户类型合约：`AccountCreateContract`，`TransferContract`，`TransferAssetContract`，`VoteAssetContract`，`VoteWitnessContract`，`WitnessCreateContract`，`AssetIssueContract` 和`DeployContract`。 - - `TransactionType`包括`UtxoType`和`ContractType`。 - - message Transaction {
 - enum TranscationType {
 - UtxoType = 0;
 - ContractType = 1;
 - }
 - message Contract {
 - enum ContractType {
 - AccountCreateContract = 0;
 - TransferContract = 1;
 - TransferAssetContract = 2;
 - VoteAssetContract = 3;
 - VoteWitnessContract = 4;
 - WitnessCreateContract = 5;
 - AssetIssueContract = 6;
 - DeployContract = 7;
 - }
 - ContractType type = 1;
 - google.protobuf.Any parameter = 2;
 - }
 - message raw {
 - TranscationType type = 2;
 - repeated TXInput vin = 5;
 - repeated TXOutput vout = 7;
 - int64 expiration = 8;
 - bytes data = 10;
 - repeated Contract contract = 11;
 - bytes scripts = 16;
 - in64 timestamp = 17; - }
 - raw raw_data = 1;
 - repeated bytes signature = 5;
 - } - - 消息体 `TXOutputs`由`outputs`构成。 - `outputs`: 元素为`TXOutput`的数组。 - - message TXOutputs {
 - repeated TXOutput outputs = 1; - 
} - - 消息体 `TXOutput`包括`value`和`pubKeyHash`。 - `value`：输出值。 - `pubKeyhash`：公钥的哈希。 - - message TXOutput {
 - int64 value = 1;
 - bytes pubKeyHash = 2; - 
} - - 消息体 `TXIutput`包括`raw_data`和`signature`。 - `raw_data`：消息体`raw`。 - `signature`：`TXInput`的签名。 - - 消息体 `raw`包含`txID`，`vout`和 `pubKey`。 - `txID`：交易ID。 - `Vout`：上一个输出的值。 - `pubkey`:公钥。 - - message TXInput {
 - message raw {
 - bytes txID = 1;
 - int64 vout = 2;
 - bytes pubKey = 3;
 - }
 - raw raw_data = 1;
 - bytes signature = 4;
} - -+ 传输涉及的协议Inventory主要用于传输中告知接收方传输数据的清单。 - - `Inventory`包括`type`和`ids`。 - `type`：清单类型——比如：_0_ 代表`TRX`。 - `ids`：清单中的物品ID。 - - `InventoryType`包含`TRX`和 `BLOCK`。 - `TRX`：交易。 - `BLOCK`：区块。 - - // Inventory
 - message Inventory {
 - enum InventoryType {
 - TRX = 0;
 - BLOCK = 1;
 - }
 - InventoryType type = 1;
 - repeated bytes ids = 2; - 
} - - 消息体 `Items`包含4种参数： - `type`：物品类型——比如：_1_ 代表 `TRX`。 - `blocks`：物品中区块。 - `blockheaders`：区块头。 - `transactions`：交易。 - - `Items`有四种类型，分别是 `ERR`， `TRX`，`BLOCK` 和`BLOCKHEADER`。 - `ERR`：错误。 - `TRX`：交易。 - `BLOCK`：区块。 - `BLOCKHEADER`：区块头。 - - message Items {
 - enum ItemType {
 - ERR = 0;
 - TRX = 1;
 - BLOCK = 2;
 - BLOCKHEADER = 3;
 - }
 - ItemType type = 1;
 - repeated Block blocks = 2;
 - repeated BlockHeader block_headers = 3;
 - repeated Transaction transactions = 4;
 - } - - `Inventory`包含`type`和`items`。 - `type`：物品种类。 - `items`：物品清单。 - - message InventoryItems {
 - int32 type = 1;
 - repeated bytes items = 2;
 - } - - 消息体 `BlockInventory` 包含 `type`。 - `type`: 清单种类. - - 有三种类型:`SYNC`, `ADVTISE`, `FETCH`。 - - // Inventory - message BlockInventory { - enum Type { - SYNC = 0; - ADVTISE = 1; - FETCH = 2; - } - - 消息体 `BlockId` 包括 `ids` and `type`。 - `ids`: 区块身份信息。 - `type`: 区块类型。 - - `ids` 包含2种参数： - `hash`: 区块的哈希值。 - `number`: 哈希值和区块高度即为当前区块号。 - - message BlockId { - bytes hash = 1; - int64 number = 2; - } - repeated BlockId ids = 1; - Type type = 2; - } - - `ReasonCode` 有15种可能断开的原因: - `REQUESTED` - `TCP_ERROR` - `BAD_PROTOCOL` - `USELESS_PEER` - `TOO_MANY_PEERS` - `DUPLICATE_PEER` - `INCOMPATIBLE_PROTOCOL` - `NULL_IDENTITY` - `PEER_QUITING` - `UNEXPECTED_IDENTITY` - `LOCAL_IDENTITY` - `PING_TIMEOU` - `USER_REASON` - `RESET` - `UNKNOWN` - - enum ReasonCode { - REQUESTED = 0; - TCP_ERROR = 1; - BAD_PROTOCOL = 2; - USELESS_PEER = 3; - TOO_MANY_PEERS = 4; - DUPLICATE_PEER = 5; - INCOMPATIBLE_PROTOCOL = 6; - NULL_IDENTITY = 7; - PEER_QUITING = 8; - UNEXPECTED_IDENTITY = 9; - LOCAL_IDENTITY = 10; - PING_TIMEOUT = 11; - USER_REASON = 12; - RESET = 16; - UNKNOWN = 255; - } - - 消息体`DisconnectMessage`包含`reason`。 - `DisconnectMessage`：断开连接是的消息。 - `reason`：断开连接时的原因。 - - 消息体`HelloMessage`包含2个参数： - `from`请：求建立连接的节点。 - `version`：建立连接的节点。 - -+ 钱包服务RPC和区块链浏览器。 - - `Wallet`钱包服务包含多个RPC。 - __`Getbalance`__：获取`Account`的余额。 - __`CreatTransaction`__：通过`TransferContract`创建交易。 - __`BroadcastTransaction`__：广播`Transaction`。 - __`CreateAccount`__：通过`AccountCreateContract`创建账户。 - __`CreatAssetIssue`__：通过`AssetIssueContract`发布一个资产。 - __`ListAccounts`__：通过`ListAccounts`查看账户列表。 - __`UpdateAccount`__：通过`UpdateAccountContract`发布一个资产。 - __`VoteWitnessAccount`__：通过`VoteWitnessContract`发布一个资产。 - __`WitnessList`__：通过`WitnessList`查看见证节点列表。 - __`UpdateWitness`__：通过`WitnessUpdateContract`发布一个资产。 - __`CreateWitness`__：通过`WitnessCreateContract`发布一个资产。 - __`TransferAsset`__：通过`TransferAssetContract`发布一个资产。 - __`ParticipateAssetIssue`__：通过`ParticipateAssetIssueContract`发布一个资产。 - __`ListNodes`__：通过`ListNodes`查看节点列表。 - __`GetAssetIssueList`__：通过`GetAssetIssueList`查看资产发布节点列表。 - __`GetAssetIssueByAccount`__：通过`Account`获取发行资产。 - __`GetAssetIssueByName`__：通过`Name`获取发行资产。 - __`GetNowBlock`__：获取区块。 - __`GetBlockByNum`__：根据块号获取区块。 - __`TotalTransaction`__：查看总交易量。 - - service Wallet { - - rpc GetAccount (Account) returns (Account) { - - }; - - rpc CreateTransaction (TransferContract) returns (Transaction) { - - }; - - rpc BroadcastTransaction (Transaction) returns (Return) { - - }; - - rpc ListAccounts (EmptyMessage) returns (AccountList) { - - }; - - rpc UpdateAccount (AccountUpdateContract) returns (Transaction) { - - }; - - rpc CreateAccount (AccountCreateContract) returns (Transaction) { - - }; - - rpc VoteWitnessAccount (VoteWitnessContract) returns (Transaction) { - - }; - - rpc CreateAssetIssue (AssetIssueContract) returns (Transaction) { - - }; - - rpc WitnessList (EmptyMessage) returns (WitnessList) { - - }; - - rpc UpdateWitness (WitnessUpdateContract) returns (Transaction) { - - }; - - rpc CreateWitness (WitnessCreateContract) returns (Transaction) { - - }; - - rpc TransferAsset (TransferAssetContract) returns (Transaction) { - - } - - rpc ParticipateAssetIssue (ParticipateAssetIssueContract) returns (Transaction) { - - } - - rpc ListNodes (EmptyMessage) returns (NodeList) { - - } - rpc GetAssetIssueList (EmptyMessage) returns (AssetIssueList) { - - } - rpc GetAssetIssueByAccount (Account) returns (AssetIssueList) { - - } - rpc GetAssetIssueByName (BytesMessage) returns (AssetIssueContract) { - - } - rpc GetNowBlock (EmptyMessage) returns (Block) { - - } - rpc GetBlockByNum (NumberMessage) returns (Block) { - - } - rpc TotalTransaction (EmptyMessage) returns (NumberMessage) { - - } - }; - - `AccountList`： 区块链浏览器中的账户列表。 - 消息体 `AccountList` 包含1个参数： - `account`： - - message AccountList { - repeated Account accounts = 1; - } - - `WitnessList`：区块链浏览器中的见证节点列表。 - 消息体 `WitnessList` 包含1个参数： - `witnesses`： - - message WitnessList { - repeated Witness witnesses = 1; - } - - `AssetIssueList`：区块链浏览器中的发布资产列表。 - 消息体 `AssetIssueList` 包含1个参数: - `assetIssue`： - - message AssetIssueList { - repeated AssetIssueContract assetIssue = 1; - } - - - `NodeList`： 分布节点图中的节点列表。 - 消息体 `NodeList` 包含1个参数： - `nodes`： - - message NodeList { - repeated Node nodes = 1; - } - - `Address`: 节点地址。 - 消息体`Address` 包含2个参数： - `host`：节点所有者。 - `port`：节点的端口号。 - - message Address { - bytes host = 1; - int32 port = 2; - } - - - 消息体`Return`只含有一个参数： - `result`: 布尔表类型标志位。 - - message `Return` {
 - bool result = 1;
 - } - -+ 网络UDP消息结构。 - - `Endpoint`：网络中节点信息存储结构. - 消息体`Endpoint` 包含3个参数： - `address`：节点地址。 - `port`：端口号。 - `nodeId`： 节点ID信息。 - - message Endpoint { - bytes address = 1; - int32 port = 2; - bytes nodeId = 3; - } - - `PingMessage`：节点建立连接时所发送的消息。 - 消息体`PingMessage` 包含4个参数： - `from`：消息来自的节点。 - `to`： 消息发送的节点。 - `version`： 网络版本。 - `timestamp`：消息创建时的时间戳。 - - message PingMessage { - Endpoint from = 1; - Endpoint to = 2; - int32 version = 3; - int64 timestamp = 4; - } - - `PongMessage`：连接建立成功时的回复消息。 - 消息体`PongMessage` 包含3个参数： - `from`：消息来自的节点。 - `echo`： - `timestamp`：消息创建时的时间戳。 - - message PongMessage { - Endpoint from = 1; - int32 echo = 2; - int64 timestamp = 3; - } - - `FindNeighbours`：节点查询相邻节点时所发送的消息。 - 消息体`FindNeighbours` 包含3个参数： - `from`: 消息来自的节点。 - `targetId`: 目标节点的信息。 - `timestamp`: 消息创建时的时间戳。 - - message FindNeighbours { - Endpoint from = 1; - bytes targetId = 2; - int64 timestamp = 3; - } - - `Neighbour`：相邻接点回复消息。 - 消息体`Neighbours` 包含3个参数： - `from`: 消息来自的节点。 - `neighbours`: 相邻节点。 - `timestamp`: 消息创建时的时间戳。 - - message Neighbours { - Endpoint from = 1; - repeated Endpoint neighbours = 2; - int64 timestamp = 3; - } - -# 详细的协议见附属文件。详细协议随着程序的迭代随时都可能发生变化，请以最新的版本为准。 \ No newline at end of file diff --git a/testcase/config/checkstyle/checkStyle.xml b/testcase/config/checkstyle/checkStyle.xml deleted file mode 100644 index d5395fa7..00000000 --- a/testcase/config/checkstyle/checkStyle.xml +++ /dev/null @@ -1,237 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -