From 00989815a8028cce79c0a2bd361a60f44b049a2a Mon Sep 17 00:00:00 2001 From: GrapeS Date: Fri, 3 Jul 2026 16:26:15 +0800 Subject: [PATCH 01/32] docs(readme): add Documentation section linking guides and protocol doc --- README.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/README.md b/README.md index edf99c4df92..fda6850a0ca 100644 --- a/README.md +++ b/README.md @@ -20,6 +20,7 @@ - [Building the Source Code](#building-the-source-code) - [Executables](#executables) - [Running java-tron](#running-java-tron) +- [Documentation](#documentation) - [Community](#community) - [Contribution](#contribution) - [Resources](#resources) @@ -195,6 +196,21 @@ When exposing any of these APIs to a public interface, ensure the node is protec Public hosted HTTP endpoints for both mainnet and testnet are provided by TronGrid. Please refer to the [TRON Network HTTP Endpoints](https://developers.tron.network/docs/connect-to-the-tron-network#tron-network-http-endpoints) for the latest list. For supported methods and request formats, see the HTTP API reference above. +# Documentation + +More detailed guides live in the [`docs/`](./docs) directory: + +- **Configuration** + - [Configuration Reference](./docs/configuration.md) — full `config.conf` option reference + - [Configuration Conventions](./docs/configuration-conventions.md) +- **Modular architecture & deployment** + - [Modular Introduction](./docs/modular-introduction-en.md) · [中文](./docs/modular-introduction-zh.md) + - [Modular Deployment](./docs/modular-deployment-en.md) · [中文](./docs/modular-deployment-zh.md) +- **Extending java-tron** + - [Implement a Customized Actuator](./docs/implement-a-customized-actuator-en.md) · [中文](./docs/implement-a-customized-actuator-zh.md) +- **Protocol** + - [TRON Protobuf Protocol Document](./docs/protobuf-protocol-document.md) — the maintained, authoritative Protobuf protocol reference + # Community [TRON Developers & SRs](https://discord.gg/hqKvyAM) is TRON's official Discord channel. Feel free to join this channel if you have any questions. From 90dea2cc8a788f4b8ada33dc651e0fdc44eb1fee Mon Sep 17 00:00:00 2001 From: GrapeS Date: Fri, 3 Jul 2026 16:26:15 +0800 Subject: [PATCH 02/32] docs(config): add super-representative private-key security notes --- docs/configuration.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/configuration.md b/docs/configuration.md index d021326a15e..6604170c59c 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -165,6 +165,10 @@ localwitness = [ # localWitnessAccountAddress = "T..." ``` +> **Security — protect the block-producing key.** A Super Representative's key can produce blocks and control the account's funds. Prefer the encrypted `localwitnesskeystore` over a plaintext `localwitness` key, and: +> - Restrict the key/keystore file so other users on the host cannot read it: `chmod 600 `. +> - **Never commit a config file that contains a real private key to Git** — it stays in the history permanently. Add such files to `.gitignore` and keep the key file **outside** the repository directory. + ### JSON-RPC (Ethereum-compatible, `node.jsonrpc`) ```hocon From 6dea9d6589b5804039a4b4dafefcbb9736ece126 Mon Sep 17 00:00:00 2001 From: GrapeS Date: Fri, 3 Jul 2026 15:16:19 +0800 Subject: [PATCH 03/32] docs: move protocol document into docs/ with a shorter name --- .../protobuf-protocol-document.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename Tron protobuf protocol document.md => docs/protobuf-protocol-document.md (100%) diff --git a/Tron protobuf protocol document.md b/docs/protobuf-protocol-document.md similarity index 100% rename from Tron protobuf protocol document.md rename to docs/protobuf-protocol-document.md From b661d064e86932a363d12b2c8c87f77de819b133 Mon Sep 17 00:00:00 2001 From: GrapeS Date: Mon, 13 Jul 2026 11:23:50 +0800 Subject: [PATCH 04/32] docs: move metrics changelog into docs/ and link from README Co-Authored-By: Claude Opus 4.8 (1M context) --- README.md | 2 ++ METRICS_CHANGELOG.md => docs/metrics_changelog.md | 0 2 files changed, 2 insertions(+) rename METRICS_CHANGELOG.md => docs/metrics_changelog.md (100%) diff --git a/README.md b/README.md index fda6850a0ca..4c750fb8c70 100644 --- a/README.md +++ b/README.md @@ -210,6 +210,8 @@ More detailed guides live in the [`docs/`](./docs) directory: - [Implement a Customized Actuator](./docs/implement-a-customized-actuator-en.md) · [中文](./docs/implement-a-customized-actuator-zh.md) - **Protocol** - [TRON Protobuf Protocol Document](./docs/protobuf-protocol-document.md) — the maintained, authoritative Protobuf protocol reference +- **Observability** + - [Metrics Changelog](./docs/metrics_changelog.md) — Prometheus metric additions, changes, and removals across java-tron releases # Community diff --git a/METRICS_CHANGELOG.md b/docs/metrics_changelog.md similarity index 100% rename from METRICS_CHANGELOG.md rename to docs/metrics_changelog.md From 5d565d6cbc0b685f0bd0d331c97f1dc0155c6d6f Mon Sep 17 00:00:00 2001 From: GrapeS Date: Fri, 3 Jul 2026 16:26:15 +0800 Subject: [PATCH 05/32] docs: mark outdated protobuf protocol copies as superseded --- .../main/protos/Chinese version of TRON Protocol document.md | 2 ++ .../main/protos/English version of TRON Protocol document.md | 2 ++ 2 files changed, 4 insertions(+) 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 index f393447e42e..a2c6f6bddb1 100644 --- a/protocol/src/main/protos/Chinese version of TRON Protocol document.md +++ b/protocol/src/main/protos/Chinese version of TRON Protocol document.md @@ -1,3 +1,5 @@ +> ⚠️ **本副本已过时（最后更新于 2022 年）。** 维护中的权威协议文档是 [`docs/protobuf-protocol-document.md`](../../../../docs/protobuf-protocol-document.md)，请以该文件为准；此副本仅作历史参考保留。 + # TRON protobuf protocol ## TRON使用Google protobuf协议，协议内容涉及到账户，区块，传输多个层面。 diff --git a/protocol/src/main/protos/English version of TRON Protocol document.md b/protocol/src/main/protos/English version of TRON Protocol document.md index 7d23f5c1f49..8d176492859 100644 --- a/protocol/src/main/protos/English version of TRON Protocol document.md +++ b/protocol/src/main/protos/English version of TRON Protocol document.md @@ -1,4 +1,6 @@ +> ⚠️ **This copy is outdated (last updated 2022).** The maintained, authoritative protocol document is [`docs/protobuf-protocol-document.md`](../../../../docs/protobuf-protocol-document.md) — please refer to that file. This copy is kept only for historical reference. + # Protobuf protocol ## The protocol of TRON is defined by Google Protobuf and contains a range of layers, from account, block to transfer. From 6f1f3e9edaefee86ac05fe6d3df15074097c23be Mon Sep 17 00:00:00 2001 From: GrapeS Date: Mon, 13 Jul 2026 11:55:58 +0800 Subject: [PATCH 06/32] chore(ci): remove unused CodeClimate and Sonar configs Co-Authored-By: Claude Opus 4.8 (1M context) --- .codeclimate.yml | 6 ------ sonar-project.properties | 19 ------------------- 2 files changed, 25 deletions(-) delete mode 100644 .codeclimate.yml delete mode 100644 sonar-project.properties diff --git a/.codeclimate.yml b/.codeclimate.yml deleted file mode 100644 index 164135dd2de..00000000000 --- a/.codeclimate.yml +++ /dev/null @@ -1,6 +0,0 @@ -version: "2" -plugins: - sonar-java: - enabled: true - config: - sonar.java.source: 8 \ No newline at end of file diff --git a/sonar-project.properties b/sonar-project.properties deleted file mode 100644 index 220dbc068cc..00000000000 --- a/sonar-project.properties +++ /dev/null @@ -1,19 +0,0 @@ -sonar.projectKey=java-tron -sonar.projectName=java-tron -sonar.projectVersion=2.1 -# ===================================================== -# Meta-data for the project -# ===================================================== -sonar.links.homepage=https://github.com/tronprotocol/java-tron -sonar.links.ci=https://travis-ci.org/tronprotocol/java-tron -sonar.links.scm=https://github.com/tronprotocol/java-tron -sonar.links.issue=https://github.com/tronprotocol/java-tron/issues -# ===================================================== -# Properties that will be shared amongst all modules -# ===================================================== -# SQ standard properties -sonar.sources=./actuator/src,./framework/src/main,./consensus/src,./chainbase/src -sonar.java.binaries=./actuator/build/classes,./framework/build/classes,./consensus/build/classes,\ - ./chainbase/build/classes -# ===================================================== -# Properties that will be shared amongst all modules \ No newline at end of file From 21f7d6c8c0e55531a7bdae572862019252907dad Mon Sep 17 00:00:00 2001 From: GrapeS Date: Mon, 13 Jul 2026 15:30:46 +0800 Subject: [PATCH 07/32] delete .dockerignore --- .dockerignore | 3 --- 1 file changed, 3 deletions(-) delete mode 100644 .dockerignore diff --git a/.dockerignore b/.dockerignore deleted file mode 100644 index d171944d877..00000000000 --- a/.dockerignore +++ /dev/null @@ -1,3 +0,0 @@ -./* -!docker-entrypoint.sh - From f6ec27a72c34348a35bb5289c1d2d081b6821aec Mon Sep 17 00:00:00 2001 From: GrapeS Date: Tue, 14 Jul 2026 10:00:33 +0800 Subject: [PATCH 08/32] modify chinese --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 4c750fb8c70..7e2b27378ad 100644 --- a/README.md +++ b/README.md @@ -204,10 +204,10 @@ More detailed guides live in the [`docs/`](./docs) directory: - [Configuration Reference](./docs/configuration.md) — full `config.conf` option reference - [Configuration Conventions](./docs/configuration-conventions.md) - **Modular architecture & deployment** - - [Modular Introduction](./docs/modular-introduction-en.md) · [中文](./docs/modular-introduction-zh.md) - - [Modular Deployment](./docs/modular-deployment-en.md) · [中文](./docs/modular-deployment-zh.md) + - [Modular Introduction](./docs/modular-introduction-en.md) · [中文版](./docs/modular-introduction-zh.md) + - [Modular Deployment](./docs/modular-deployment-en.md) · [中文版](./docs/modular-deployment-zh.md) - **Extending java-tron** - - [Implement a Customized Actuator](./docs/implement-a-customized-actuator-en.md) · [中文](./docs/implement-a-customized-actuator-zh.md) + - [Implement a Customized Actuator](./docs/implement-a-customized-actuator-en.md) · [中文版](./docs/implement-a-customized-actuator-zh.md) - **Protocol** - [TRON Protobuf Protocol Document](./docs/protobuf-protocol-document.md) — the maintained, authoritative Protobuf protocol reference - **Observability** From 8334a03b917d68e37eef8c05def644ff6865a690 Mon Sep 17 00:00:00 2001 From: GrapeS Date: Tue, 14 Jul 2026 13:57:52 +0800 Subject: [PATCH 09/32] docs: drop stale Sonar references and fix metrics changelog link --- CONTRIBUTING.md | 3 +-- README.md | 2 +- docs/{metrics_changelog.md => metrics-changelog.md} | 2 +- framework/build.gradle | 1 - plugins/build.gradle | 4 ---- 5 files changed, 3 insertions(+), 9 deletions(-) rename docs/{metrics_changelog.md => metrics-changelog.md} (98%) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ef67a81e3ee..0f1844df026 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -147,7 +147,7 @@ We would like all developers to follow a standard development flow and coding st 2. Review the code before submission. 3. Run standardized tests. -`Sonar`-scanner and CI checks (GitHub Actions) will be automatically triggered when a pull request has been submitted. When a PR passes all the checks, the **java-tron** maintainers will then review the PR and offer feedback and modifications when necessary. Once adopted, the PR will be closed and merged into the `develop` branch. +CI checks (GitHub Actions) will be automatically triggered when a pull request has been submitted. When a PR passes all the checks, the **java-tron** maintainers will then review the PR and offer feedback and modifications when necessary. Once adopted, the PR will be closed and merged into the `develop` branch. We are glad to receive your pull requests and will try our best to review them as soon as we can. Any pull request is welcome, even if it is for a typo. @@ -158,7 +158,6 @@ Please do not be discouraged if your pull request is not accepted, as it may be Please make sure your submission meets the following code style: - The code must conform to [Google Code Style](https://google.github.io/styleguide/javaguide.html). -- The code must have passed the Sonar scanner test. - The code has to be pulled from the `develop` branch. - The commit message should start with a verb, whose initial should not be capitalized. - The commit message title should be between 10 and 72 characters in length. diff --git a/README.md b/README.md index 7e2b27378ad..a9d740bf4fd 100644 --- a/README.md +++ b/README.md @@ -211,7 +211,7 @@ More detailed guides live in the [`docs/`](./docs) directory: - **Protocol** - [TRON Protobuf Protocol Document](./docs/protobuf-protocol-document.md) — the maintained, authoritative Protobuf protocol reference - **Observability** - - [Metrics Changelog](./docs/metrics_changelog.md) — Prometheus metric additions, changes, and removals across java-tron releases + - [Metrics Changelog](./docs/metrics-changelog.md) — Prometheus metric additions, changes, and removals across java-tron releases # Community diff --git a/docs/metrics_changelog.md b/docs/metrics-changelog.md similarity index 98% rename from docs/metrics_changelog.md rename to docs/metrics-changelog.md index 3c599796d7a..e28cc7393fc 100644 --- a/docs/metrics_changelog.md +++ b/docs/metrics-changelog.md @@ -19,7 +19,7 @@ This file tracks Prometheus metric additions, changes, and removals in java-tron **Pre-4.8.2 Baseline** -Snapshot of metrics emitted prior to this changelog. Per-version provenance is not tracked here; consult `git log` on [`common/src/main/java/org/tron/common/prometheus/`](common/src/main/java/org/tron/common/prometheus/) for exact origin of each metric. +Snapshot of metrics emitted prior to this changelog. Per-version provenance is not tracked here; consult `git log` on [`common/src/main/java/org/tron/common/prometheus/`](../common/src/main/java/org/tron/common/prometheus/) for exact origin of each metric. ### Existing Metrics diff --git a/framework/build.gradle b/framework/build.gradle index 8255fc30d18..888be2e316b 100644 --- a/framework/build.gradle +++ b/framework/build.gradle @@ -1,6 +1,5 @@ plugins { id "org.gradle.test-retry" version "1.5.9" - id "org.sonarqube" version "2.6" id "com.gorylenko.gradle-git-properties" version "2.4.1" } diff --git a/plugins/build.gradle b/plugins/build.gradle index 09a13a19b1b..87249cd6f25 100644 --- a/plugins/build.gradle +++ b/plugins/build.gradle @@ -1,7 +1,3 @@ -plugins { - id "org.sonarqube" version "2.6" -} - apply plugin: 'application' apply plugin: 'checkstyle' From 0369ec4430048f884dab5be797f97e5ff9f84085 Mon Sep 17 00:00:00 2001 From: GrapeS Date: Tue, 14 Jul 2026 16:22:26 +0800 Subject: [PATCH 10/32] chore: remove unused Sonar entries from verification-metadata --- gradle/verification-metadata.xml | 31 ------------------------------- 1 file changed, 31 deletions(-) diff --git a/gradle/verification-metadata.xml b/gradle/verification-metadata.xml index 6a3e641d5d6..6b919cf11be 100644 --- a/gradle/verification-metadata.xml +++ b/gradle/verification-metadata.xml @@ -2659,37 +2659,6 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - From c7011ba5db1dee5f38af39851274fdf0203bef6c Mon Sep 17 00:00:00 2001 From: GrapeS Date: Fri, 3 Jul 2026 16:26:15 +0800 Subject: [PATCH 11/32] docs: add AGENTS.md for AI assistants and contributors --- AGENTS.md | 99 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 99 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000000..ce632d4d4be --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,99 @@ +# AGENTS.md + +Guidance for AI coding assistants and new contributors working on java-tron: how to build, test, and navigate the codebase, plus the high-frequency constraints to respect. For running a node, see the [README](./README.md) and [`docs/`](./docs). + +## Working principles + +- Keep changes minimal and focused: only touch code related to the task. Do not refactor unrelated code, rename for style, or bundle unrelated fixes into one commit/PR. +- Do not add, remove, or upgrade dependencies unless the task requires it — dependency changes in a consensus node are high-risk and need separate review. + +## Build & Test + +Supported platforms: **Linux** and **macOS** only. JDK requirement: **JDK 8** on x86_64, **JDK 17** on ARM64/aarch64 (e.g. Apple Silicon Macs, or Linux aarch64 servers such as AWS Graviton). + +```bash +./gradlew clean build -x test # build without tests +./gradlew build # build with tests +./gradlew test # run all tests +./gradlew :framework:test # test one module +./gradlew test --tests "org.tron.core.db.TronDatabaseTest" # one class +./gradlew test --tests "org.tron.core.db.TronDatabaseTest.testX" # one method +./gradlew :framework:testWithRocksDb # RocksDB tests (x86 only) +./gradlew lint # Checkstyle (main) +./gradlew checkstyleMain checkstyleTest # Checkstyle main + test (as CI runs) +./gradlew jacocoTestReport # coverage report +``` + +- Main entry point: `org.tron.program.FullNode`. +- Tests run in parallel locally, serially in CI (detected via the `CI` env var); the test-retry plugin retries up to 5 times. +- On ARM64/aarch64, only the RocksDB storage engine is supported; the build forces RocksDB and skips the LevelDB tests. +- Protobuf / gRPC Java stubs are generated at build time from `protocol/src/main/protos/*.proto` (via the `com.google.protobuf` Gradle plugin) and are git-ignored — rebuild after changing a `.proto`; never hand-edit or commit generated sources. + +**Before pushing:** +- `./gradlew checkstyleMain checkstyleTest` and `./gradlew test` must pass. +- Do not commit build artifacts or byproducts — `*.jar`, `build/`, logs, or database files. + +## Module Layout + +| Module | Responsibility | +|--------|----------------| +| `framework` | Main entry (`org.tron.program.FullNode`); wires all modules; largest test suite | +| `protocol` | Protobuf / gRPC definitions | +| `chainbase` | Blockchain storage abstraction (LevelDB / RocksDB); snapshot & rollback | +| `consensus` | Pluggable DPoS consensus engine | +| `actuator` | Transaction execution; one Actuator class per transaction type | +| `crypto` | Cryptographic primitives (depends only on `common`) | +| `common` | Shared utilities | +| `plugins` | Standalone tools (e.g. `Toolkit.jar`) | + +**Module dependency direction is one-way — do not introduce reverse dependencies:** + +```text +framework → chainbase → common → protocol +actuator → chainbase +consensus → chainbase / common (only via ConsensusDelegate; never call Manager directly) +crypto → common +``` + +## Hard Constraints + +**Cross-JVM determinism** (consensus, state transition, block ordering): +- Never use `float` / `double`. +- Never depend on `HashMap` iteration order for a business decision. +- Use the DPoS slot time for produced-block timestamps, not `System.currentTimeMillis()`. + +**DB / Store:** +- All writes must happen inside a `Session` / `Dialog` — no bare `put()`. +- A new store must extend `TronStoreWithRevoking` and register with the `RevokingDatabase`. +- Multi-store updates must roll back fully on exception. + +**Actuator:** +- Register new actuators in `ActuatorFactory`. +- Charge fees before `execute()`. +- `validate()` must not mutate state. + +**Protobuf:** +- Fields may only be added — never removed or renumbered. +- Message field numbers start at `1`; the first enum value must be `0`. + +**API / Threads:** +- New HTTP servlets must go through `HttpApiAccessFilter` and use `Wallet` (never inject `Manager` directly). +- New gRPC methods must join the `LiteFnQueryGrpcInterceptor` chain. +- No bare `new Thread()` — use a named Executor, shut down via `shutdown()` → `awaitTermination()` → `shutdownNow()`. + +## Authoritative Documentation + +- **Build / run / node operation:** [README](./README.md) +- **Configuration:** [`docs/configuration.md`](./docs/configuration.md), [`docs/configuration-conventions.md`](./docs/configuration-conventions.md) +- **Protobuf protocol:** [`docs/protobuf-protocol-document.md`](./docs/protobuf-protocol-document.md) is the maintained reference (the copies under `protocol/src/main/protos/` are outdated). +- **Extending / deployment:** the [`docs/`](./docs) directory (customized actuator, modular deployment). +- **Contributing:** [CONTRIBUTING.md](./CONTRIBUTING.md) (workflow, coding style, commit/PR conventions). +- **Security policy:** [SECURITY.md](./SECURITY.md) (supported versions, vulnerability disclosure). + +## Commit Convention + +`type(scope): description` (Conventional Commits), 10–72 chars, no trailing period. + +- **type:** `feat` `fix` `refactor` `docs` `style` `test` `chore` `ci` `perf` `build` `revert` +- **scope:** `framework` `chainbase` `actuator` `consensus` `common` `crypto` `plugins` `protocol` `net` `db` `vm` `tvm` `api` `jsonrpc` `rpc` `http` `event` `config` `block` `proposal` `trie` `log` `metrics` `test` `docker` `version` +- **PR title:** same `type(scope): description` convention; fill in `.github/PULL_REQUEST_TEMPLATE.md`. From 741c49f9a9b1c2c3aca29db958ddec74779a5677 Mon Sep 17 00:00:00 2001 From: GrapeS Date: Mon, 20 Jul 2026 11:09:23 +0800 Subject: [PATCH 12/32] docs: correct AGENTS.md platform and build details - Note the build fails fast on a JDK/arch mismatch - Scope the lint helper comment to framework main - Fix the generated-protobuf source path (core/, api/ subdirs) - Add the platform module (arch-specific source sets) to the layout - List both plugins jars (Toolkit, ArchiveManifest) --- AGENTS.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index ce632d4d4be..9f0e06af76b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -9,7 +9,7 @@ Guidance for AI coding assistants and new contributors working on java-tron: how ## Build & Test -Supported platforms: **Linux** and **macOS** only. JDK requirement: **JDK 8** on x86_64, **JDK 17** on ARM64/aarch64 (e.g. Apple Silicon Macs, or Linux aarch64 servers such as AWS Graviton). +Supported platforms: **Linux** and **macOS** only. JDK requirement is by CPU architecture: **JDK 8** on x86_64, **JDK 17** on ARM64/aarch64 (e.g. Apple Silicon Macs, or Linux aarch64 servers such as AWS Graviton). The build fails fast if the JDK major version does not match the architecture. ```bash ./gradlew clean build -x test # build without tests @@ -19,7 +19,7 @@ Supported platforms: **Linux** and **macOS** only. JDK requirement: **JDK 8** on ./gradlew test --tests "org.tron.core.db.TronDatabaseTest" # one class ./gradlew test --tests "org.tron.core.db.TronDatabaseTest.testX" # one method ./gradlew :framework:testWithRocksDb # RocksDB tests (x86 only) -./gradlew lint # Checkstyle (main) +./gradlew lint # Checkstyle (framework main only) ./gradlew checkstyleMain checkstyleTest # Checkstyle main + test (as CI runs) ./gradlew jacocoTestReport # coverage report ``` @@ -27,7 +27,7 @@ Supported platforms: **Linux** and **macOS** only. JDK requirement: **JDK 8** on - Main entry point: `org.tron.program.FullNode`. - Tests run in parallel locally, serially in CI (detected via the `CI` env var); the test-retry plugin retries up to 5 times. - On ARM64/aarch64, only the RocksDB storage engine is supported; the build forces RocksDB and skips the LevelDB tests. -- Protobuf / gRPC Java stubs are generated at build time from `protocol/src/main/protos/*.proto` (via the `com.google.protobuf` Gradle plugin) and are git-ignored — rebuild after changing a `.proto`; never hand-edit or commit generated sources. +- Protobuf / gRPC Java stubs are generated at build time from the `.proto` files under `protocol/src/main/protos/` (subdirectories `core/`, `api/`; via the `com.google.protobuf` Gradle plugin) and are git-ignored — rebuild after changing a `.proto`; never hand-edit or commit generated sources. **Before pushing:** - `./gradlew checkstyleMain checkstyleTest` and `./gradlew test` must pass. @@ -44,7 +44,8 @@ Supported platforms: **Linux** and **macOS** only. JDK requirement: **JDK 8** on | `actuator` | Transaction execution; one Actuator class per transaction type | | `crypto` | Cryptographic primitives (depends only on `common`) | | `common` | Shared utilities | -| `plugins` | Standalone tools (e.g. `Toolkit.jar`) | +| `platform` | Architecture-specific implementations selected at build time (separate `x86` / `arm` / `common` source sets): math wrappers, LevelDB/RocksDB order-price comparators — relevant to cross-JVM determinism | +| `plugins` | Standalone tools (`Toolkit.jar`, `ArchiveManifest.jar`) | **Module dependency direction is one-way — do not introduce reverse dependencies:** @@ -55,6 +56,8 @@ consensus → chainbase / common (only via ConsensusDelegate; never call Manag crypto → common ``` +`platform` is a leaf module (no project dependencies of its own) that `common`, `framework`, and `plugins` depend on for architecture-specific code. + ## Hard Constraints **Cross-JVM determinism** (consensus, state transition, block ordering): From 3e90afb44e3d8b4c1472c51c54de70d04b42fc9e Mon Sep 17 00:00:00 2001 From: GrapeS Date: Mon, 14 Sep 2026 15:26:20 +0800 Subject: [PATCH 13/32] merge --- README.md | 4 +- shell.md | 236 ------------------------------------------------------ 2 files changed, 1 insertion(+), 239 deletions(-) delete mode 100644 shell.md diff --git a/README.md b/README.md index a9d740bf4fd..9c32f7bbf6d 100644 --- a/README.md +++ b/README.md @@ -75,14 +75,12 @@ git checkout -t origin/master # Executables -The java-tron project comes with several runnable artifacts and helper scripts found in the project root and build directories. +The java-tron project comes with several runnable artifacts found in the build directories. | Artifact/Script | Description | | :---------------------- | :---------- | | **`FullNode.jar`** | Main TRON node executable (generated in `build/libs/` after a successful build following the above guidance). Runs as a full node by default. `java -jar FullNode.jar --help` for command line options| | **`Toolkit.jar`** | Node management utility (generated in `build/libs/`): partition, prune, copy, convert DBs; shadow-fork tool. [Usage](https://tronprotocol.github.io/documentation-en/using_javatron/toolkit/#toolkit-a-java-tron-node-maintenance-suite) | -| **`start.sh`** | Quick start script (x86_64, JDK 8) to download/build/run `FullNode.jar`. See the tool [guide](./shell.md). | -| **`start.sh.simple`** | Quick start script template (ARM64, JDK 17). See usage notes inside the script. | # Running java-tron diff --git a/shell.md b/shell.md deleted file mode 100644 index 700067a9aa3..00000000000 --- a/shell.md +++ /dev/null @@ -1,236 +0,0 @@ -# Quick Start Scripting Tool - -# Introduction - -Using the `start.sh` script, you can quickly and easily run and build java-tron. - -If you already downloaded the `FullNode.jar`, you can use `start.sh` to run it, or if you have not downloaded java-tron source code or jar packages, you can use `start.sh` to download the source code, compile, run or get the latest release version in the form of a `jar package ` and run. - -The script is available in the java-tron project at [github](https://github.com/tronprotocol/java-tron), or if you need a separate script: [start.sh](https://github.com/tronprotocol/java-tron/blob/develop/start.sh) - -*** - -# Usage - -## Examples - -* Start the `FullNode.jar` (`start.sh`, `config.conf` and `FullNode.jar` in the same directory.) - - ``` - sh start.sh --run - ``` - - Start the service with options. - - ``` - sh start.sh --run -j /data/FullNode.jar -c /data/config.conf -d /data/output-directory - ``` - -* Stop the `FullNode.jar` - - ``` - sh start.sh --stop - ``` - -* Get the latest version of `FullNode.jar` and start it - - ``` - sh start.sh --release --run - ``` - -* Clone the source code, compile `java-tron`, and generate `FullNode.jar` and start it - - ``` - sh start.sh -cb --run - ``` - -* Select a supported network,default network `main`, optional network `test`,`private` - ``` - sh start.sh --net test - ``` - - -## Options - -### Service operation - -* `--run` - - start the service - -* `--stop` - - stop the service - -* `-c` - - Specify the configuration file, by default it will load the `config.conf` in the same directory as `FullNode.jar` - -* `-d` - - Specify the database storage path, The default path is the same directory where `FullNode.jar` is located. - -* `-j` - - Specify the jar package, default value is the `FullNode.jar` in the current path. - -* `-mem` - - Specify the maximum memory of the `FullNode.jar` service in`MB`, jvm's startup maximum memory will be adjusted according to this parameter. - -* `--net` - Select test and private networks. - -### build project - -* `-cb` - - Clone the latest source code and compile. - -* `--release` - - Get the latest released version of the `jar` package from github. - - -### rebuild the manifest - -* `-d` - - specify the `output-directory` db directory - -* `-m` - - specify the minimum required manifest file size ，unit:M，default：0 - -* `-b` - - specify the batch manifest size,default：80000 - -* `-dr` or `--disable-rewrite-manifest` - disable rewrite manifest - -*** - -## How to use - -* Local mode - - Start the service using the local Jar package - -* Online mode - - Get the latest code or latest release from github and start the service - -### 1.local mode - -Format: - -``` -sh start.sh [-j ] [-d ] [-c ] [[--run] | [--stop]] -``` - -**start service** - -``` -sh start.sh --run -``` - -**stop service** - -``` -sh start.sh --stop -``` - -### 2.online mode - -* Get the latest release - -* Clone the source code and build - -**Get the latest release** - -Format: - -``` -sh start.sh <[--release | -cb]> <--run> [-m ] | [-b ] | [-d | [-dr | --disable-rewrite-manifes]] -``` - -Get the latest released version. - - -``` -sh start.sh --release --run -``` - -Following file structure will be generated after executing the above command and the `FullNode.jar` will be started. - -``` -├── ... -├── FullNode/ - ├── config.conf - ├── FullNode.jar - ├── start.sh -``` - -**Clone the source code and build** - -Get the latest code from master branch of https://github.com/tronprotocol/java-tron and compile. - -After using this command, the "FullNode" directory will be created, the compiled file `FullNode.jar` and the configuration file will be copied to this directory - -demo: - -``` -sh start.sh -cb --run -``` - -Following file structure will be created： - -``` -├── ... -├── java-tron - ├── actuator/ - ├── chainbase/ - ├── common/ - ├── config/ - ├── consensus/ - ├── crypto/ - ├── docker/ - ├── docs/ - ├── example/ - ├── framework/ - ├── gradle/ - ├── plugins/ - ├── protocol/ - ├── config.conf - ├── FullNode.jar - ├── start.sh - ├── README.md - ├── ... -``` - -``` -├── java-tron/ -├── FullNode/ - |── config.conf - ├── FullNode.jar - ├── start.sh -``` - -### 3. rebuild manifest tool - -This tool provides the ability to reformat the manifest based on current database, Enabled by default. - -1.Local mode: - -``` -sh start.sh --run -d /tmp/db/database -m 128 -b 64000 -``` - -2.Online mode - -``` -sh start.sh --release --run -d /tmp/db/database -m 128 -b 64000 -``` - -For more design details, please refer to: [TIP298](https://github.com/tronprotocol/tips/issues/298) | [Leveldb Startup Optimization Plugins](https://github.com/tronprotocol/documentation-en/blob/master/docs/developers/archive-manifest.md) From 626611743c521362dc79694129d1d8c95d899458 Mon Sep 17 00:00:00 2001 From: GrapeS Date: Mon, 14 Sep 2026 15:27:41 +0800 Subject: [PATCH 14/32] chore: remove obsolete start scripts # Conflicts: # start.sh # start.sh.simple --- start.sh | 623 ------------------------------------------------ start.sh.simple | 193 --------------- 2 files changed, 816 deletions(-) delete mode 100644 start.sh delete mode 100644 start.sh.simple diff --git a/start.sh b/start.sh deleted file mode 100644 index 1472a94dc62..00000000000 --- a/start.sh +++ /dev/null @@ -1,623 +0,0 @@ -#!/bin/bash -############################################################################# -# -# GNU LESSER GENERAL PUBLIC LICENSE -# Version 3, 29 June 2007 -# -# Copyright (C) [2007] [TRON Foundation], Inc. -# Everyone is permitted to copy and distribute verbatim copies -# of this license document, but changing it is not allowed. -# -# -# This version of the GNU Lesser General Public License incorporates -# the terms and conditions of version 3 of the GNU General Public -# License, supplemented by the additional permissions listed below. -# -# You can find java-tron at https://github.com/tronprotocol/java-tron/ -# -############################################################################## - -# Build FullNode config -FULL_NODE_DIR="FullNode" -FULL_NODE_CONFIG_DIR="config" -# config file -FULL_NODE_CONFIG_MAIN_NET="main_net_config.conf" -FULL_NODE_CONFIG_TEST_NET="test_net_config.conf" -FULL_NODE_CONFIG_PRIVATE_NET="private_net_config.conf" -DEFAULT_FULL_NODE_CONFIG='config.conf' -JAR_NAME="FullNode.jar" -FULL_START_OPT='' - -# Github -GITHUB_BRANCH='master' -GITHUB_CLONE_TYPE='HTTPS' -GITHUB_REPOSITORY='' -GITHUB_REPOSITORY_HTTPS_URL='https://github.com/tronprotocol/java-tron.git' -GITHUB_REPOSITORY_SSH_URL='git@github.com:tronprotocol/java-tron.git' - -# Shell option -ALL_OPT_LENGTH=$# -# Start service option -MAX_STOP_TIME=60 -# Modify this option to allow the minimum memory to be started, unit MB -ALLOW_MIN_MEMORY=8192 - -# JVM option -MAX_DIRECT_MEMORY=1g -JVM_MS=4g -JVM_MX=4g -IS_BACKUP_GC_LOG=true - -SPECIFY_MEMORY=0 -RUN=false -UPGRADE=false - -# Rebuild manifest -REBUILD_MANIFEST=true -REBUILD_DIR="$PWD/output-directory/database" -REBUILD_MANIFEST_SIZE=0 -REBUILD_BATCH_SIZE=80000 - -# Download and upgrade -DOWNLOAD=false -RELEASE_URL='https://github.com/tronprotocol/java-tron/releases' -QUICK_START=false -CLONE_BUILD=false - -if [[ $GITHUB_CLONE_TYPE == 'HTTPS' ]]; then - GITHUB_REPOSITORY=$GITHUB_REPOSITORY_HTTPS_URL -else - GITHUB_REPOSITORY=$GITHUB_REPOSITORY_SSH_URL -fi - -# Determine the Java command to use to start the JVM. -if [ -z "$JAVA_HOME" ]; then - javaExecutable="`which javac`" - if [ -n "$javaExecutable" ] && ! [ "`expr \"$javaExecutable\" : '\([^ ]*\)'`" = "no" ]; then - # readlink(1) is not available as standard on Solaris 10. - readLink=`which readlink` - if [ ! `expr "$readLink" : '\([^ ]*\)'` = "no" ]; then - if $darwin ; then - javaHome="`dirname \"$javaExecutable\"`" - javaExecutable="`cd \"$javaHome\" && pwd -P`/javac" - else - javaExecutable="`readlink -f \"$javaExecutable\"`" - fi - javaHome="`dirname \"$javaExecutable\"`" - javaHome=`expr "$javaHome" : '\(.*\)/bin'` - JAVA_HOME="$javaHome" - export JAVA_HOME - fi - fi -fi - -if [ -z "$JAVACMD" ] ; then - if [ -n "$JAVA_HOME" ] ; then - if [ -x "$JAVA_HOME/jre/sh/java" ] ; then - # IBM's JDK on AIX uses strange locations for the executables - JAVACMD="$JAVA_HOME/jre/sh/java" - else - JAVACMD="$JAVA_HOME/bin/java" - fi - else - JAVACMD="`which java`" - fi -fi - -if [ ! -x "$JAVACMD" ] ; then - echo "Error: JAVA_HOME is not defined correctly." >&2 - echo " We cannot execute $JAVACMD" >&2 - exit 1 -fi - -if [ -z "$JAVA_HOME" ] ; then - echo "Warning: JAVA_HOME environment variable is not set." -fi - -backupGCLog() { - local maxFile=5 - local gcLogDir=logs/gc_logs/ - if [ ! -d "$gcLogDir" ];then - mkdir -p 'logs/gc_logs' - fi - - if [ -f 'gc.log' ]; then - echo '[info] backup gc.log' - local dateformat=`date "+%Y-%m-%d_%H-%M-%S"` - tar -czvf gc.log_$dateformat'.tar.gz' gc.log - mv gc.log_$dateformat'.tar.gz' $gcLogDir - rm -rf gc.log - - # checking the number of backups - local currentDirCount=`ls -l $gcLogDir | grep "gc.log*" | wc -l` - if [ $currentDirCount -gt $maxFile ]; then - local oldFileSize=`expr $currentDirCount - $maxFile` - local oldGcLogFiles=(`ls -1 $gcLogDir |head -n $oldFileSize`) - fi - - for fileName in ${oldGcLogFiles[@]}; do - rm -rf $gcLogDir$fileName - done - fi -} - -getLatestReleaseVersion() { - full_node_version=`git ls-remote --tags $GITHUB_REPOSITORY |grep GreatVoyage- | awk -F '/' 'END{print $3}'` - if [[ -n $full_node_version ]]; then - echo $full_node_version - else - echo '' - fi -} - -checkVersion() { - github_release_version=$(`echo getLatestReleaseVersion`) - if [[ -n $github_release_version ]]; then - echo "info: github latest version: $github_release_version" - echo $github_release_version - else - echo 'info: not getting the latest version' - exit - fi -} - -upgrade() { - latest_version=$(`echo getLatestReleaseVersion`) - echo "info: latest version: $latest_version" - if [[ -n $latest_version ]]; then - old_jar="$PWD/$JAR_NAME" - if [[ -f $old_jar ]]; then - echo "info: backup $old_jar" - mv $PWD/$JAR_NAME $PWD/$JAR_NAME'_bak' - fi - download $RELEASE_URL/download/$latest_version/$JAR_NAME $JAR_NAME - if [[ $? == 0 ]]; then - echo "info: download version $latest_version success" - fi - else - echo 'info: nothing to upgrade' - fi -} - -download() { - local url=$1 - local file_name=$2 - if type wget >/dev/null 2>&1; then - wget --no-check-certificate -q $url - elif type curl >/dev/null 2>&1; then - echo "curl -OLJ $url" - curl -OLJ $url - else - echo 'info: no exists wget or curl, make sure the system can use the "wget" or "curl" command' - fi -} - -mkdirFullNode() { - if [ ! -d $FULL_NODE_DIR ]; then - echo "info: create $FULL_NODE_DIR" - mkdir $FULL_NODE_DIR - $(cp $0 $FULL_NODE_DIR) - cd $FULL_NODE_DIR - elif [ -d $FULL_NODE_DIR ]; then - cd $FULL_NODE_DIR - fi -} - -quickStart() { - full_node_version=$(`echo getLatestReleaseVersion`) - if [[ -n $full_node_version ]]; then - mkdirFullNode - echo "info: check latest version: $full_node_version" - echo 'info: download config' - download https://raw.githubusercontent.com/tronprotocol/tron-deployment/$GITHUB_BRANCH/$FULL_NODE_CONFIG_MAIN_NET $FULL_NODE_CONFIG_MAIN_NET - mv $FULL_NODE_CONFIG_MAIN_NET 'config.conf' - - echo "info: download $full_node_version" - download $RELEASE_URL/download/$full_node_version/$JAR_NAME $JAR_NAME - checkSign - else - echo 'info: not getting the latest version' - exit - fi -} - -cloneCode() { - if type git >/dev/null 2>&1; then - git_clone=$(git clone -b $GITHUB_BRANCH $GITHUB_REPOSITORY) - if [[ git_clone == 0 ]]; then - echo 'info: git clone java-tron success' - fi - else - echo 'info: no exists git, make sure the system can use the "git" command' - fi -} - -cloneBuild() { - local currentPwd=$PWD - echo 'info: clone java-tron' - cloneCode - - echo 'info: build java-tron' - cd java-tron - sh gradlew clean build -x test - if [[ $? == 0 ]];then - cd $currentPwd - mkdirFullNode - cp '../java-tron/build/libs/FullNode.jar' $PWD - cp '../java-tron/framework/src/main/resources/config.conf' $PWD - else - exit - fi -} - -checkPid() { - if [[ $JAR_NAME =~ '/' ]]; then - JAR_NAME=$(echo $JAR_NAME |awk -F '/' '{print $NF}') - fi - pid=$(ps -ef | grep -v start | grep $JAR_NAME | grep -v grep | awk '{print $2}') - return $pid -} - -stopService() { - count=1 - while [ $count -le $MAX_STOP_TIME ]; do - checkPid - if [ $pid ]; then - kill -15 $pid - sleep 1 - else - echo "info: java-tron stop" - return - fi - count=$(($count + 1)) - if [ $count -eq $MAX_STOP_TIME ]; then - kill -9 $pid - sleep 1 - fi - done - sleep 5 -} - -checkAllowMemory() { - os=`uname` - totalMemory=$(`echo getTotalMemory`) - total=`expr $totalMemory / 1024` - if [[ $os == 'Darwin' ]]; then - return - fi - - if [[ $total -lt $ALLOW_MIN_MEMORY ]]; then - echo "warn: the memory $total MB cannot be smaller than the minimum memory $ALLOW_MIN_MEMORY MB" - exit - elif [[ $SPECIFY_MEMORY -gt 0 ]] && - [[ $SPECIFY_MEMORY -lt $ALLOW_MIN_MEMORY ]]; then - echo "warn: the specified memory $SPECIFY_MEMORY MB cannot be smaller than the minimum memory $ALLOW_MIN_MEMORY MB" - echo 'warn: start abort' - exit - fi -} - -setTCMalloc() { - os=`uname` - if [[ $os == 'Linux' ]] || [[ $os == 'linux' ]] ; then - lib_tc_malloc="/usr/lib64/libtcmalloc.so" - if [[ -f $lib_tc_malloc ]]; then - export LD_PRELOAD="$lib_tc_malloc" - export TCMALLOC_RELEASE_RATE=10 - else - echo 'info: recommended for linux systems using tcmalloc as the default memory management tool' - fi - fi -} - -getTotalMemory() { - os=`uname` - if [[ $os == 'Linux' ]] || [[ $os == 'linux' ]] ; then - total=$(cat /proc/meminfo | grep MemTotal | awk -F ' ' '{print $2}') - echo $total - return - elif [[ $os == 'Darwin' ]]; then - total=$(sysctl -a | grep mem |grep hw.memsize |awk -F ' ' '{print $2}') - echo `expr $total / 1024` - fi -} - -setJVMMemory() { - os=`uname` - if [[ $os == 'Linux' ]] || [[ $os == 'linux' ]] ; then - if [[ $SPECIFY_MEMORY >0 ]]; then - max_direct=$(echo "$SPECIFY_MEMORY/1024*0.1" | bc | awk -F. '{print $1"g"}') - if [[ "$max_direct" != "g" ]]; then - MAX_DIRECT_MEMORY=$max_direct - fi - JVM_MX=$(echo "$SPECIFY_MEMORY/1024*0.6" | bc | awk -F. '{print $1"g"}') - JVM_MS=$JVM_MX - else - total=$(`echo getTotalMemory`) - MAX_DIRECT_MEMORY=$(echo "$total/1024/1024*0.1" | bc | awk -F. '{print $1"g"}') - JVM_MX=$(echo "$total/1024/1024*0.6" | bc | awk -F. '{print $1"g"}') - JVM_MS=$JVM_MX - fi - - elif [[ $os == 'Darwin' ]]; then - MAX_DIRECT_MEMORY='1g' - fi -} - -startService() { - echo $(date) >>start.log - if [[ ! $JAR_NAME =~ '-c' ]]; then - FULL_START_OPT="$FULL_START_OPT -c $DEFAULT_FULL_NODE_CONFIG" - fi - - if [[ ! -f $JAR_NAME ]]; then - echo "warn: jar file $JAR_NAME not exist" - exit - fi - - nohup $JAVACMD -Xms$JVM_MS -Xmx$JVM_MX -XX:+UseConcMarkSweepGC -XX:+PrintGCDetails -Xloggc:./gc.log \ - -XX:+PrintGCDateStamps -XX:+CMSParallelRemarkEnabled -XX:ReservedCodeCacheSize=256m -XX:+UseCodeCacheFlushing \ - -XX:MetaspaceSize=256m -XX:MaxMetaspaceSize=512m \ - -XX:MaxDirectMemorySize=$MAX_DIRECT_MEMORY -Dio.netty.allocator.type=pooled \ - -XX:+HeapDumpOnOutOfMemoryError \ - -XX:NewRatio=2 -jar \ - $JAR_NAME $FULL_START_OPT >>start.log 2>&1 & - checkPid - echo "info: start java-tron with pid $pid on $HOSTNAME" - echo "info: if you need to stop the service, execute: sh start.sh --stop" -} - -rebuildManifest() { - if [[ $REBUILD_MANIFEST = false ]]; then - echo 'info: disable rebuild manifest!' - return - fi - - if [[ ! -d $REBUILD_DIR ]]; then - echo "info: database not exists, skip rebuild manifest" - return - fi - - ARCHIVE_JAR='ArchiveManifest.jar' - if [[ -f $ARCHIVE_JAR ]]; then - echo 'info: execute rebuild manifest.' - $JAVACMD -jar $ARCHIVE_JAR -d $REBUILD_DIR -m $REBUILD_MANIFEST_SIZE -b $REBUILD_BATCH_SIZE - else - echo 'info: download the rebuild manifest plugin from the github' - local latest=$(`echo getLatestReleaseVersion`) - download $RELEASE_URL/download/GreatVoyage-v"$latest"/$ARCHIVE_JAR $ARCHIVE_JAR - if [[ $download == 0 ]]; then - echo 'info: download success, rebuild manifest' - $JAVACMD -jar $ARCHIVE_JAR $REBUILD_DIR -m $REBUILD_MANIFEST_SIZE -b $REBUILD_BATCH_SIZE - fi - fi - if [[ $? == 0 ]]; then - echo 'info: rebuild manifest success' - else - echo 'info: rebuild manifest fail, log in logs/archive.log' - fi -} - -specifyConfig(){ - echo "info: specify the net: $1" - local netType=$1 - local configName; - if [[ "$netType" = 'test' ]]; then - configName=$FULL_NODE_CONFIG_TEST_NET - elif [[ "$netType" = 'private' ]]; then - configName=$FULL_NODE_CONFIG_PRIVATE_NET - else - echo "warn: no support config $nodeType" - exit - fi - - if [[ ! -d $FULL_NODE_CONFIG_DIR ]]; then - mkdir -p $FULL_NODE_CONFIG_DIR - fi - - if [[ -d $FULL_NODE_CONFIG_DIR/$configName ]]; then - DEFAULT_FULL_NODE_CONFIG=$FULL_NODE_CONFIG_DIR/$configName - break - fi - - if [[ ! -f $FULL_NODE_CONFIG_DIR/$configName ]]; then - download https://raw.githubusercontent.com/tronprotocol/tron-deployment/$GITHUB_BRANCH/$configName $configName - mv $configName $FULL_NODE_CONFIG_DIR/$configName - DEFAULT_FULL_NODE_CONFIG=$FULL_NODE_CONFIG_DIR/$configName - fi -} - -checkSign() { - echo 'info: verify signature' - local latest_version=$(`echo getLatestReleaseVersion`) - download $RELEASE_URL/download/$latest_version/sha256sum.txt sha256sum.txt - fullNodeSha256=$(cat sha256sum.txt|grep 'FullNode'| awk -F ' ' '{print $1}') - - os=`uname` - if [[ $os == 'Linux' ]] || [[ $os == 'linux' ]] ; then - releaseFullNodeSha256=$(sha256sum FullNode.jar| grep FullNode | awk -F ' ' '{print $1}') - elif [[ $os == 'Darwin' ]]; then - releaseFullNodeSha256=$(shasum -a 256 FullNode.jar| grep FullNode | awk -F ' ' '{print $1}') - cat $releaseFullNodeSha256 | awk -F ' ' '{print $0}' - fi - - echo "info: release sha256sum sign: $releaseFullNodeSha256" - echo "info: FullNode.jar sha256sum sign: $fullNodeSha256" - - if [[ "$fullNodeSha256" == "$releaseFullNodeSha256" ]]; then - echo 'info: sha256 signatures pass' - else - echo 'info: sha256 signature exception!!!' - echo 'info: please compile from the code or download the latest version from https://github.com/tronprotocol/java-tron' - fi -} - -restart() { - stopService - checkAllowMemory - rebuildManifest - setTCMalloc - setJVMMemory - startService -} - -while [ -n "$1" ]; do - case "$1" in - -c) - DEFAULT_FULL_NODE_CONFIG=$2 - shift 2 - ;; - -d) - REBUILD_DIR=$2/database - FULL_START_OPT="$FULL_START_OPT $1 $2" - shift 2 - ;; - -j) - JAR_NAME=$2 - shift 2 - ;; - -p) - FULL_START_OPT="$FULL_START_OPT $1 $2" - shift 2 - ;; - -w) - FULL_START_OPT="$FULL_START_OPT $1" - shift 1 - ;; - --witness) - FULL_START_OPT="$FULL_START_OPT $1" - shift 1 - ;; - --net) - specifyConfig $2 - shift 2 - ;; - -m) - REBUILD_MANIFEST_SIZE=$2 - shift 2 - ;; - -n) - JAR_NAME=$2 - shift 2 - ;; - -b) - REBUILD_BATCH_SIZE=$2 - shift 2 - ;; - -cb) - CLONE_BUILD=true - shift 1 - ;; - --download) - DOWNLOAD=true - shift 1 - ;; - --deploy) - QUICK_START=true - shift 1 - ;; - --release) - QUICK_START=true - shift 1 - ;; - --clone) - cloneCode - exit - ;; - -mem) - SPECIFY_MEMORY=$2 - shift 2 - ;; - --disable-rewrite-manifes) - REBUILD_MANIFEST=false - shift 1 - ;; - -dr) - REBUILD_MANIFEST=false - shift 1 - ;; - --upgrade) - UPGRADE=true - shift 1 - ;; - --run) - if [[ $ALL_OPT_LENGTH -eq 1 ]]; then - restart - fi - RUN=true - shift 1 - ;; - --stop) - stopService - ;; - FullNode) - RUN=true - shift 1 - ;; - FullNode.jar) - RUN=true - shift 1 - ;; - *.jar) - RUN=true - shift 1 - ;; - *) - if [[ $ALL_OPT_LENGTH -eq 1 ]]; then - if [[ ! "$1" =~ "-" ]] && [[ ! "$1" =~ "--" ]]; then - if [[ $1 =~ '.jar' ]]; then - JAR_NAME=$1 - else - JAR_NAME="$1.jar" - fi - restart - exit - fi - fi - FULL_START_OPT="$FULL_START_OPT $@" - break - ;; - esac -done - -if [[ $IS_BACKUP_GC_LOG = true ]]; then - backupGCLog -fi - -if [[ $CLONE_BUILD == true ]];then - cloneBuild -fi - -if [[ $QUICK_START == true ]]; then - quickStart - if [[ $? == 0 ]] ; then - if [[ $RUN == true ]]; then - cd $FULL_NODE_DIR - FULL_START_OPT='' - restart - fi - fi -fi - -if [[ $UPGRADE == true ]]; then - upgrade -fi - -if [[ $DOWNLOAD == true ]]; then - latest=$(`echo getLatestReleaseVersion`) - if [[ -n $latest ]]; then - download $RELEASE_URL/download/$latest/$JAR_NAME $latest - exit - else - echo 'info: not getting the latest version' - fi -fi - -if [[ $ALL_OPT_LENGTH -eq 0 || $ALL_OPT_LENGTH -gt 0 ]]; then - restart -fi - -if [[ $RUN == true ]]; then - restart -fi - diff --git a/start.sh.simple b/start.sh.simple deleted file mode 100644 index 109f0dc85a3..00000000000 --- a/start.sh.simple +++ /dev/null @@ -1,193 +0,0 @@ -#!/bin/bash -############################################################################# -# -# GNU LESSER GENERAL PUBLIC LICENSE -# Version 3, 29 June 2007 -# -# Copyright (C) [2007] [TRON Foundation], Inc. -# Everyone is permitted to copy and distribute verbatim copies -# of this license document, but changing it is not allowed. -# -# -# This version of the GNU Lesser General Public License incorporates -# the terms and conditions of version 3 of the GNU General Public -# License, supplemented by the additional permissions listed below. -# -# You can find java-tron at https://github.com/tronprotocol/java-tron/ -# -############################################################################## -# TRON Full Node Management Simple Script -# -# NOTE: This is a simple and concise script to start and stop the java-tron full node, -# designed for developers to quickly get started and learn. -# It may not be suitable for production environments. -# -# Usage: -# sh start.sh # Start the java-tron FullNode -# sh start.sh -s # Stop the java-tron FullNode -# sh start.sh [options] # Start with additional java-tron options,such as: -c config.conf -d /path_to_data, etc. -# -############################################################################## - - -# adjust JVM start -# Set the maximum heap size to 9G, adjust as needed -VM_XMX="9G" -# adjust JVM end - -FULL_NODE_JAR="FullNode.jar" -FULL_START_OPT=() -PID="" -MAX_STOP_TIME=60 -JAVACMD="" -SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" - -RED='\033[0;31m' -GREEN='\033[0;32m' -YELLOW='\033[1;33m' -NC='\033[0m' - -log() { - local level="$1"; shift - local timestamp color="" - timestamp=$(date '+%Y-%m-%d %H:%M:%S') - case "$level" in - INFO) color="$GREEN" ;; - WARN) color="$YELLOW" ;; - ERROR) color="$RED" ;; - esac - printf "%b[%s] [%s]:%b %s\n" "$color" "$timestamp" "$level" "$NC" "$*" | tee -a "${SCRIPT_DIR}/start.log" -} - -info() { log INFO "$@"; } -warn() { log WARN "$@"; } -error() { log ERROR "$@"; } -die() { error "$@"; exit 1; } - -ulimit -n 65535 || warn "Failed to set ulimit -n 65535" - -findJava() { - if [ -n "${JAVA_HOME:-}" ]; then - if [ -x "$JAVA_HOME/jre/sh/java" ]; then - JAVACMD="$JAVA_HOME/jre/sh/java" - else - JAVACMD="$JAVA_HOME/bin/java" - fi - [ -x "$JAVACMD" ] || die "JAVA_HOME is invalid: $JAVA_HOME" - else - JAVACMD="java" - which java >/dev/null 2>&1 || die "JAVA_HOME not set and no 'java' in PATH" - fi - "$JAVACMD" -version > /dev/null 2>&1 || die "Java command not working" -} - -checkPid() { - # shellcheck disable=SC2009 - PID=$(ps -ef |grep $FULL_NODE_JAR |grep -v grep |awk '{print $2}') -} - - -stopService() { - checkPid - - if ! kill -0 "$PID" 2>/dev/null; then - info "java-tron is not running." - return 0 - fi - info "Stopping java-tron service (PID: $PID)" - - local count=1 - - while [ -n "$PID" ] && [ $count -le $MAX_STOP_TIME ]; do - kill -TERM "$PID" 2>/dev/null && info "Sent SIGTERM to java-tron (PID: $PID), attempt $count" - sleep 1 - checkPid - count=$((count + 1)) - done - - if [ -n "$PID" ]; then - warn "Forcing kill java-tron (PID: $PID) after $MAX_STOP_TIME seconds" - kill -KILL "$PID" 2>/dev/null - sleep 1 - checkPid - fi - - if [ -n "$PID" ]; then - die "Failed to stop the service (PID: $PID)" - else - info "java-tron stopped" - wait_with_info 2 "Cleaning up..." - fi -} - -startService() { - if [ -n "${FULL_START_OPT[*]}" ]; then - info "Starting java-tron service with options: ${FULL_START_OPT[*]}" - fi - if [ ! -f "$FULL_NODE_JAR" ]; then - die "$FULL_NODE_JAR not found in path $SCRIPT_DIR." - fi - - nohup "$JAVACMD" \ - -Xmx"$VM_XMX" \ - -XX:+UseZGC \ - -Xlog:gc,gc+heap:file=gc.log:time,tags,level:filecount=10,filesize=100M \ - -XX:ReservedCodeCacheSize=256m \ - -XX:+UseCodeCacheFlushing \ - -XX:MetaspaceSize=256m \ - -XX:MaxMetaspaceSize=512m \ - -XX:MaxDirectMemorySize=1g \ - -Dio.netty.allocator.type=pooled \ - -XX:+HeapDumpOnOutOfMemoryError \ - -jar "$FULL_NODE_JAR" "${FULL_START_OPT[@]}" \ - >> start.log 2>&1 & - - - info "Waiting for the service to start..." - wait_with_info 5 "Starting..." - - checkPid - - if [ -n "$PID" ]; then - info "Started java-tron with PID $PID on $HOSTNAME." - else - die "Failed to start java-tron, see start.log or logs/tron.log for details." - fi -} - -wait_with_info() { - local seconds=$1 - local message=$2 - for i in $(seq "$seconds" -1 1); do - info "$message wait ($i) s" - sleep 1 - done -} - - -start() { - checkPid - if [ -n "$PID" ]; then - info "java-tron is already running (PID: $PID), to stop the service: sh start.sh -s" - return - fi - findJava - startService -} - -while [ -n "$1" ]; do - case "$1" in - -s) - stopService - exit 0 - ;; - *) - FULL_START_OPT+=("$@") - break - ;; - esac -done - -start - -exit 0 \ No newline at end of file From a6dcbc645766051885b69b895a66da226d1bf551 Mon Sep 17 00:00:00 2001 From: GrapeS Date: Thu, 17 Sep 2026 14:44:21 +0800 Subject: [PATCH 15/32] update agents.md --- AGENTS.md | 124 +++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 108 insertions(+), 16 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 9f0e06af76b..9e734088789 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,15 +1,16 @@ # AGENTS.md -Guidance for AI coding assistants and new contributors working on java-tron: how to build, test, and navigate the codebase, plus the high-frequency constraints to respect. For running a node, see the [README](./README.md) and [`docs/`](./docs). +Guidance for AI coding assistants and new contributors working on java-tron: how to build, test, and navigate the codebase, plus the constraints that CI enforces and the invariants that must not be broken. For running a node, see the [README](./README.md) and [`docs/`](./docs). -## Working principles +## Guidelines -- Keep changes minimal and focused: only touch code related to the task. Do not refactor unrelated code, rename for style, or bundle unrelated fixes into one commit/PR. -- Do not add, remove, or upgrade dependencies unless the task requires it — dependency changes in a consensus node are high-risk and need separate review. +- **Keep changes minimal and focused.** Only modify code directly related to the task at hand. Do not refactor unrelated code, rename existing variables or functions for style, or bundle unrelated fixes into the same commit or PR. +- **Do not add, remove, or update dependencies** unless the task explicitly requires it. Dependency changes in a consensus node are high-risk, need separate review, and require regenerating dependency verification metadata (see checklist step 6). +- **Never hand-edit generated sources.** Protobuf / gRPC Java stubs are generated at build time from `protocol/src/main/protos/` (`core/`, `api/`) and are git-ignored. Rebuild after changing a `.proto`. ## Build & Test -Supported platforms: **Linux** and **macOS** only. JDK requirement is by CPU architecture: **JDK 8** on x86_64, **JDK 17** on ARM64/aarch64 (e.g. Apple Silicon Macs, or Linux aarch64 servers such as AWS Graviton). The build fails fast if the JDK major version does not match the architecture. +Supported platforms: **Linux** and **macOS** only. The JDK requirement is determined by CPU architecture: **JDK 8** on x86_64, **JDK 17** on ARM64/aarch64 (Apple Silicon, AWS Graviton). The build fails fast if the JDK major version does not match the architecture. ```bash ./gradlew clean build -x test # build without tests @@ -19,19 +20,88 @@ Supported platforms: **Linux** and **macOS** only. JDK requirement is by CPU arc ./gradlew test --tests "org.tron.core.db.TronDatabaseTest" # one class ./gradlew test --tests "org.tron.core.db.TronDatabaseTest.testX" # one method ./gradlew :framework:testWithRocksDb # RocksDB tests (x86 only) -./gradlew lint # Checkstyle (framework main only) -./gradlew checkstyleMain checkstyleTest # Checkstyle main + test (as CI runs) ./gradlew jacocoTestReport # coverage report ``` - Main entry point: `org.tron.program.FullNode`. - Tests run in parallel locally, serially in CI (detected via the `CI` env var); the test-retry plugin retries up to 5 times. - On ARM64/aarch64, only the RocksDB storage engine is supported; the build forces RocksDB and skips the LevelDB tests. -- Protobuf / gRPC Java stubs are generated at build time from the `.proto` files under `protocol/src/main/protos/` (subdirectories `core/`, `api/`; via the `com.google.protobuf` Gradle plugin) and are git-ignored — rebuild after changing a `.proto`; never hand-edit or commit generated sources. +- CI builds the full matrix: **JDK 8 / x86_64** (rockylinux, debian11) and **JDK 17 / aarch64** (macOS, ubuntu24). A change must compile on both. -**Before pushing:** -- `./gradlew checkstyleMain checkstyleTest` and `./gradlew test` must pass. -- Do not commit build artifacts or byproducts — `*.jar`, `build/`, logs, or database files. +## Pre-Commit Checklist + +Run **all** applicable checks before committing. Each maps to a CI job that will otherwise fail the PR. + +### 1. Build + +```bash +./gradlew clean build -x test +``` + +### 2. Tests + +```bash +./gradlew test +``` + +### 3. Checkstyle + +Run exactly what CI runs (`.github/workflows/pr-check.yml`): + +```bash +./gradlew :framework:checkstyleMain :framework:checkstyleTest :plugins:checkstyleMain +``` + +Checkstyle is configured only for `framework`, `protocol`, and `plugins`. A bare `./gradlew checkstyleMain` does not reproduce the CI gate. + +### 4. Forbidden `Math` usage + +CI (`.github/workflows/math-check.yml`) **fails the build on any use of `java.lang.Math`** anywhere in the repository. Only `StrictMathWrapper.java` and `MathWrapper.java` are exempt. + +Use `org.tron.common.math.StrictMathWrapper` instead. Self-check before pushing (same matching logic as CI; `StrictMath.` and string/comment occurrences are correctly ignored): + +```bash +find . -name '*.java' -not -path '*/build/*' | while IFS= read -r f; do + case "$(basename "$f")" in StrictMathWrapper.java|MathWrapper.java) continue;; esac + perl -0777 -ne 's/"([^"\\]|\\.)*"//g; s!/\*([^*]|\*[^/])*\*/!!g; s!//[^\n]*!!g; + print "$ARGV\n" if /(? Date: Thu, 17 Sep 2026 17:22:21 +0800 Subject: [PATCH 16/32] docs: qualify --tests examples with the framework module --- AGENTS.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 9e734088789..7ada21aabc3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -17,8 +17,8 @@ Supported platforms: **Linux** and **macOS** only. The JDK requirement is determ ./gradlew build # build with tests ./gradlew test # run all tests ./gradlew :framework:test # test one module -./gradlew test --tests "org.tron.core.db.TronDatabaseTest" # one class -./gradlew test --tests "org.tron.core.db.TronDatabaseTest.testX" # one method +./gradlew :framework:test --tests "org.tron.core.db.TronDatabaseTest" # one class +./gradlew :framework:test --tests "org.tron.core.db.TronDatabaseTest.testX" # one method ./gradlew :framework:testWithRocksDb # RocksDB tests (x86 only) ./gradlew jacocoTestReport # coverage report ``` From 1b0690f9489e4d5483353e7dba992322d9068968 Mon Sep 17 00:00:00 2001 From: GrapeS Date: Thu, 17 Sep 2026 17:22:32 +0800 Subject: [PATCH 17/32] docs: correct the actuator registration rule in AGENTS.md --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 7ada21aabc3..7ec6b4b573f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -145,7 +145,7 @@ crypto → common - Multi-store updates must roll back fully on exception. **Actuator:** -- Register new actuators in `ActuatorFactory`. +- New actuators are registered automatically: place the class in the `org.tron.core.actuator` package, extend `AbstractActuator`, and pass the `ContractType` to `super(...)` from a no-arg constructor. `TransactionRegister.registerActuator()` discovers it by reflection at startup — there is no manual registration step. - Charge fees before `execute()`. - `validate()` must not mutate state. From 016e7279203a3100c54c5bd296d2df610a1b26be Mon Sep 17 00:00:00 2001 From: GrapeS Date: Thu, 17 Sep 2026 17:22:39 +0800 Subject: [PATCH 18/32] docs: use the fully qualified StrictMathWrapper name --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 7ec6b4b573f..e86421439b3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -133,7 +133,7 @@ crypto → common ## Hard Constraints **Cross-JVM determinism** (consensus, state transition, block ordering) — the same block must produce the same state on every supported platform: -- Never use `java.lang.Math` — use `StrictMathWrapper` (CI-enforced, see checklist step 4). +- Never use `java.lang.Math` — use `org.tron.common.math.StrictMathWrapper` instead (CI-enforced, see checklist step 4). - Never use `float` / `double` in consensus-relevant arithmetic. - Never depend on `HashMap` iteration order for a business decision. - Use the DPoS slot time for produced-block timestamps, not `System.currentTimeMillis()`. From d785afbe0f859773f798c138ec5d1e41adde63b0 Mon Sep 17 00:00:00 2001 From: GrapeS Date: Thu, 17 Sep 2026 17:25:24 +0800 Subject: [PATCH 19/32] docs: reference the real ISession type in the DB rule --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index e86421439b3..e0addcc21e2 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -140,7 +140,7 @@ crypto → common - Never call `String.toLowerCase()` / `toUpperCase()` without an explicit `Locale` — ErrorProne enforces this as a compile error (`StringCaseLocaleUsage`). **DB / Store:** -- All writes must happen inside a `Session` / `Dialog` — no bare `put()`. +- All writes must happen inside a revocable session — `try (ISession session = revokingStore.buildSession())` — never a bare `put()`. - A new store must extend `TronStoreWithRevoking` and register with the `RevokingDatabase`. - Multi-store updates must roll back fully on exception. From ff4ca6c404da316b07ec578587cb74defeced5b4 Mon Sep 17 00:00:00 2001 From: GrapeS Date: Thu, 17 Sep 2026 17:25:31 +0800 Subject: [PATCH 20/32] docs: correct the lite-fullnode query rule in AGENTS.md --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index e0addcc21e2..49c39416acf 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -155,7 +155,7 @@ crypto → common **API / Threads:** - New HTTP servlets must go through `HttpApiAccessFilter` and use `Wallet` (never inject `Manager` directly). -- New gRPC methods must join the `LiteFnQueryGrpcInterceptor` chain. +- A new gRPC or HTTP query that depends on historical data (unavailable on a lite fullnode) must be added to the deny-list in `LiteFnQueryGrpcInterceptor` / `LiteFnQueryHttpFilter`; other methods need no action — the interceptor and filter are installed server-wide. - No bare `new Thread()` — use a named Executor, shut down via `shutdown()` → `awaitTermination()` → `shutdownNow()`. ## Common Pitfalls From 92ff47508efc0994adc444ea027619d87d439b70 Mon Sep 17 00:00:00 2001 From: GrapeS Date: Thu, 17 Sep 2026 17:29:06 +0800 Subject: [PATCH 21/32] docs: point commit convention to CONTRIBUTING.md --- AGENTS.md | 15 ++------------- 1 file changed, 2 insertions(+), 13 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 49c39416acf..92962130358 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -178,17 +178,6 @@ crypto → common ## Commit & PR Convention -`type(scope): description` (Conventional Commits), 10–72 characters, no trailing period. +Commit messages and PR titles follow `type(scope): description`. The allowed types, the full scope list and the subject rules are defined in [CONTRIBUTING.md](./CONTRIBUTING.md#commit-messages) — follow it there. -- **type:** `feat` `fix` `refactor` `docs` `style` `test` `chore` `ci` `perf` `build` `revert` -- **scope:** `framework` `chainbase` `actuator` `consensus` `common` `crypto` `plugins` `protocol` `net` `db` `vm` `tvm` `api` `jsonrpc` `rpc` `http` `event` `config` `block` `proposal` `trie` `log` `metrics` `test` `docker` `version` - -Examples: - -``` -fix(vm): correct energy accounting for CREATE2 -feat(api): add block header endpoint to solidity node -refactor(chainbase): extract snapshot flush into its own method -``` - -**PR titles follow the same convention and are validated automatically** (`.github/workflows/pr-check.yml`): 10–72 characters, a recognised `type(scope)` prefix, and no trailing period. Fill in `.github/PULL_REQUEST_TEMPLATE.md`; the description is checked as well. +PR titles and descriptions are validated in CI by `.github/workflows/pr-check.yml`. Fill in `.github/PULL_REQUEST_TEMPLATE.md`. From d6dfa94cef049a8d4b9de8943091be62add8b8f0 Mon Sep 17 00:00:00 2001 From: GrapeS Date: Thu, 17 Sep 2026 17:33:14 +0800 Subject: [PATCH 22/32] docs: drop Script from the README executables header --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 9c32f7bbf6d..c0a85d38b36 100644 --- a/README.md +++ b/README.md @@ -77,7 +77,7 @@ git checkout -t origin/master The java-tron project comes with several runnable artifacts found in the build directories. -| Artifact/Script | Description | +| Artifact | Description | | :---------------------- | :---------- | | **`FullNode.jar`** | Main TRON node executable (generated in `build/libs/` after a successful build following the above guidance). Runs as a full node by default. `java -jar FullNode.jar --help` for command line options| | **`Toolkit.jar`** | Node management utility (generated in `build/libs/`): partition, prune, copy, convert DBs; shadow-fork tool. [Usage](https://tronprotocol.github.io/documentation-en/using_javatron/toolkit/#toolkit-a-java-tron-node-maintenance-suite) | From f4571000b62619240c6dd1f27fa01354c9b465d8 Mon Sep 17 00:00:00 2001 From: GrapeS Date: Fri, 18 Sep 2026 13:57:07 +0800 Subject: [PATCH 23/32] docs: correct test parallelism and actuator fee rules in AGENTS.md --- AGENTS.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 92962130358..6f3d7e4d317 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -24,7 +24,7 @@ Supported platforms: **Linux** and **macOS** only. The JDK requirement is determ ``` - Main entry point: `org.tron.program.FullNode`. -- Tests run in parallel locally, serially in CI (detected via the `CI` env var); the test-retry plugin retries up to 5 times. +- Tests also run in parallel in CI: `framework/build.gradle` sets `maxParallelForks` without checking the `CI` env var. Each module configures its own test parallelism in its `build.gradle`. - On ARM64/aarch64, only the RocksDB storage engine is supported; the build forces RocksDB and skips the LevelDB tests. - CI builds the full matrix: **JDK 8 / x86_64** (rockylinux, debian11) and **JDK 17 / aarch64** (macOS, ubuntu24). A change must compile on both. @@ -146,7 +146,7 @@ crypto → common **Actuator:** - New actuators are registered automatically: place the class in the `org.tron.core.actuator` package, extend `AbstractActuator`, and pass the `ContractType` to `super(...)` from a no-arg constructor. `TransactionRegister.registerActuator()` discovers it by reflection at startup — there is no manual registration step. -- Charge fees before `execute()`. +- `validate()` must check that the owner can afford `calcFee()` plus any amount being moved; the fee itself is charged inside `execute()` together with the state change, so a failed `execute()` rolls back both. Bandwidth, multi-signature and memo fees are charged by `Manager.processTransaction()` before the actuator runs — an actuator never touches them. - `validate()` must not mutate state. **Protobuf:** From 642e5396a89507e675d3c9079b93026b2de36ce1 Mon Sep 17 00:00:00 2001 From: GrapeS Date: Wed, 23 Sep 2026 11:10:29 +0800 Subject: [PATCH 24/32] chore: restore start.sh and start.sh.simple --- start.sh | 623 ++++++++++++++++++++++++++++++++++++++++++++++++ start.sh.simple | 193 +++++++++++++++ 2 files changed, 816 insertions(+) create mode 100644 start.sh create mode 100644 start.sh.simple diff --git a/start.sh b/start.sh new file mode 100644 index 00000000000..1472a94dc62 --- /dev/null +++ b/start.sh @@ -0,0 +1,623 @@ +#!/bin/bash +############################################################################# +# +# GNU LESSER GENERAL PUBLIC LICENSE +# Version 3, 29 June 2007 +# +# Copyright (C) [2007] [TRON Foundation], Inc. +# Everyone is permitted to copy and distribute verbatim copies +# of this license document, but changing it is not allowed. +# +# +# This version of the GNU Lesser General Public License incorporates +# the terms and conditions of version 3 of the GNU General Public +# License, supplemented by the additional permissions listed below. +# +# You can find java-tron at https://github.com/tronprotocol/java-tron/ +# +############################################################################## + +# Build FullNode config +FULL_NODE_DIR="FullNode" +FULL_NODE_CONFIG_DIR="config" +# config file +FULL_NODE_CONFIG_MAIN_NET="main_net_config.conf" +FULL_NODE_CONFIG_TEST_NET="test_net_config.conf" +FULL_NODE_CONFIG_PRIVATE_NET="private_net_config.conf" +DEFAULT_FULL_NODE_CONFIG='config.conf' +JAR_NAME="FullNode.jar" +FULL_START_OPT='' + +# Github +GITHUB_BRANCH='master' +GITHUB_CLONE_TYPE='HTTPS' +GITHUB_REPOSITORY='' +GITHUB_REPOSITORY_HTTPS_URL='https://github.com/tronprotocol/java-tron.git' +GITHUB_REPOSITORY_SSH_URL='git@github.com:tronprotocol/java-tron.git' + +# Shell option +ALL_OPT_LENGTH=$# +# Start service option +MAX_STOP_TIME=60 +# Modify this option to allow the minimum memory to be started, unit MB +ALLOW_MIN_MEMORY=8192 + +# JVM option +MAX_DIRECT_MEMORY=1g +JVM_MS=4g +JVM_MX=4g +IS_BACKUP_GC_LOG=true + +SPECIFY_MEMORY=0 +RUN=false +UPGRADE=false + +# Rebuild manifest +REBUILD_MANIFEST=true +REBUILD_DIR="$PWD/output-directory/database" +REBUILD_MANIFEST_SIZE=0 +REBUILD_BATCH_SIZE=80000 + +# Download and upgrade +DOWNLOAD=false +RELEASE_URL='https://github.com/tronprotocol/java-tron/releases' +QUICK_START=false +CLONE_BUILD=false + +if [[ $GITHUB_CLONE_TYPE == 'HTTPS' ]]; then + GITHUB_REPOSITORY=$GITHUB_REPOSITORY_HTTPS_URL +else + GITHUB_REPOSITORY=$GITHUB_REPOSITORY_SSH_URL +fi + +# Determine the Java command to use to start the JVM. +if [ -z "$JAVA_HOME" ]; then + javaExecutable="`which javac`" + if [ -n "$javaExecutable" ] && ! [ "`expr \"$javaExecutable\" : '\([^ ]*\)'`" = "no" ]; then + # readlink(1) is not available as standard on Solaris 10. + readLink=`which readlink` + if [ ! `expr "$readLink" : '\([^ ]*\)'` = "no" ]; then + if $darwin ; then + javaHome="`dirname \"$javaExecutable\"`" + javaExecutable="`cd \"$javaHome\" && pwd -P`/javac" + else + javaExecutable="`readlink -f \"$javaExecutable\"`" + fi + javaHome="`dirname \"$javaExecutable\"`" + javaHome=`expr "$javaHome" : '\(.*\)/bin'` + JAVA_HOME="$javaHome" + export JAVA_HOME + fi + fi +fi + +if [ -z "$JAVACMD" ] ; then + if [ -n "$JAVA_HOME" ] ; then + if [ -x "$JAVA_HOME/jre/sh/java" ] ; then + # IBM's JDK on AIX uses strange locations for the executables + JAVACMD="$JAVA_HOME/jre/sh/java" + else + JAVACMD="$JAVA_HOME/bin/java" + fi + else + JAVACMD="`which java`" + fi +fi + +if [ ! -x "$JAVACMD" ] ; then + echo "Error: JAVA_HOME is not defined correctly." >&2 + echo " We cannot execute $JAVACMD" >&2 + exit 1 +fi + +if [ -z "$JAVA_HOME" ] ; then + echo "Warning: JAVA_HOME environment variable is not set." +fi + +backupGCLog() { + local maxFile=5 + local gcLogDir=logs/gc_logs/ + if [ ! -d "$gcLogDir" ];then + mkdir -p 'logs/gc_logs' + fi + + if [ -f 'gc.log' ]; then + echo '[info] backup gc.log' + local dateformat=`date "+%Y-%m-%d_%H-%M-%S"` + tar -czvf gc.log_$dateformat'.tar.gz' gc.log + mv gc.log_$dateformat'.tar.gz' $gcLogDir + rm -rf gc.log + + # checking the number of backups + local currentDirCount=`ls -l $gcLogDir | grep "gc.log*" | wc -l` + if [ $currentDirCount -gt $maxFile ]; then + local oldFileSize=`expr $currentDirCount - $maxFile` + local oldGcLogFiles=(`ls -1 $gcLogDir |head -n $oldFileSize`) + fi + + for fileName in ${oldGcLogFiles[@]}; do + rm -rf $gcLogDir$fileName + done + fi +} + +getLatestReleaseVersion() { + full_node_version=`git ls-remote --tags $GITHUB_REPOSITORY |grep GreatVoyage- | awk -F '/' 'END{print $3}'` + if [[ -n $full_node_version ]]; then + echo $full_node_version + else + echo '' + fi +} + +checkVersion() { + github_release_version=$(`echo getLatestReleaseVersion`) + if [[ -n $github_release_version ]]; then + echo "info: github latest version: $github_release_version" + echo $github_release_version + else + echo 'info: not getting the latest version' + exit + fi +} + +upgrade() { + latest_version=$(`echo getLatestReleaseVersion`) + echo "info: latest version: $latest_version" + if [[ -n $latest_version ]]; then + old_jar="$PWD/$JAR_NAME" + if [[ -f $old_jar ]]; then + echo "info: backup $old_jar" + mv $PWD/$JAR_NAME $PWD/$JAR_NAME'_bak' + fi + download $RELEASE_URL/download/$latest_version/$JAR_NAME $JAR_NAME + if [[ $? == 0 ]]; then + echo "info: download version $latest_version success" + fi + else + echo 'info: nothing to upgrade' + fi +} + +download() { + local url=$1 + local file_name=$2 + if type wget >/dev/null 2>&1; then + wget --no-check-certificate -q $url + elif type curl >/dev/null 2>&1; then + echo "curl -OLJ $url" + curl -OLJ $url + else + echo 'info: no exists wget or curl, make sure the system can use the "wget" or "curl" command' + fi +} + +mkdirFullNode() { + if [ ! -d $FULL_NODE_DIR ]; then + echo "info: create $FULL_NODE_DIR" + mkdir $FULL_NODE_DIR + $(cp $0 $FULL_NODE_DIR) + cd $FULL_NODE_DIR + elif [ -d $FULL_NODE_DIR ]; then + cd $FULL_NODE_DIR + fi +} + +quickStart() { + full_node_version=$(`echo getLatestReleaseVersion`) + if [[ -n $full_node_version ]]; then + mkdirFullNode + echo "info: check latest version: $full_node_version" + echo 'info: download config' + download https://raw.githubusercontent.com/tronprotocol/tron-deployment/$GITHUB_BRANCH/$FULL_NODE_CONFIG_MAIN_NET $FULL_NODE_CONFIG_MAIN_NET + mv $FULL_NODE_CONFIG_MAIN_NET 'config.conf' + + echo "info: download $full_node_version" + download $RELEASE_URL/download/$full_node_version/$JAR_NAME $JAR_NAME + checkSign + else + echo 'info: not getting the latest version' + exit + fi +} + +cloneCode() { + if type git >/dev/null 2>&1; then + git_clone=$(git clone -b $GITHUB_BRANCH $GITHUB_REPOSITORY) + if [[ git_clone == 0 ]]; then + echo 'info: git clone java-tron success' + fi + else + echo 'info: no exists git, make sure the system can use the "git" command' + fi +} + +cloneBuild() { + local currentPwd=$PWD + echo 'info: clone java-tron' + cloneCode + + echo 'info: build java-tron' + cd java-tron + sh gradlew clean build -x test + if [[ $? == 0 ]];then + cd $currentPwd + mkdirFullNode + cp '../java-tron/build/libs/FullNode.jar' $PWD + cp '../java-tron/framework/src/main/resources/config.conf' $PWD + else + exit + fi +} + +checkPid() { + if [[ $JAR_NAME =~ '/' ]]; then + JAR_NAME=$(echo $JAR_NAME |awk -F '/' '{print $NF}') + fi + pid=$(ps -ef | grep -v start | grep $JAR_NAME | grep -v grep | awk '{print $2}') + return $pid +} + +stopService() { + count=1 + while [ $count -le $MAX_STOP_TIME ]; do + checkPid + if [ $pid ]; then + kill -15 $pid + sleep 1 + else + echo "info: java-tron stop" + return + fi + count=$(($count + 1)) + if [ $count -eq $MAX_STOP_TIME ]; then + kill -9 $pid + sleep 1 + fi + done + sleep 5 +} + +checkAllowMemory() { + os=`uname` + totalMemory=$(`echo getTotalMemory`) + total=`expr $totalMemory / 1024` + if [[ $os == 'Darwin' ]]; then + return + fi + + if [[ $total -lt $ALLOW_MIN_MEMORY ]]; then + echo "warn: the memory $total MB cannot be smaller than the minimum memory $ALLOW_MIN_MEMORY MB" + exit + elif [[ $SPECIFY_MEMORY -gt 0 ]] && + [[ $SPECIFY_MEMORY -lt $ALLOW_MIN_MEMORY ]]; then + echo "warn: the specified memory $SPECIFY_MEMORY MB cannot be smaller than the minimum memory $ALLOW_MIN_MEMORY MB" + echo 'warn: start abort' + exit + fi +} + +setTCMalloc() { + os=`uname` + if [[ $os == 'Linux' ]] || [[ $os == 'linux' ]] ; then + lib_tc_malloc="/usr/lib64/libtcmalloc.so" + if [[ -f $lib_tc_malloc ]]; then + export LD_PRELOAD="$lib_tc_malloc" + export TCMALLOC_RELEASE_RATE=10 + else + echo 'info: recommended for linux systems using tcmalloc as the default memory management tool' + fi + fi +} + +getTotalMemory() { + os=`uname` + if [[ $os == 'Linux' ]] || [[ $os == 'linux' ]] ; then + total=$(cat /proc/meminfo | grep MemTotal | awk -F ' ' '{print $2}') + echo $total + return + elif [[ $os == 'Darwin' ]]; then + total=$(sysctl -a | grep mem |grep hw.memsize |awk -F ' ' '{print $2}') + echo `expr $total / 1024` + fi +} + +setJVMMemory() { + os=`uname` + if [[ $os == 'Linux' ]] || [[ $os == 'linux' ]] ; then + if [[ $SPECIFY_MEMORY >0 ]]; then + max_direct=$(echo "$SPECIFY_MEMORY/1024*0.1" | bc | awk -F. '{print $1"g"}') + if [[ "$max_direct" != "g" ]]; then + MAX_DIRECT_MEMORY=$max_direct + fi + JVM_MX=$(echo "$SPECIFY_MEMORY/1024*0.6" | bc | awk -F. '{print $1"g"}') + JVM_MS=$JVM_MX + else + total=$(`echo getTotalMemory`) + MAX_DIRECT_MEMORY=$(echo "$total/1024/1024*0.1" | bc | awk -F. '{print $1"g"}') + JVM_MX=$(echo "$total/1024/1024*0.6" | bc | awk -F. '{print $1"g"}') + JVM_MS=$JVM_MX + fi + + elif [[ $os == 'Darwin' ]]; then + MAX_DIRECT_MEMORY='1g' + fi +} + +startService() { + echo $(date) >>start.log + if [[ ! $JAR_NAME =~ '-c' ]]; then + FULL_START_OPT="$FULL_START_OPT -c $DEFAULT_FULL_NODE_CONFIG" + fi + + if [[ ! -f $JAR_NAME ]]; then + echo "warn: jar file $JAR_NAME not exist" + exit + fi + + nohup $JAVACMD -Xms$JVM_MS -Xmx$JVM_MX -XX:+UseConcMarkSweepGC -XX:+PrintGCDetails -Xloggc:./gc.log \ + -XX:+PrintGCDateStamps -XX:+CMSParallelRemarkEnabled -XX:ReservedCodeCacheSize=256m -XX:+UseCodeCacheFlushing \ + -XX:MetaspaceSize=256m -XX:MaxMetaspaceSize=512m \ + -XX:MaxDirectMemorySize=$MAX_DIRECT_MEMORY -Dio.netty.allocator.type=pooled \ + -XX:+HeapDumpOnOutOfMemoryError \ + -XX:NewRatio=2 -jar \ + $JAR_NAME $FULL_START_OPT >>start.log 2>&1 & + checkPid + echo "info: start java-tron with pid $pid on $HOSTNAME" + echo "info: if you need to stop the service, execute: sh start.sh --stop" +} + +rebuildManifest() { + if [[ $REBUILD_MANIFEST = false ]]; then + echo 'info: disable rebuild manifest!' + return + fi + + if [[ ! -d $REBUILD_DIR ]]; then + echo "info: database not exists, skip rebuild manifest" + return + fi + + ARCHIVE_JAR='ArchiveManifest.jar' + if [[ -f $ARCHIVE_JAR ]]; then + echo 'info: execute rebuild manifest.' + $JAVACMD -jar $ARCHIVE_JAR -d $REBUILD_DIR -m $REBUILD_MANIFEST_SIZE -b $REBUILD_BATCH_SIZE + else + echo 'info: download the rebuild manifest plugin from the github' + local latest=$(`echo getLatestReleaseVersion`) + download $RELEASE_URL/download/GreatVoyage-v"$latest"/$ARCHIVE_JAR $ARCHIVE_JAR + if [[ $download == 0 ]]; then + echo 'info: download success, rebuild manifest' + $JAVACMD -jar $ARCHIVE_JAR $REBUILD_DIR -m $REBUILD_MANIFEST_SIZE -b $REBUILD_BATCH_SIZE + fi + fi + if [[ $? == 0 ]]; then + echo 'info: rebuild manifest success' + else + echo 'info: rebuild manifest fail, log in logs/archive.log' + fi +} + +specifyConfig(){ + echo "info: specify the net: $1" + local netType=$1 + local configName; + if [[ "$netType" = 'test' ]]; then + configName=$FULL_NODE_CONFIG_TEST_NET + elif [[ "$netType" = 'private' ]]; then + configName=$FULL_NODE_CONFIG_PRIVATE_NET + else + echo "warn: no support config $nodeType" + exit + fi + + if [[ ! -d $FULL_NODE_CONFIG_DIR ]]; then + mkdir -p $FULL_NODE_CONFIG_DIR + fi + + if [[ -d $FULL_NODE_CONFIG_DIR/$configName ]]; then + DEFAULT_FULL_NODE_CONFIG=$FULL_NODE_CONFIG_DIR/$configName + break + fi + + if [[ ! -f $FULL_NODE_CONFIG_DIR/$configName ]]; then + download https://raw.githubusercontent.com/tronprotocol/tron-deployment/$GITHUB_BRANCH/$configName $configName + mv $configName $FULL_NODE_CONFIG_DIR/$configName + DEFAULT_FULL_NODE_CONFIG=$FULL_NODE_CONFIG_DIR/$configName + fi +} + +checkSign() { + echo 'info: verify signature' + local latest_version=$(`echo getLatestReleaseVersion`) + download $RELEASE_URL/download/$latest_version/sha256sum.txt sha256sum.txt + fullNodeSha256=$(cat sha256sum.txt|grep 'FullNode'| awk -F ' ' '{print $1}') + + os=`uname` + if [[ $os == 'Linux' ]] || [[ $os == 'linux' ]] ; then + releaseFullNodeSha256=$(sha256sum FullNode.jar| grep FullNode | awk -F ' ' '{print $1}') + elif [[ $os == 'Darwin' ]]; then + releaseFullNodeSha256=$(shasum -a 256 FullNode.jar| grep FullNode | awk -F ' ' '{print $1}') + cat $releaseFullNodeSha256 | awk -F ' ' '{print $0}' + fi + + echo "info: release sha256sum sign: $releaseFullNodeSha256" + echo "info: FullNode.jar sha256sum sign: $fullNodeSha256" + + if [[ "$fullNodeSha256" == "$releaseFullNodeSha256" ]]; then + echo 'info: sha256 signatures pass' + else + echo 'info: sha256 signature exception!!!' + echo 'info: please compile from the code or download the latest version from https://github.com/tronprotocol/java-tron' + fi +} + +restart() { + stopService + checkAllowMemory + rebuildManifest + setTCMalloc + setJVMMemory + startService +} + +while [ -n "$1" ]; do + case "$1" in + -c) + DEFAULT_FULL_NODE_CONFIG=$2 + shift 2 + ;; + -d) + REBUILD_DIR=$2/database + FULL_START_OPT="$FULL_START_OPT $1 $2" + shift 2 + ;; + -j) + JAR_NAME=$2 + shift 2 + ;; + -p) + FULL_START_OPT="$FULL_START_OPT $1 $2" + shift 2 + ;; + -w) + FULL_START_OPT="$FULL_START_OPT $1" + shift 1 + ;; + --witness) + FULL_START_OPT="$FULL_START_OPT $1" + shift 1 + ;; + --net) + specifyConfig $2 + shift 2 + ;; + -m) + REBUILD_MANIFEST_SIZE=$2 + shift 2 + ;; + -n) + JAR_NAME=$2 + shift 2 + ;; + -b) + REBUILD_BATCH_SIZE=$2 + shift 2 + ;; + -cb) + CLONE_BUILD=true + shift 1 + ;; + --download) + DOWNLOAD=true + shift 1 + ;; + --deploy) + QUICK_START=true + shift 1 + ;; + --release) + QUICK_START=true + shift 1 + ;; + --clone) + cloneCode + exit + ;; + -mem) + SPECIFY_MEMORY=$2 + shift 2 + ;; + --disable-rewrite-manifes) + REBUILD_MANIFEST=false + shift 1 + ;; + -dr) + REBUILD_MANIFEST=false + shift 1 + ;; + --upgrade) + UPGRADE=true + shift 1 + ;; + --run) + if [[ $ALL_OPT_LENGTH -eq 1 ]]; then + restart + fi + RUN=true + shift 1 + ;; + --stop) + stopService + ;; + FullNode) + RUN=true + shift 1 + ;; + FullNode.jar) + RUN=true + shift 1 + ;; + *.jar) + RUN=true + shift 1 + ;; + *) + if [[ $ALL_OPT_LENGTH -eq 1 ]]; then + if [[ ! "$1" =~ "-" ]] && [[ ! "$1" =~ "--" ]]; then + if [[ $1 =~ '.jar' ]]; then + JAR_NAME=$1 + else + JAR_NAME="$1.jar" + fi + restart + exit + fi + fi + FULL_START_OPT="$FULL_START_OPT $@" + break + ;; + esac +done + +if [[ $IS_BACKUP_GC_LOG = true ]]; then + backupGCLog +fi + +if [[ $CLONE_BUILD == true ]];then + cloneBuild +fi + +if [[ $QUICK_START == true ]]; then + quickStart + if [[ $? == 0 ]] ; then + if [[ $RUN == true ]]; then + cd $FULL_NODE_DIR + FULL_START_OPT='' + restart + fi + fi +fi + +if [[ $UPGRADE == true ]]; then + upgrade +fi + +if [[ $DOWNLOAD == true ]]; then + latest=$(`echo getLatestReleaseVersion`) + if [[ -n $latest ]]; then + download $RELEASE_URL/download/$latest/$JAR_NAME $latest + exit + else + echo 'info: not getting the latest version' + fi +fi + +if [[ $ALL_OPT_LENGTH -eq 0 || $ALL_OPT_LENGTH -gt 0 ]]; then + restart +fi + +if [[ $RUN == true ]]; then + restart +fi + diff --git a/start.sh.simple b/start.sh.simple new file mode 100644 index 00000000000..109f0dc85a3 --- /dev/null +++ b/start.sh.simple @@ -0,0 +1,193 @@ +#!/bin/bash +############################################################################# +# +# GNU LESSER GENERAL PUBLIC LICENSE +# Version 3, 29 June 2007 +# +# Copyright (C) [2007] [TRON Foundation], Inc. +# Everyone is permitted to copy and distribute verbatim copies +# of this license document, but changing it is not allowed. +# +# +# This version of the GNU Lesser General Public License incorporates +# the terms and conditions of version 3 of the GNU General Public +# License, supplemented by the additional permissions listed below. +# +# You can find java-tron at https://github.com/tronprotocol/java-tron/ +# +############################################################################## +# TRON Full Node Management Simple Script +# +# NOTE: This is a simple and concise script to start and stop the java-tron full node, +# designed for developers to quickly get started and learn. +# It may not be suitable for production environments. +# +# Usage: +# sh start.sh # Start the java-tron FullNode +# sh start.sh -s # Stop the java-tron FullNode +# sh start.sh [options] # Start with additional java-tron options,such as: -c config.conf -d /path_to_data, etc. +# +############################################################################## + + +# adjust JVM start +# Set the maximum heap size to 9G, adjust as needed +VM_XMX="9G" +# adjust JVM end + +FULL_NODE_JAR="FullNode.jar" +FULL_START_OPT=() +PID="" +MAX_STOP_TIME=60 +JAVACMD="" +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" + +RED='\033[0;31m' +GREEN='\033[0;32m' +YELLOW='\033[1;33m' +NC='\033[0m' + +log() { + local level="$1"; shift + local timestamp color="" + timestamp=$(date '+%Y-%m-%d %H:%M:%S') + case "$level" in + INFO) color="$GREEN" ;; + WARN) color="$YELLOW" ;; + ERROR) color="$RED" ;; + esac + printf "%b[%s] [%s]:%b %s\n" "$color" "$timestamp" "$level" "$NC" "$*" | tee -a "${SCRIPT_DIR}/start.log" +} + +info() { log INFO "$@"; } +warn() { log WARN "$@"; } +error() { log ERROR "$@"; } +die() { error "$@"; exit 1; } + +ulimit -n 65535 || warn "Failed to set ulimit -n 65535" + +findJava() { + if [ -n "${JAVA_HOME:-}" ]; then + if [ -x "$JAVA_HOME/jre/sh/java" ]; then + JAVACMD="$JAVA_HOME/jre/sh/java" + else + JAVACMD="$JAVA_HOME/bin/java" + fi + [ -x "$JAVACMD" ] || die "JAVA_HOME is invalid: $JAVA_HOME" + else + JAVACMD="java" + which java >/dev/null 2>&1 || die "JAVA_HOME not set and no 'java' in PATH" + fi + "$JAVACMD" -version > /dev/null 2>&1 || die "Java command not working" +} + +checkPid() { + # shellcheck disable=SC2009 + PID=$(ps -ef |grep $FULL_NODE_JAR |grep -v grep |awk '{print $2}') +} + + +stopService() { + checkPid + + if ! kill -0 "$PID" 2>/dev/null; then + info "java-tron is not running." + return 0 + fi + info "Stopping java-tron service (PID: $PID)" + + local count=1 + + while [ -n "$PID" ] && [ $count -le $MAX_STOP_TIME ]; do + kill -TERM "$PID" 2>/dev/null && info "Sent SIGTERM to java-tron (PID: $PID), attempt $count" + sleep 1 + checkPid + count=$((count + 1)) + done + + if [ -n "$PID" ]; then + warn "Forcing kill java-tron (PID: $PID) after $MAX_STOP_TIME seconds" + kill -KILL "$PID" 2>/dev/null + sleep 1 + checkPid + fi + + if [ -n "$PID" ]; then + die "Failed to stop the service (PID: $PID)" + else + info "java-tron stopped" + wait_with_info 2 "Cleaning up..." + fi +} + +startService() { + if [ -n "${FULL_START_OPT[*]}" ]; then + info "Starting java-tron service with options: ${FULL_START_OPT[*]}" + fi + if [ ! -f "$FULL_NODE_JAR" ]; then + die "$FULL_NODE_JAR not found in path $SCRIPT_DIR." + fi + + nohup "$JAVACMD" \ + -Xmx"$VM_XMX" \ + -XX:+UseZGC \ + -Xlog:gc,gc+heap:file=gc.log:time,tags,level:filecount=10,filesize=100M \ + -XX:ReservedCodeCacheSize=256m \ + -XX:+UseCodeCacheFlushing \ + -XX:MetaspaceSize=256m \ + -XX:MaxMetaspaceSize=512m \ + -XX:MaxDirectMemorySize=1g \ + -Dio.netty.allocator.type=pooled \ + -XX:+HeapDumpOnOutOfMemoryError \ + -jar "$FULL_NODE_JAR" "${FULL_START_OPT[@]}" \ + >> start.log 2>&1 & + + + info "Waiting for the service to start..." + wait_with_info 5 "Starting..." + + checkPid + + if [ -n "$PID" ]; then + info "Started java-tron with PID $PID on $HOSTNAME." + else + die "Failed to start java-tron, see start.log or logs/tron.log for details." + fi +} + +wait_with_info() { + local seconds=$1 + local message=$2 + for i in $(seq "$seconds" -1 1); do + info "$message wait ($i) s" + sleep 1 + done +} + + +start() { + checkPid + if [ -n "$PID" ]; then + info "java-tron is already running (PID: $PID), to stop the service: sh start.sh -s" + return + fi + findJava + startService +} + +while [ -n "$1" ]; do + case "$1" in + -s) + stopService + exit 0 + ;; + *) + FULL_START_OPT+=("$@") + break + ;; + esac +done + +start + +exit 0 \ No newline at end of file From 800f0849fc680b3df77aa81947c1f5f8f6b78e3f Mon Sep 17 00:00:00 2001 From: GrapeS Date: Wed, 23 Sep 2026 11:10:29 +0800 Subject: [PATCH 25/32] fix: disable download in start.sh download() now prints a notice and returns non-zero; release files must be fetched and verified manually. It returns instead of exiting so that restart() still completes when rebuildManifest reaches it. --- start.sh | 2 ++ 1 file changed, 2 insertions(+) diff --git a/start.sh b/start.sh index 1472a94dc62..ac11f6c9508 100644 --- a/start.sh +++ b/start.sh @@ -180,6 +180,8 @@ upgrade() { } download() { + echo "warn: download is disabled, fetch $1 manually and verify it" + return 1 local url=$1 local file_name=$2 if type wget >/dev/null 2>&1; then From 6d40041ac53f91aea29b2b265915d6065aa9ef3c Mon Sep 17 00:00:00 2001 From: GrapeS Date: Wed, 23 Sep 2026 17:41:36 +0800 Subject: [PATCH 26/32] revert: disable download in start.sh This reverts commit 800f0849fc. --- start.sh | 2 -- 1 file changed, 2 deletions(-) diff --git a/start.sh b/start.sh index ac11f6c9508..1472a94dc62 100644 --- a/start.sh +++ b/start.sh @@ -180,8 +180,6 @@ upgrade() { } download() { - echo "warn: download is disabled, fetch $1 manually and verify it" - return 1 local url=$1 local file_name=$2 if type wget >/dev/null 2>&1; then From 3c0762220e942e3a245530527881ab9d7f8a5608 Mon Sep 17 00:00:00 2001 From: GrapeS Date: Mon, 28 Sep 2026 14:36:10 +0800 Subject: [PATCH 27/32] docs: restore shell.md and start script entries in README start.sh and start.sh.simple are not changed on this branch, so keep their guide and their rows in the README Executables table. --- README.md | 6 +- shell.md | 236 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 240 insertions(+), 2 deletions(-) create mode 100644 shell.md diff --git a/README.md b/README.md index c0a85d38b36..a9d740bf4fd 100644 --- a/README.md +++ b/README.md @@ -75,12 +75,14 @@ git checkout -t origin/master # Executables -The java-tron project comes with several runnable artifacts found in the build directories. +The java-tron project comes with several runnable artifacts and helper scripts found in the project root and build directories. -| Artifact | Description | +| Artifact/Script | Description | | :---------------------- | :---------- | | **`FullNode.jar`** | Main TRON node executable (generated in `build/libs/` after a successful build following the above guidance). Runs as a full node by default. `java -jar FullNode.jar --help` for command line options| | **`Toolkit.jar`** | Node management utility (generated in `build/libs/`): partition, prune, copy, convert DBs; shadow-fork tool. [Usage](https://tronprotocol.github.io/documentation-en/using_javatron/toolkit/#toolkit-a-java-tron-node-maintenance-suite) | +| **`start.sh`** | Quick start script (x86_64, JDK 8) to download/build/run `FullNode.jar`. See the tool [guide](./shell.md). | +| **`start.sh.simple`** | Quick start script template (ARM64, JDK 17). See usage notes inside the script. | # Running java-tron diff --git a/shell.md b/shell.md new file mode 100644 index 00000000000..700067a9aa3 --- /dev/null +++ b/shell.md @@ -0,0 +1,236 @@ +# Quick Start Scripting Tool + +# Introduction + +Using the `start.sh` script, you can quickly and easily run and build java-tron. + +If you already downloaded the `FullNode.jar`, you can use `start.sh` to run it, or if you have not downloaded java-tron source code or jar packages, you can use `start.sh` to download the source code, compile, run or get the latest release version in the form of a `jar package ` and run. + +The script is available in the java-tron project at [github](https://github.com/tronprotocol/java-tron), or if you need a separate script: [start.sh](https://github.com/tronprotocol/java-tron/blob/develop/start.sh) + +*** + +# Usage + +## Examples + +* Start the `FullNode.jar` (`start.sh`, `config.conf` and `FullNode.jar` in the same directory.) + + ``` + sh start.sh --run + ``` + + Start the service with options. + + ``` + sh start.sh --run -j /data/FullNode.jar -c /data/config.conf -d /data/output-directory + ``` + +* Stop the `FullNode.jar` + + ``` + sh start.sh --stop + ``` + +* Get the latest version of `FullNode.jar` and start it + + ``` + sh start.sh --release --run + ``` + +* Clone the source code, compile `java-tron`, and generate `FullNode.jar` and start it + + ``` + sh start.sh -cb --run + ``` + +* Select a supported network,default network `main`, optional network `test`,`private` + ``` + sh start.sh --net test + ``` + + +## Options + +### Service operation + +* `--run` + + start the service + +* `--stop` + + stop the service + +* `-c` + + Specify the configuration file, by default it will load the `config.conf` in the same directory as `FullNode.jar` + +* `-d` + + Specify the database storage path, The default path is the same directory where `FullNode.jar` is located. + +* `-j` + + Specify the jar package, default value is the `FullNode.jar` in the current path. + +* `-mem` + + Specify the maximum memory of the `FullNode.jar` service in`MB`, jvm's startup maximum memory will be adjusted according to this parameter. + +* `--net` + Select test and private networks. + +### build project + +* `-cb` + + Clone the latest source code and compile. + +* `--release` + + Get the latest released version of the `jar` package from github. + + +### rebuild the manifest + +* `-d` + + specify the `output-directory` db directory + +* `-m` + + specify the minimum required manifest file size ，unit:M，default：0 + +* `-b` + + specify the batch manifest size,default：80000 + +* `-dr` or `--disable-rewrite-manifest` + disable rewrite manifest + +*** + +## How to use + +* Local mode + + Start the service using the local Jar package + +* Online mode + + Get the latest code or latest release from github and start the service + +### 1.local mode + +Format: + +``` +sh start.sh [-j ] [-d ] [-c ] [[--run] | [--stop]] +``` + +**start service** + +``` +sh start.sh --run +``` + +**stop service** + +``` +sh start.sh --stop +``` + +### 2.online mode + +* Get the latest release + +* Clone the source code and build + +**Get the latest release** + +Format: + +``` +sh start.sh <[--release | -cb]> <--run> [-m ] | [-b ] | [-d | [-dr | --disable-rewrite-manifes]] +``` + +Get the latest released version. + + +``` +sh start.sh --release --run +``` + +Following file structure will be generated after executing the above command and the `FullNode.jar` will be started. + +``` +├── ... +├── FullNode/ + ├── config.conf + ├── FullNode.jar + ├── start.sh +``` + +**Clone the source code and build** + +Get the latest code from master branch of https://github.com/tronprotocol/java-tron and compile. + +After using this command, the "FullNode" directory will be created, the compiled file `FullNode.jar` and the configuration file will be copied to this directory + +demo: + +``` +sh start.sh -cb --run +``` + +Following file structure will be created： + +``` +├── ... +├── java-tron + ├── actuator/ + ├── chainbase/ + ├── common/ + ├── config/ + ├── consensus/ + ├── crypto/ + ├── docker/ + ├── docs/ + ├── example/ + ├── framework/ + ├── gradle/ + ├── plugins/ + ├── protocol/ + ├── config.conf + ├── FullNode.jar + ├── start.sh + ├── README.md + ├── ... +``` + +``` +├── java-tron/ +├── FullNode/ + |── config.conf + ├── FullNode.jar + ├── start.sh +``` + +### 3. rebuild manifest tool + +This tool provides the ability to reformat the manifest based on current database, Enabled by default. + +1.Local mode: + +``` +sh start.sh --run -d /tmp/db/database -m 128 -b 64000 +``` + +2.Online mode + +``` +sh start.sh --release --run -d /tmp/db/database -m 128 -b 64000 +``` + +For more design details, please refer to: [TIP298](https://github.com/tronprotocol/tips/issues/298) | [Leveldb Startup Optimization Plugins](https://github.com/tronprotocol/documentation-en/blob/master/docs/developers/archive-manifest.md) From 960d65bf635379d24013ccb7750618b4da5c3891 Mon Sep 17 00:00:00 2001 From: GrapeS Date: Mon, 28 Sep 2026 14:59:41 +0800 Subject: [PATCH 28/32] docs: align AGENTS.md checks with CI - Move the java.lang.Math check into .github/scripts/check_math_usage.sh and run it from both math-check.yml and AGENTS.md, so the self-check also flags fully qualified calls and imports. - Document the protoLint rule that the zero value of a new enum starts with UNKNOWN_. - Use an existing test method in the single-test example and drop protocol from the Checkstyle module list. --- .github/scripts/check_math_usage.sh | 29 +++++++++++++++++++++++++++++ .github/workflows/math-check.yml | 27 +++------------------------ AGENTS.md | 19 ++++++++----------- 3 files changed, 40 insertions(+), 35 deletions(-) create mode 100755 .github/scripts/check_math_usage.sh diff --git a/.github/scripts/check_math_usage.sh b/.github/scripts/check_math_usage.sh new file mode 100755 index 00000000000..405d1d850d0 --- /dev/null +++ b/.github/scripts/check_math_usage.sh @@ -0,0 +1,29 @@ +#!/usr/bin/env bash +# Prints every Java file that uses java.lang.Math: bare `Math.` calls, fully +# qualified `java.lang.Math.` calls (including static imports) and +# `import java.lang.Math`. No output means no forbidden usage. +# StrictMathWrapper.java and MathWrapper.java are exempt. String literals, char +# literals and comments are stripped before matching, so `StrictMath.` and +# mentions in text are not reported. +# Used by .github/workflows/math-check.yml; run it locally from any directory. +set -euo pipefail + +cd "$(dirname "$0")/../.." + +find . -type f -name '*.java' -not -path '*/build/*' | while IFS= read -r file; do + case "$(basename "$file")" in + StrictMathWrapper.java|MathWrapper.java) continue ;; + esac + + perl -0777 -ne ' + s/"([^"\\]|\\.)*"//g; + s/'\''([^'\''\\]|\\.)*'\''//g; + s!/\*([^*]|\*[^/])*\*/!!g; + s!//[^\n]*!!g; + $hasMath = 0; + $hasMath = 1 if /^[\s]*import[\s]+java\.lang\.Math\b/m; + $hasMath = 1 if /\bjava\s*\.\s*lang\s*\.\s*Math\s*\./; + $hasMath = 1 if /(?> math_usage.txt - done < <(find . -type f -name "*.java") - - sort -u math_usage.txt -o math_usage.txt - + + bash .github/scripts/check_math_usage.sh > math_usage.txt + if [ -s math_usage.txt ]; then echo "❌ Error: Forbidden Math usage found in the following files:" cat math_usage.txt diff --git a/AGENTS.md b/AGENTS.md index 6f3d7e4d317..edb4213296f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -17,8 +17,8 @@ Supported platforms: **Linux** and **macOS** only. The JDK requirement is determ ./gradlew build # build with tests ./gradlew test # run all tests ./gradlew :framework:test # test one module -./gradlew :framework:test --tests "org.tron.core.db.TronDatabaseTest" # one class -./gradlew :framework:test --tests "org.tron.core.db.TronDatabaseTest.testX" # one method +./gradlew :framework:test --tests "org.tron.core.db.TronDatabaseTest" # one class +./gradlew :framework:test --tests "org.tron.core.db.TronDatabaseTest.TestGetUnchecked" # one method ./gradlew :framework:testWithRocksDb # RocksDB tests (x86 only) ./gradlew jacocoTestReport # coverage report ``` @@ -52,23 +52,19 @@ Run exactly what CI runs (`.github/workflows/pr-check.yml`): ./gradlew :framework:checkstyleMain :framework:checkstyleTest :plugins:checkstyleMain ``` -Checkstyle is configured only for `framework`, `protocol`, and `plugins`. A bare `./gradlew checkstyleMain` does not reproduce the CI gate. +Checkstyle is configured only for `framework` and `plugins`; `protocol` is checked by `protoLint` instead (see Protobuf below). A bare `./gradlew checkstyleMain` does not reproduce the CI gate. ### 4. Forbidden `Math` usage -CI (`.github/workflows/math-check.yml`) **fails the build on any use of `java.lang.Math`** anywhere in the repository. Only `StrictMathWrapper.java` and `MathWrapper.java` are exempt. +CI (`.github/workflows/math-check.yml`) **fails the build on any use of `java.lang.Math`** anywhere in the repository: bare `Math.` calls, fully qualified `java.lang.Math.` calls (including static imports), and `import java.lang.Math`. Only `StrictMathWrapper.java` and `MathWrapper.java` are exempt. -Use `org.tron.common.math.StrictMathWrapper` instead. Self-check before pushing (same matching logic as CI; `StrictMath.` and string/comment occurrences are correctly ignored): +Use `org.tron.common.math.StrictMathWrapper` instead. Self-check before pushing with the script CI runs (`StrictMath.` and occurrences in strings or comments are ignored): ```bash -find . -name '*.java' -not -path '*/build/*' | while IFS= read -r f; do - case "$(basename "$f")" in StrictMathWrapper.java|MathWrapper.java) continue;; esac - perl -0777 -ne 's/"([^"\\]|\\.)*"//g; s!/\*([^*]|\*[^/])*\*/!!g; s!//[^\n]*!!g; - print "$ARGV\n" if /(? Date: Tue, 29 Sep 2026 10:48:03 +0800 Subject: [PATCH 29/32] docs: sync protobuf protocol document with the proto files - Add the fields and enum values missing from Account, AccountResource, Transaction.Result, TransactionInfo, ResourceReceipt, InternalTransaction, SmartContract, ReasonCode and HelloMessage, with descriptions, and drop TransactionSign, which no longer exists. - Document the six Stake 2.0 contracts and the FreezeV2 / UnFreezeV2 messages. - State that the .proto files are the source of truth in the document, README, AGENTS.md and the outdated copies under protocol/src/main/protos. --- AGENTS.md | 2 +- README.md | 2 +- docs/protobuf-protocol-document.md | 254 ++++++++++++++++-- ...inese version of TRON Protocol document.md | 2 +- ...glish version of TRON Protocol document.md | 2 +- 5 files changed, 242 insertions(+), 20 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index edb4213296f..a1f12572475 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -168,7 +168,7 @@ crypto → common - **Build / run / node operation:** [README](./README.md) - **Configuration:** [`docs/configuration.md`](./docs/configuration.md), [`docs/configuration-conventions.md`](./docs/configuration-conventions.md) -- **Protobuf protocol:** [`docs/protobuf-protocol-document.md`](./docs/protobuf-protocol-document.md) is the maintained reference (the copies under `protocol/src/main/protos/` are outdated). +- **Protobuf protocol:** the `.proto` files under `protocol/src/main/protos/` are the source of truth; [`docs/protobuf-protocol-document.md`](./docs/protobuf-protocol-document.md) explains the main messages (the Markdown copies under `protocol/src/main/protos/` are outdated). - **Extending / deployment:** the [`docs/`](./docs) directory (customized actuator, modular deployment). - **Contributing:** [CONTRIBUTING.md](./CONTRIBUTING.md) (workflow, coding style, commit/PR conventions). - **Security policy:** [SECURITY.md](./SECURITY.md) (supported versions, vulnerability disclosure). diff --git a/README.md b/README.md index a9d740bf4fd..1cb46f8292c 100644 --- a/README.md +++ b/README.md @@ -209,7 +209,7 @@ More detailed guides live in the [`docs/`](./docs) directory: - **Extending java-tron** - [Implement a Customized Actuator](./docs/implement-a-customized-actuator-en.md) · [中文版](./docs/implement-a-customized-actuator-zh.md) - **Protocol** - - [TRON Protobuf Protocol Document](./docs/protobuf-protocol-document.md) — the maintained, authoritative Protobuf protocol reference + - [TRON Protobuf Protocol Document](./docs/protobuf-protocol-document.md) — guide to the main Protobuf messages; the `.proto` files under [`protocol/src/main/protos`](./protocol/src/main/protos) are the source of truth - **Observability** - [Metrics Changelog](./docs/metrics-changelog.md) — Prometheus metric additions, changes, and removals across java-tron releases diff --git a/docs/protobuf-protocol-document.md b/docs/protobuf-protocol-document.md index d8e621ed69a..5178e417857 100644 --- a/docs/protobuf-protocol-document.md +++ b/docs/protobuf-protocol-document.md @@ -4,6 +4,8 @@ This is the description of Google Protobuf implementation of Tron's protocol. +> The `.proto` files under [`protocol/src/main/protos`](../protocol/src/main/protos) are the source of truth for every message and field. This document explains the main messages. + ## Contents #### [1. Account](#account) @@ -34,7 +36,7 @@ enum AccountType { } ``` -- message `Account` has multiple attributes and 2 nested messages: +- message `Account` has multiple attributes and 4 nested messages: message `Frozen`: @@ -57,6 +59,35 @@ enum AccountType { int64 storage_limit = 6; int64 storage_usage = 7; int64 latest_exchange_storage_time = 8; + int64 energy_window_size = 9; + int64 delegated_frozenV2_balance_for_energy = 10; + int64 acquired_delegated_frozenV2_balance_for_energy = 11; + bool energy_window_optimized = 12; + } + ``` + + `energy_window_size`: the window, in blocks, over which energy usage recovers; `0` means the default of 24 hours. When `energy_window_optimized` is true, the value is stored multiplied by 1000. + + `delegated_frozenV2_balance_for_energy`: TRX staked by this account under Stake 2.0 whose energy is delegated to other accounts. + + `acquired_delegated_frozenV2_balance_for_energy`: TRX staked by other accounts under Stake 2.0 whose energy is delegated to this account. + + message `FreezeV2`: TRX staked under Stake 2.0 for one resource type. + + ```java + message FreezeV2 { + ResourceCode type = 1; + int64 amount = 2; + } + ``` + + message `UnFreezeV2`: TRX unstaked under Stake 2.0 and waiting to be withdrawn; `unfreeze_expire_time` is when it becomes withdrawable. + + ```java + message UnFreezeV2 { + ResourceCode type = 1; + int64 unfreeze_amount = 3; + int64 unfreeze_expire_time = 4; } ``` @@ -118,6 +149,22 @@ enum AccountType { `latest_consume_free_time`: the latest consume free bandwidth time of this account. + `net_window_size`: the window, in blocks, over which bandwidth usage recovers; `0` means the default of 24 hours. When `net_window_optimized` is true, the value is stored multiplied by 1000. + + `frozenV2`: TRX staked under Stake 2.0, one entry per resource type. + + `unfrozenV2`: TRX unstaked under Stake 2.0 and waiting to be withdrawn, with the time each amount becomes withdrawable. + + `delegated_frozenV2_balance_for_bandwidth`: TRX staked by this account under Stake 2.0 whose bandwidth is delegated to other accounts. + + `acquired_delegated_frozenV2_balance_for_bandwidth`: TRX staked by other accounts under Stake 2.0 whose bandwidth is delegated to this account. + + `old_tron_power`: under the new resource model (`getAllowNewResourceModel`), the voting power recorded from the account's bandwidth and energy stakes. `0` means not recorded yet, so those stakes still count in full; `-1` means they no longer count and only TRON Power stakes give voting power. + + `tron_power`: TRX frozen under Stake 1.0 for TRON Power (voting power only), available under the new resource model. + + `asset_optimized`: true when this account's TRC-10 balances are kept in a separate account-asset store instead of the `asset` / `assetV2` maps. + ```java message Account { message Frozen { @@ -135,6 +182,9 @@ message Account { int64 net_usage = 8; int64 acquired_delegated_frozen_balance_for_bandwidth = 41; int64 delegated_frozen_balance_for_bandwidth = 42; + int64 old_tron_power = 46; + Frozen tron_power = 47; + bool asset_optimized = 60; int64 create_time = 0x09; int64 latest_opration_time = 10; int64 allowance = 0x0B; @@ -153,6 +203,8 @@ message Account { int64 latest_consume_time = 21; int64 latest_consume_free_time = 22; bytes account_id = 23; + int64 net_window_size = 24; + bool net_window_optimized = 25; message AccountResource { int64 energy_usage = 1; Frozen frozen_balance_for_energy = 2; @@ -162,12 +214,29 @@ message Account { int64 storage_limit = 6; int64 storage_usage = 7; int64 latest_exchange_storage_time = 8; + int64 energy_window_size = 9; + int64 delegated_frozenV2_balance_for_energy = 10; + int64 acquired_delegated_frozenV2_balance_for_energy = 11; + bool energy_window_optimized = 12; } AccountResource account_resource = 26; bytes codeHash = 30; Permission owner_permission = 31; Permission witness_permission = 32; repeated Permission active_permission = 33; + message FreezeV2 { + ResourceCode type = 1; + int64 amount = 2; + } + message UnFreezeV2 { + ResourceCode type = 1; + int64 unfreeze_amount = 3; + int64 unfreeze_expire_time = 4; + } + repeated FreezeV2 frozenV2 = 34; + repeated UnFreezeV2 unfrozenV2 = 35; + int64 delegated_frozenV2_balance_for_bandwidth = 36; + int64 acquired_delegated_frozenV2_balance_for_bandwidth = 37; } ``` @@ -385,19 +454,6 @@ Transaction and transaction-related messages. } ``` - - message `TransactionSign` - - `transaction`: transaction data. - - `privateKey`: private key. - - ```java - message TransactionSign { - Transaction transaction = 1; - bytes privateKey = 2; - } - ``` - - message `ResourceReceipt` `energy_usage`: consume yourself account energy. @@ -414,6 +470,8 @@ Transaction and transaction-related messages. `result`: the result of executing transaction. + `energy_penalty_total`: extra energy charged by the dynamic energy model; it is included in `energy_usage_total`. + ```java message ResourceReceipt { int64 energy_usage = 1; @@ -423,6 +481,7 @@ Transaction and transaction-related messages. int64 net_usage = 5; int64 net_fee = 6; Transaction.Result.contractResult result = 7; + int64 energy_penalty_total = 8; } ``` @@ -451,6 +510,8 @@ Transaction and transaction-related messages. `callValueInfo`: Refers to asset transfer information in internal transactions, including trx and trc10. + `extra`: JSON details for some internal transactions, such as the votes cast by a contract, or the amounts staked again per resource by a contract's cancel-all-unstake call when `vm.saveCancelAllUnfreezeV2Details` is enabled. + ```java message InternalTransaction { bytes hash = 1; @@ -463,6 +524,7 @@ Transaction and transaction-related messages. repeated CallValueInfo callValueInfo = 4; bytes note = 5; bool rejected = 6; + string extra = 7; } ``` @@ -505,6 +567,14 @@ Transaction and transaction-related messages. `exchange_id`: `shielded_transaction_fee`: + + `orderId`: ID of the order created by `MarketSellAssetContract`. + + `orderDetails`: orders matched when that order was placed. + + `withdraw_expire_amount`: expired unstaked TRX withdrawn to the balance by this transaction. + + `cancel_unfreezeV2_amount`: for `CancelAllUnfreezeV2Contract`, the unstaked amounts staked again, keyed by resource type. ```java message Result { @@ -528,6 +598,7 @@ Transaction and transaction-related messages. JVM_STACK_OVER_FLOW = 12; UNKNOWN = 13; TRANSFER_FAILED = 14; + INVALID_CODE = 15; } int64 fee = 1; code ret = 2; @@ -541,6 +612,10 @@ Transaction and transaction-related messages. int64 exchange_withdraw_another_amount = 20; int64 exchange_id = 21; int64 shielded_transaction_fee = 22; + bytes orderId = 25; + repeated MarketOrderDetail orderDetails = 26; + int64 withdraw_expire_amount = 27; + map cancel_unfreezeV2_amount = 28; } ``` @@ -657,6 +732,7 @@ Transaction and transaction-related messages. JVM_STACK_OVER_FLOW = 12; UNKNOWN = 13; TRANSFER_FAILED = 14; + INVALID_CODE = 15; } int64 fee = 1; code ret = 2; @@ -670,6 +746,10 @@ Transaction and transaction-related messages. int64 exchange_withdraw_another_amount = 20; int64 exchange_id = 21; int64 shielded_transaction_fee = 22; + bytes orderId = 25; + repeated MarketOrderDetail orderDetails = 26; + int64 withdraw_expire_amount = 27; + map cancel_unfreezeV2_amount = 28; } message raw { @@ -757,6 +837,16 @@ Transaction and transaction-related messages. `shielded_transaction_fee`: the usage fee for shielded transaction. + `orderId`: ID of the order created by `MarketSellAssetContract`. + + `orderDetails`: orders matched when that order was placed. + + `packingFee`: the part of the bandwidth and energy fees paid into the transaction fee pool, from which block producers are rewarded; set only when the transaction fee pool (`getAllowTransactionFeePool`) is enabled. + + `withdraw_expire_amount`: expired unstaked TRX withdrawn to the balance by this transaction. + + `cancel_unfreezeV2_amount`: for `CancelAllUnfreezeV2Contract`, the unstaked amounts staked again, keyed by resource type. + ```java message TransactionInfo { enum code { @@ -788,6 +878,11 @@ Transaction and transaction-related messages. int64 exchange_withdraw_another_amount = 20; int64 exchange_id = 21; int64 shielded_transaction_fee = 22; + bytes orderId = 25; + repeated MarketOrderDetail orderDetails = 26; + int64 packingFee = 27; + int64 withdraw_expire_amount = 28; + map cancel_unfreezeV2_amount = 29; } ``` - message `Transactions` @@ -829,7 +924,7 @@ Transaction and transaction-related messages. Contract and contract-related messages. -- Tron has 33 types of Contracts declared within [`Transaction`](#trans). +- Tron has 41 types of Contracts declared within [`Transaction`](#trans). - message `Contract` @@ -898,7 +993,7 @@ Contract and contract-related messages. } ``` -- There are 15 types of results while deploying contracts (refer to `Transaction.Result`): +- There are 16 types of results while deploying contracts (refer to `Transaction.Result`): ```java enum contractResult { @@ -917,6 +1012,7 @@ Contract and contract-related messages. JVM_STACK_OVER_FLOW = 12; UNKNOWN = 13; TRANSFER_FAILED = 14; + INVALID_CODE = 15; } ``` @@ -1531,6 +1627,114 @@ Contract and contract-related messages. ``` attributes' type refer to [Shield Contract Related](#shieldc) + + - message `FreezeBalanceV2Contract` + + Stakes TRX under Stake 2.0 to obtain bandwidth, energy, or, under the new resource model (`getAllowNewResourceModel`), TRON Power. + + `owner_address`: address of owner. + + `frozen_balance`: amount of TRX to stake, in sun; at least 1 TRX and no more than the account balance. + + `resource`: type of resource to obtain: BANDWIDTH / ENERGY / TRON_POWER. + + ```java + message FreezeBalanceV2Contract { + bytes owner_address = 1; + int64 frozen_balance = 2; + ResourceCode resource = 3; + } + ``` + + - message `UnfreezeBalanceV2Contract` + + Unstakes TRX staked under Stake 2.0. The amount becomes withdrawable after the unstaking period (`getUnfreezeDelayDays` days), and an account can have at most 32 unstakes pending at a time. Unstaked amounts whose period has already ended are withdrawn to the balance in the same transaction. + + `owner_address`: address of owner. + + `unfreeze_balance`: amount of TRX to unstake, in sun. + + `resource`: type of resource the TRX was staked for: BANDWIDTH / ENERGY / TRON_POWER. + + ```java + message UnfreezeBalanceV2Contract { + bytes owner_address = 1; + int64 unfreeze_balance = 2; + ResourceCode resource = 3; + } + ``` + + - message `WithdrawExpireUnfreezeContract` + + Withdraws all unstaked TRX whose unstaking period has ended to the account balance. + + `owner_address`: address of owner. + + ```java + message WithdrawExpireUnfreezeContract { + bytes owner_address = 1; + } + ``` + + - message `DelegateResourceContract` + + Delegates the bandwidth or energy of TRX staked under Stake 2.0 to another account. + + `owner_address`: address of owner. + + `resource`: type of resource to delegate: BANDWIDTH / ENERGY. + + `balance`: amount of staked TRX whose resource is delegated, in sun; at least 1 TRX. + + `receiver_address`: account that receives the resource; it cannot be the owner or a contract. + + `lock`: if true, the delegation cannot be reclaimed until the lock period ends. + + `lock_period`: lock period in blocks (3 seconds each), up to `getMaxDelegateLockPeriod`; `0` means the default of 3 days. A new locked delegation of the same resource to the same receiver moves the lock end of all balance already locked for that resource and receiver to the new end time, and its lock period cannot be shorter than the time left on the current lock. + + ```java + message DelegateResourceContract { + bytes owner_address = 1; + ResourceCode resource = 2; + int64 balance = 3; + bytes receiver_address = 4; + bool lock = 5; + int64 lock_period = 6; + } + ``` + + - message `UnDelegateResourceContract` + + Reclaims resource delegated with `DelegateResourceContract`. Locked delegations can be reclaimed only after their lock period ends. + + `owner_address`: address of owner. + + `resource`: type of resource to reclaim: BANDWIDTH / ENERGY. + + `balance`: amount of delegated staked TRX to reclaim, in sun. + + `receiver_address`: account the resource was delegated to. + + ```java + message UnDelegateResourceContract { + bytes owner_address = 1; + ResourceCode resource = 2; + int64 balance = 3; + bytes receiver_address = 4; + } + ``` + + - message `CancelAllUnfreezeV2Contract` + + Cancels all pending Stake 2.0 unstakes: amounts still in the unstaking period are staked again, and amounts whose period has ended are withdrawn to the balance. + + `owner_address`: address of owner. + + ```java + message CancelAllUnfreezeV2Contract { + bytes owner_address = 1; + } + ``` @@ -1554,6 +1758,7 @@ message `SmartContract` has multiple attributes and nested message `ABI` Event = 3; Fallback = 4; Receive = 5; + Error = 6; } ``` @@ -1623,6 +1828,8 @@ message `SmartContract` has multiple attributes and nested message `ABI` `code_hash`: hash of smart contract bytecode. `trx_hash`: transactionId of Deploying contract transaction. + + `version`: contract version; `1` for contracts created while EVM compatibility (`getAllowTvmCompatibleEvm`) is enabled, otherwise `0`. ```java message SmartContract { @@ -1635,6 +1842,7 @@ message `SmartContract` has multiple attributes and nested message `ABI` Event = 3; Fallback = 4; Receive = 5; + Error = 6; } message Param { bool indexed = 1; @@ -1670,6 +1878,7 @@ message `SmartContract` has multiple attributes and nested message `ABI` int64 origin_energy_limit = 8; bytes code_hash = 9; bytes trx_hash = 10; + int32 version = 11; } ``` @@ -2053,6 +2262,10 @@ message `SmartContract` has multiple attributes and nested message `ABI` TIME_OUT = 0x20; CONNECT_FAIL = 0x21; TOO_MANY_PEERS_WITH_SAME_IP = 0x22; + LIGHT_NODE_SYNC_FAIL = 0x23; + BELOW_THAN_ME = 0x24; + NOT_WITNESS = 0x25; + NO_SUCH_MESSAGE = 0x26; UNKNOWN = 0xFF; } ``` @@ -2100,6 +2313,12 @@ message `SmartContract` has multiple attributes and nested message `ABI` `signature`: signature for sender. + `nodeType`: node type, `0` for a full node and `1` for a lite fullnode. + + `lowestBlockNum`: lowest block number stored by a lite fullnode; `0` for a full node. + + `codeVersion`: java-tron version of the sender. + ```java message DisconnectMessage { ReasonCode reason = 1; @@ -2119,6 +2338,9 @@ message `SmartContract` has multiple attributes and nested message `ABI` BlockId headBlockId = 6; bytes address = 7; bytes signature = 8; + int32 nodeType = 9; + int64 lowestBlockNum = 10; + bytes codeVersion = 11; } ``` 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 index a2c6f6bddb1..330c1af0b2f 100644 --- a/protocol/src/main/protos/Chinese version of TRON Protocol document.md +++ b/protocol/src/main/protos/Chinese version of TRON Protocol document.md @@ -1,4 +1,4 @@ -> ⚠️ **本副本已过时（最后更新于 2022 年）。** 维护中的权威协议文档是 [`docs/protobuf-protocol-document.md`](../../../../docs/protobuf-protocol-document.md)，请以该文件为准；此副本仅作历史参考保留。 +> ⚠️ **本副本已过时（最后更新于 2022 年）。** 当前的协议说明见 [`docs/protobuf-protocol-document.md`](../../../../docs/protobuf-protocol-document.md)，字段定义以本目录下的 `.proto` 文件为准；此副本仅作历史参考保留。 # TRON protobuf protocol diff --git a/protocol/src/main/protos/English version of TRON Protocol document.md b/protocol/src/main/protos/English version of TRON Protocol document.md index 8d176492859..757512ef519 100644 --- a/protocol/src/main/protos/English version of TRON Protocol document.md +++ b/protocol/src/main/protos/English version of TRON Protocol document.md @@ -1,5 +1,5 @@ -> ⚠️ **This copy is outdated (last updated 2022).** The maintained, authoritative protocol document is [`docs/protobuf-protocol-document.md`](../../../../docs/protobuf-protocol-document.md) — please refer to that file. This copy is kept only for historical reference. +> ⚠️ **This copy is outdated (last updated 2022).** See [`docs/protobuf-protocol-document.md`](../../../../docs/protobuf-protocol-document.md) for the current guide; the `.proto` files in this directory are the source of truth. This copy is kept only for historical reference. # Protobuf protocol From 0db602d481438eb7bead7c47125e7745ff73980d Mon Sep 17 00:00:00 2001 From: GrapeS Date: Tue, 29 Sep 2026 18:46:06 +0800 Subject: [PATCH 30/32] add libp2p related in doc --- AGENTS.md | 6 +++++- README.md | 1 + docs/modular-introduction-en.md | 6 +++++- docs/modular-introduction-zh.md | 6 +++++- 4 files changed, 16 insertions(+), 3 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index a1f12572475..a8f473c197b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -52,7 +52,7 @@ Run exactly what CI runs (`.github/workflows/pr-check.yml`): ./gradlew :framework:checkstyleMain :framework:checkstyleTest :plugins:checkstyleMain ``` -Checkstyle is configured only for `framework` and `plugins`; `protocol` is checked by `protoLint` instead (see Protobuf below). A bare `./gradlew checkstyleMain` does not reproduce the CI gate. +CI runs Checkstyle only for `framework` and `plugins`; `protocol` is checked by `protoLint` instead (see Protobuf below). `p2p` has its own Checkstyle configuration (`./gradlew :p2p:checkstyleMain :p2p:checkstyleTest`) that is not part of the CI gate. A bare `./gradlew checkstyleMain` does not reproduce the CI gate. ### 4. Forbidden `Math` usage @@ -110,6 +110,7 @@ No `*.jar`, `build/`, logs, or database files — whether produced by the main b | `actuator` | Transaction execution; one Actuator class per transaction type | | `crypto` | Cryptographic primitives (depends only on `common`) | | `common` | Shared utilities | +| `p2p` | Peer discovery, connection management and DNS-based node lists; vendored from [tronprotocol/libp2p](https://github.com/tronprotocol/libp2p) v2.2.9 (see [`p2p/README.md`](./p2p/README.md)) | | `platform` | Architecture-specific implementations selected at build time (separate `x86` / `arm` / `common` source sets): math wrappers, LevelDB/RocksDB order-price comparators — relevant to cross-JVM determinism | | `plugins` | Standalone tools (`Toolkit.jar`, `ArchiveManifest.jar`) | @@ -126,6 +127,8 @@ crypto → common `platform` is a leaf module (no project dependencies of its own) that `common`, `framework`, and `plugins` depend on for architecture-specific code. +`p2p` is also a leaf module. + ## Hard Constraints **Cross-JVM determinism** (consensus, state transition, block ordering) — the same block must produce the same state on every supported platform: @@ -170,6 +173,7 @@ crypto → common - **Configuration:** [`docs/configuration.md`](./docs/configuration.md), [`docs/configuration-conventions.md`](./docs/configuration-conventions.md) - **Protobuf protocol:** the `.proto` files under `protocol/src/main/protos/` are the source of truth; [`docs/protobuf-protocol-document.md`](./docs/protobuf-protocol-document.md) explains the main messages (the Markdown copies under `protocol/src/main/protos/` are outdated). - **Extending / deployment:** the [`docs/`](./docs) directory (customized actuator, modular deployment). +- **P2P module:** [`p2p/README.md`](./p2p/README.md) (standalone use, DNS node-list publishing, API). - **Contributing:** [CONTRIBUTING.md](./CONTRIBUTING.md) (workflow, coding style, commit/PR conventions). - **Security policy:** [SECURITY.md](./SECURITY.md) (supported versions, vulnerability disclosure). diff --git a/README.md b/README.md index 1cb46f8292c..44338f1729b 100644 --- a/README.md +++ b/README.md @@ -206,6 +206,7 @@ More detailed guides live in the [`docs/`](./docs) directory: - **Modular architecture & deployment** - [Modular Introduction](./docs/modular-introduction-en.md) · [中文版](./docs/modular-introduction-zh.md) - [Modular Deployment](./docs/modular-deployment-en.md) · [中文版](./docs/modular-deployment-zh.md) + - [P2P Module](./p2p/README.md) — peer discovery, connection management and DNS-based node lists - **Extending java-tron** - [Implement a Customized Actuator](./docs/implement-a-customized-actuator-en.md) · [中文版](./docs/implement-a-customized-actuator-zh.md) - **Protocol** diff --git a/docs/modular-introduction-en.md b/docs/modular-introduction-en.md index 654fbfcf995..f662801fefb 100644 --- a/docs/modular-introduction-en.md +++ b/docs/modular-introduction-en.md @@ -16,7 +16,7 @@ The aim of java-tron modularization is to enable developers to easily build a de ![modular-structure](https://github.com/tronprotocol/java-tron/blob/develop/docs/images/module.png) -A modularized java-tron consists of nine modules: framework, protocol, common, chainbase, consensus, actuator, crypto, plugins and platform. The function of each module is elaborated below. +A modularized java-tron consists of ten modules: framework, protocol, common, p2p, chainbase, consensus, actuator, crypto, plugins and platform. The function of each module is elaborated below. ### framework @@ -33,6 +33,10 @@ A concise and efficient data transfer protocol is essential to a distributed net Common module encapsulates common components and tools for other modules to access. +### p2p + +The p2p module handles peer discovery, connection management and DNS-based node lists: nodes discover each other over UDP and connect over TCP, and a node list can be published as DNS TXT records (Amazon Route 53 or Aliyun DNS) that other nodes fetch through a `tree://{pubkey}@{domain}` URL. The module is vendored from [tronprotocol/libp2p](https://github.com/tronprotocol/libp2p) v2.2.9, depends on no other module of the project, and is exposed to the rest of java-tron by `common`. See [p2p/README.md](../p2p/README.md) for standalone use and the API. + ### chainbase Chainbase is a database module. For probabilistic consensus algorithms such as PoW, PoS and DPoS, situations of switching to a new chain, however unlikely, is inevitable. Because of this, chainbase defines an interface standard supporting databases that can roll back. This interface requires databases to have a state rollback mechanism, a checkpoint-based fault tolerant mechanism and so on. diff --git a/docs/modular-introduction-zh.md b/docs/modular-introduction-zh.md index e1a02f6b778..2ceed12c4fc 100644 --- a/docs/modular-introduction-zh.md +++ b/docs/modular-introduction-zh.md @@ -14,7 +14,7 @@ java-tron 模块化的目的是为了帮助开发者方便地构建出特定应 ![modular-structure](https://github.com/tronprotocol/java-tron/blob/develop/docs/images/module.png) -模块化后的 java-tron 目前分为9个模块：framework、protocol、common、chainbase、consensus、actuator、crypto、plugins、platform，下面分别简单介绍一下各个模块的作用。 +模块化后的 java-tron 目前分为10个模块：framework、protocol、common、p2p、chainbase、consensus、actuator、crypto、plugins、platform，下面分别简单介绍一下各个模块的作用。 ### framework @@ -30,6 +30,10 @@ framework 是 java-tron 的核心模块，不仅是整个链的入口模块， common 模块对公共组件和一些工具类进行了封装，以方便其他模块调用。 +### p2p + +p2p 模块负责节点发现、连接管理和基于 DNS 的节点列表：节点之间通过 UDP 相互发现、通过 TCP 建立连接；节点列表还可以发布为 DNS TXT 记录（支持 Amazon Route 53 和阿里云 DNS），其他节点通过 `tree://{pubkey}@{domain}` 形式的地址获取。该模块内置自 [tronprotocol/libp2p](https://github.com/tronprotocol/libp2p) v2.2.9，不依赖项目中的其他模块，由 `common` 对外暴露。单独运行方式和接口说明见 [p2p/README.md](../p2p/README.md)。 + ### chainbase chainbase 模块是数据库层面的抽象，像 PoW、PoS、DPoS 这类基于概率性的共识算法不可避免的会以一定的概率发生切链，因此 chainbase 定义了一个支持可回退数据库的接口标准，该接口要求数据库实现状态回滚机制、checkpoint容灾机制等。 From 57c356c1db41bdb228c385ec9865ad4efb6a4fe9 Mon Sep 17 00:00:00 2001 From: GrapeS Date: Tue, 29 Sep 2026 18:58:35 +0800 Subject: [PATCH 31/32] docs: add p2p-standalone.jar to README and trim p2p details - README: list p2p-standalone.jar in the executables table. - AGENTS.md and the modular introduction (en/zh): drop the libp2p version, the DNS providers, the tree:// URL format and how common exposes the module, since those can change. --- AGENTS.md | 2 +- README.md | 1 + docs/modular-introduction-en.md | 2 +- docs/modular-introduction-zh.md | 2 +- 4 files changed, 4 insertions(+), 3 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index a8f473c197b..3d10490a36a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -110,7 +110,7 @@ No `*.jar`, `build/`, logs, or database files — whether produced by the main b | `actuator` | Transaction execution; one Actuator class per transaction type | | `crypto` | Cryptographic primitives (depends only on `common`) | | `common` | Shared utilities | -| `p2p` | Peer discovery, connection management and DNS-based node lists; vendored from [tronprotocol/libp2p](https://github.com/tronprotocol/libp2p) v2.2.9 (see [`p2p/README.md`](./p2p/README.md)) | +| `p2p` | Peer discovery, connection management and DNS-based node lists; vendored from [tronprotocol/libp2p](https://github.com/tronprotocol/libp2p) (see [`p2p/README.md`](./p2p/README.md)) | | `platform` | Architecture-specific implementations selected at build time (separate `x86` / `arm` / `common` source sets): math wrappers, LevelDB/RocksDB order-price comparators — relevant to cross-JVM determinism | | `plugins` | Standalone tools (`Toolkit.jar`, `ArchiveManifest.jar`) | diff --git a/README.md b/README.md index 44338f1729b..eefc1d4bde0 100644 --- a/README.md +++ b/README.md @@ -81,6 +81,7 @@ The java-tron project comes with several runnable artifacts and helper scripts f | :---------------------- | :---------- | | **`FullNode.jar`** | Main TRON node executable (generated in `build/libs/` after a successful build following the above guidance). Runs as a full node by default. `java -jar FullNode.jar --help` for command line options| | **`Toolkit.jar`** | Node management utility (generated in `build/libs/`): partition, prune, copy, convert DBs; shadow-fork tool. [Usage](https://tronprotocol.github.io/documentation-en/using_javatron/toolkit/#toolkit-a-java-tron-node-maintenance-suite) | +| **`p2p-standalone.jar`** | Runs the p2p module without a full node (generated in `p2p/build/libs/`): peer discovery tests, DNS node-list publishing. `java -jar p2p-standalone.jar --help` for options; see the [p2p guide](./p2p/README.md). | | **`start.sh`** | Quick start script (x86_64, JDK 8) to download/build/run `FullNode.jar`. See the tool [guide](./shell.md). | | **`start.sh.simple`** | Quick start script template (ARM64, JDK 17). See usage notes inside the script. | diff --git a/docs/modular-introduction-en.md b/docs/modular-introduction-en.md index f662801fefb..d35d4269995 100644 --- a/docs/modular-introduction-en.md +++ b/docs/modular-introduction-en.md @@ -35,7 +35,7 @@ Common module encapsulates common components and tools for other modules to acce ### p2p -The p2p module handles peer discovery, connection management and DNS-based node lists: nodes discover each other over UDP and connect over TCP, and a node list can be published as DNS TXT records (Amazon Route 53 or Aliyun DNS) that other nodes fetch through a `tree://{pubkey}@{domain}` URL. The module is vendored from [tronprotocol/libp2p](https://github.com/tronprotocol/libp2p) v2.2.9, depends on no other module of the project, and is exposed to the rest of java-tron by `common`. See [p2p/README.md](../p2p/README.md) for standalone use and the API. +The p2p module handles peer discovery, connection management and DNS-based node lists: nodes discover each other over UDP and connect over TCP, and a node list can be published as DNS TXT records for other nodes to fetch. The module is vendored from [tronprotocol/libp2p](https://github.com/tronprotocol/libp2p) and depends on no other module of the project. See [p2p/README.md](../p2p/README.md) for standalone use and the API. ### chainbase diff --git a/docs/modular-introduction-zh.md b/docs/modular-introduction-zh.md index 2ceed12c4fc..711794d24f3 100644 --- a/docs/modular-introduction-zh.md +++ b/docs/modular-introduction-zh.md @@ -32,7 +32,7 @@ common 模块对公共组件和一些工具类进行了封装，以方便其他 ### p2p -p2p 模块负责节点发现、连接管理和基于 DNS 的节点列表：节点之间通过 UDP 相互发现、通过 TCP 建立连接；节点列表还可以发布为 DNS TXT 记录（支持 Amazon Route 53 和阿里云 DNS），其他节点通过 `tree://{pubkey}@{domain}` 形式的地址获取。该模块内置自 [tronprotocol/libp2p](https://github.com/tronprotocol/libp2p) v2.2.9，不依赖项目中的其他模块，由 `common` 对外暴露。单独运行方式和接口说明见 [p2p/README.md](../p2p/README.md)。 +p2p 模块负责节点发现、连接管理和基于 DNS 的节点列表：节点之间通过 UDP 相互发现、通过 TCP 建立连接；节点列表还可以发布为 DNS TXT 记录，供其他节点获取。该模块内置自 [tronprotocol/libp2p](https://github.com/tronprotocol/libp2p)，不依赖项目中的其他模块。单独运行方式和接口说明见 [p2p/README.md](../p2p/README.md)。 ### chainbase From 3303a354c29cd46f25938dcf212b0cd23a27bb8a Mon Sep 17 00:00:00 2001 From: GrapeS Date: Tue, 29 Sep 2026 19:14:32 +0800 Subject: [PATCH 32/32] docs: reword the p2p-standalone.jar entry in README --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index eefc1d4bde0..721468efdd3 100644 --- a/README.md +++ b/README.md @@ -81,7 +81,7 @@ The java-tron project comes with several runnable artifacts and helper scripts f | :---------------------- | :---------- | | **`FullNode.jar`** | Main TRON node executable (generated in `build/libs/` after a successful build following the above guidance). Runs as a full node by default. `java -jar FullNode.jar --help` for command line options| | **`Toolkit.jar`** | Node management utility (generated in `build/libs/`): partition, prune, copy, convert DBs; shadow-fork tool. [Usage](https://tronprotocol.github.io/documentation-en/using_javatron/toolkit/#toolkit-a-java-tron-node-maintenance-suite) | -| **`p2p-standalone.jar`** | Runs the p2p module without a full node (generated in `p2p/build/libs/`): peer discovery tests, DNS node-list publishing. `java -jar p2p-standalone.jar --help` for options; see the [p2p guide](./p2p/README.md). | +| **`p2p-standalone.jar`** | Peer discovery, connection management and DNS-based node lists (generated in `build/libs/`). See the [p2p guide](./p2p/README.md). | | **`start.sh`** | Quick start script (x86_64, JDK 8) to download/build/run `FullNode.jar`. See the tool [guide](./shell.md). | | **`start.sh.simple`** | Quick start script template (ARM64, JDK 17). See usage notes inside the script. |