From 773ab21125085e404b27f8cf0ff08c1fe3a4944f Mon Sep 17 00:00:00 2001 From: GrapeS Date: Fri, 3 Jul 2026 16:26:15 +0800 Subject: [PATCH 01/12] 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 be84b44150b..ea137818235 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) @@ -188,6 +189,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 1a3bafc89c9257b878f2b3eed691008212dcb38d Mon Sep 17 00:00:00 2001 From: GrapeS Date: Fri, 3 Jul 2026 16:26:15 +0800 Subject: [PATCH 02/12] 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 28b53b1970c..b6356f1d676 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -161,6 +161,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 cbf9eaea4b5b57a89968dad91776280076e6a59a Mon Sep 17 00:00:00 2001 From: GrapeS Date: Fri, 3 Jul 2026 15:16:19 +0800 Subject: [PATCH 03/12] 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 0ca274043dac4219e3b944a5a8a30f6d9d650806 Mon Sep 17 00:00:00 2001 From: GrapeS Date: Mon, 13 Jul 2026 11:23:50 +0800 Subject: [PATCH 04/12] 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 ea137818235..71923af079a 100644 --- a/README.md +++ b/README.md @@ -203,6 +203,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 c0208302dc3ba3f9f88e6fa0625d30f66ceb9be3 Mon Sep 17 00:00:00 2001 From: GrapeS Date: Fri, 3 Jul 2026 16:26:15 +0800 Subject: [PATCH 05/12] 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 f2fb42688188b2d804f891983248001c4711f811 Mon Sep 17 00:00:00 2001 From: GrapeS Date: Mon, 13 Jul 2026 11:55:58 +0800 Subject: [PATCH 06/12] 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 acac4d553e44d4713dfba854a5fcb2c06ca4e862 Mon Sep 17 00:00:00 2001 From: GrapeS Date: Mon, 13 Jul 2026 15:30:46 +0800 Subject: [PATCH 07/12] 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 f966422ddc9d556d43875df5d16bf58eedc3eb1e Mon Sep 17 00:00:00 2001 From: GrapeS Date: Tue, 14 Jul 2026 10:00:33 +0800 Subject: [PATCH 08/12] modify chinese --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 71923af079a..d0176b39e36 100644 --- a/README.md +++ b/README.md @@ -197,10 +197,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 8ead2053ac66d97934928e1546ca50982d1c04b1 Mon Sep 17 00:00:00 2001 From: GrapeS Date: Tue, 14 Jul 2026 13:57:52 +0800 Subject: [PATCH 09/12] 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 d0176b39e36..6ff1f943a1f 100644 --- a/README.md +++ b/README.md @@ -204,7 +204,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 0ce33f253cf..3309e6d383b 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 565ae0fe64a9ae7d3ae9fc0fe23c326a15495c35 Mon Sep 17 00:00:00 2001 From: GrapeS Date: Tue, 14 Jul 2026 16:22:26 +0800 Subject: [PATCH 10/12] 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 832d2728f0b..8d1d59ed6bb 100644 --- a/gradle/verification-metadata.xml +++ b/gradle/verification-metadata.xml @@ -2567,37 +2567,6 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - From 84c44b6614029919636d7ec3297db482e8e2551f Mon Sep 17 00:00:00 2001 From: GrapeS Date: Fri, 3 Jul 2026 16:26:15 +0800 Subject: [PATCH 11/12] 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 0ca52e5b4aa1273d300fdc4b734d1c2e5f82e087 Mon Sep 17 00:00:00 2001 From: GrapeS Date: Mon, 20 Jul 2026 11:09:23 +0800 Subject: [PATCH 12/12] 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):