docs: add AGENTS.md and reorganize project documentation

.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 /(?<![\w\.])(?<!Strict)Math\s*\./;
+    print "$ARGV\n" if $hasMath;
+  ' "$file"
+done | sort -u

.github/workflows/math-check.yml

@@ -19,30 +19,9 @@ jobs:
         shell: bash
         run: |
           echo "Checking for java.lang.Math usage..."
-
-          touch math_usage.txt
-
-          while IFS= read -r file; do
-            filename=$(basename "$file")
-            if [[ "$filename" == "StrictMathWrapper.java" || "$filename" == "MathWrapper.java" ]]; then
-              continue
-            fi
-
-            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 /(?<![\w\.])(?<!Strict)Math\s*\./;
-              print "$ARGV\n" if $hasMath;
-            ' "$file" >> 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

AGENTS.md

@@ -0,0 +1,184 @@
+# AGENTS.md
+
+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).
+
+## Guidelines
+
+- **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. 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
+./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.TestGetUnchecked"  # one method
+./gradlew :framework:testWithRocksDb         # RocksDB tests (x86 only)
+./gradlew jacocoTestReport                   # coverage report
+```
+
+- Main entry point: `org.tron.program.FullNode`.
+- 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.
+
+## 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
+```
+
+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
+
+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 with the script CI runs (`StrictMath.` and occurrences in strings or comments are ignored):
+
+```bash
+bash .github/scripts/check_math_usage.sh
+```
+
+No output means the gate passes.
+
+This exists because `java.lang.Math` gives platform-dependent results for floating-point operations, which breaks cross-JVM determinism between the x86/JDK 8 and ARM64/JDK 17 builds.
+
+### 5. Config validation — only if you touched `reference.conf`
+
+```bash
+pip install -r .github/scripts/requirements.txt          # pyhocon, required by the first script
+python3 .github/scripts/check_reference_conf.py     common/src/main/resources/reference.conf
+python3 .github/scripts/check_reference_comments.py common/src/main/resources/reference.conf
+```
+
+Both gates run in CI. The rules:
+
+- Every key path segment must match `^[a-z][a-zA-Z0-9]*$` (only the first character is constrained; acronyms such as `httpPBFTEnable` are fine). This is what `ConfigBeanFactory` bean-binding requires.
+- Total path depth ≤ **5**; each list/array step counts as one level.
+- Service-binding port values (leaf named `port` or ending in `Port`, outside arrays) must be unique; `0` and `-1` are reserved sentinels.
+- **Every key needs a comment** — inline on the same line, or on the immediately preceding line. Blank lines do not count.
+
+See [`docs/configuration-conventions.md`](./docs/configuration-conventions.md).
+
+### 6. Dependency verification — only if you touched dependencies
+
+`gradle/verification-metadata.xml` pins checksums for every resolved artifact (`verify-metadata=true`). Adding, removing, or upgrading any dependency requires regenerating it, or the build fails for everyone:
+
+```bash
+./gradlew --write-verification-metadata sha256 help
+```
+
+Review the resulting diff — it must contain only the artifacts your change actually introduces.
+
+### 7. Do not commit binaries
+
+No `*.jar`, `build/`, logs, or database files — whether produced by the main build or as byproducts of investigation.
+
+## 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 |
+| `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`) |
+
+`errorprone` and `example:actuator-example` are build-support and sample modules, not part of the node.
+
+**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.
+
+`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:
+- 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()`.
+- 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 revocable session — `try (ISession session = revokingStore.buildSession())` — never a bare `put()`.
+- A new store must extend `TronStoreWithRevoking<T>` and register with the `RevokingDatabase`.
+- Multi-store updates must roll back fully on exception.
+
+**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.
+- `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:**
+- Fields may only be added — never removed or renumbered.
+- Message field numbers start at `1`; the first enum value must be `0`.
+- In a new enum, the zero value's name must start with `UNKNOWN_` (e.g. `UNKNOWN_STATUS = 0;`, not `SUCCESS = 0;`). `protocol/protoLint.gradle` enforces this during `./gradlew build`; only the existing enums in its `legacyEnums` whitelist are exempt.
+
+**API / Threads:**
+- New HTTP servlets must go through `HttpApiAccessFilter` and use `Wallet` (never inject `Manager` directly).
+- 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
+
+1. **ErrorProne only runs on JDK 11+.** Building on x86/JDK 8 will *not* surface `StringCaseLocaleUsage` violations, but the aarch64/JDK 17 CI jobs will fail. If you only build on x86, you will not see these locally.
+2. **`./gradlew checkstyleMain` is not the CI gate.** Use the exact module-scoped command in checklist step 3.
+3. **Adding a config key without a comment fails CI**, even if the key itself is valid.
+4. **Changing a dependency without regenerating `verification-metadata.xml` breaks the build for everyone**, not just you.
+5. **Generated protobuf sources are git-ignored.** If a build error references a missing generated class, rebuild instead of creating the file.
+6. **Consensus-affecting behaviour changes need a proposal / fork gate**, not just a code change. Changing how an existing transaction validates or executes will fork the network unless gated. When in doubt, ask before implementing.
+
+## 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:** 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).
+
+## Commit & PR Convention
+
+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.
+
+PR titles and descriptions are validated in CI by `.github/workflows/pr-check.yml`. 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)
@@ -80,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`** | 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. |
 
@@ -195,6 +197,24 @@ 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)
+  - [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**
+  - [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
+
 # 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

@@ -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 <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