docs: add AGENTS.md and reorganize project documentation

AGENTS.md

@@ -0,0 +1,102 @@
+# 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 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
+./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 (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.
+
+**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 |
+| `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:**
+
+```text
+framework → chainbase → common → protocol
+actuator  → chainbase
+consensus → chainbase / common   (only via ConsensusDelegate; never call Manager directly)
+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):
+- 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<T>` 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`.

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.

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,23 @@ 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
+- **Observability**
+  - [Metrics Changelog](./docs/metrics-changelog.md) — Prometheus metric additions, changes, and removals across java-tron releases
+
 # 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.

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 <key-or-keystore-file>`.
+> - **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

METRICS_CHANGELOG.md → 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
 

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"
 }
 

gradle/verification-metadata.xml

@@ -2567,37 +2567,6 @@
             <sha256 value="bb388d37fbcdd3cde64c3cede21838693218dc451f04040c5df360a78ed7e812" origin="Generated by Gradle"/>
          </artifact>
       </component>
-      <component group="org.sonarqube" name="org.sonarqube.gradle.plugin" version="2.6">
-         <artifact name="org.sonarqube.gradle.plugin-2.6.pom">
-            <sha256 value="df7f5a31a8fd8f0b5521242cdda42cad48970e39016e2c397b3d68bbb57c4197" origin="Generated by Gradle"/>
-         </artifact>
-      </component>
-      <component group="org.sonarsource.parent" name="parent" version="40">
-         <artifact name="parent-40.pom">
-            <sha256 value="896728b6f49906d7516f182a170197963fe90dce88f14f50b585ac153427ffc2" origin="Generated by Gradle"/>
-         </artifact>
-      </component>
-      <component group="org.sonarsource.scanner.api" name="sonar-scanner-api" version="2.9.0.887">
-         <artifact name="sonar-scanner-api-2.9.0.887.jar">
-            <sha256 value="12ba0b2d9fc5b5b896b3b16c96c3c46728094d83da5ea0a6289e21ac9c39f88a" origin="Generated by Gradle"/>
-         </artifact>
-         <artifact name="sonar-scanner-api-2.9.0.887.pom">
-            <sha256 value="d80d568bb60b53d5c748c0f07649608bbb3c0880939f911af6477bd0dc132915" origin="Generated by Gradle"/>
-         </artifact>
-      </component>
-      <component group="org.sonarsource.scanner.api" name="sonar-scanner-api-parent" version="2.9.0.887">
-         <artifact name="sonar-scanner-api-parent-2.9.0.887.pom">
-            <sha256 value="803f182f822f359678cd1a108fc44cda785859d5555582cf3fe40574a3141943" origin="Generated by Gradle"/>
-         </artifact>
-      </component>
-      <component group="org.sonarsource.scanner.gradle" name="sonarqube-gradle-plugin" version="2.6">
-         <artifact name="sonarqube-gradle-plugin-2.6.jar">
-            <sha256 value="3d3b67291ecedfcb84697aa7ee4e893fd5498190ec2d9c340dab7061b70317e3" origin="Generated by Gradle"/>
-         </artifact>
-         <artifact name="sonarqube-gradle-plugin-2.6.pom">
-            <sha256 value="7e733b80012fed1f7a830a80b56ff76cfd3ac9b1cd4cfa9e0833727663bf2f4f" origin="Generated by Gradle"/>
-         </artifact>
-      </component>
       <component group="org.sonatype.oss" name="oss-parent" version="7">
          <artifact name="oss-parent-7.pom">
             <sha256 value="b51f8867c92b6a722499557fc3a1fdea77bdf9ef574722fe90ce436a29559454" origin="Generated by Gradle"/>

plugins/build.gradle

@@ -1,7 +1,3 @@
-plugins {
-    id "org.sonarqube" version "2.6"
-}
-
 apply plugin: 'application'
 apply plugin: 'checkstyle'
 

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协议，协议内容涉及到账户，区块，传输多个层面。

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.