update configuration documents

Author: 317787106

common/src/main/resources/reference.conf

@@ -434,9 +434,18 @@ node {
 
 ## Rate limiter config
 rate.limiter = {
-  # Strategies: GlobalPreemptibleAdapter, QpsRateLimiterAdapter, IPQPSRateLimiterAdapter
-  # Default: QpsRateLimiterAdapter with qps=1000
-
+  # Each HTTP servlet and gRPC method can have its own rate-limit strategy.
+  # Three blocking strategies are available:
+  #   GlobalPreemptibleAdapter – limits maximum concurrent requests globally.
+  #                              paramString = "permit=N" (N = max concurrent calls)
+  #   QpsRateLimiterAdapter    – limits average QPS across all callers.
+  #                              paramString = "qps=N" (N may be a decimal)
+  #   IPQPSRateLimiterAdapter  – limits average QPS per source IP.
+  #                              paramString = "qps=N" (N may be a decimal)
+  # If no strategy is configured for an endpoint, QpsRateLimiterAdapter with
+  # qps=1000 is applied automatically.
+
+  # Per-servlet HTTP rate limits. component is the servlet class simple name.
   http = [
     # {
     #   component = "GetNowBlockServlet",
@@ -455,6 +464,7 @@ rate.limiter = {
     # }
   ]
 
+  # Per-method gRPC rate limits. component is "package.ServiceName/MethodName".
   rpc = [
     # {
     #   component = "protocol.Wallet/GetBlockByLatestNum2",
@@ -474,14 +484,20 @@ rate.limiter = {
   ]
 
   p2p = {
-    syncBlockChain = 3.0
-    fetchInvData = 3.0
-    disconnect = 1.0
+    # QPS ceiling for individual P2P message types received from peers.
+    # Values are doubles; fractional QPS is allowed (e.g. 0.5 = one per 2 s).
+    syncBlockChain = 3.0  # SyncBlockChain handshake messages
+    fetchInvData = 3.0    # FetchInvData (block/tx fetch) messages
+    disconnect = 1.0      # Disconnect messages
   }
 
+  # Node-wide QPS ceiling across all HTTP + gRPC requests combined.
   global.qps = 50000
+  # Per-source-IP QPS ceiling across all HTTP + gRPC requests from that IP.
   global.ip.qps = 10000
+  # Default per-endpoint QPS limit applied to any endpoint with no explicit strategy.
   global.api.qps = 1000
+  # true = reject over-limit requests immediately; false = queue and block the caller.
   apiNonBlocking = false
 }
 
@@ -522,7 +538,21 @@ seed.node = {
   ]
 }
 
+## Genesis block config
+# WARNING: All nodes in the same network must have identical genesis.block settings.
+# Any change here produces a different genesis block hash and creates an incompatible chain.
 genesis.block = {
+  # Pre-allocated accounts created at block 0, before any transactions are processed.
+  # Fields:
+  #   accountName – human-readable label stored on-chain; must not be blank
+  #   accountType – one of: Normal, AssetIssue, Contract
+  #   address     – Base58Check-encoded account address (T...)
+  #   balance     – initial balance in SUN (1 TRX = 1,000,000 SUN); stored as String
+  #                 to accommodate values that exceed Integer range
+  # Mainnet special accounts:
+  #   Zion      – holds the initial circulating supply (99,000,000,000 TRX = 99×10¹⁵ SUN)
+  #   Sun       – the founding account; starts at 0
+  #   Blackhole – receives burned TRX; initialized to Long.MIN_VALUE so it can only increase
   assets = [
     {
       accountName = "Zion"
@@ -544,6 +574,12 @@ genesis.block = {
     }
   ]
 
+  # Initial Super Representatives at block 0.
+  # Fields:
+  #   address   – Base58Check-encoded SR address (T...)
+  #   url       – SR's public URL (informational only, stored on-chain)
+  #   voteCount – initial vote count; seeds SR ranking before any user votes are cast
+  # The 27 witnesses with the highest voteCount produce the first round of blocks.
   witnesses = [
     {
       address: THKJYuUmMKKARNf7s2VT51g5uPY6KEqnat,
@@ -682,8 +718,13 @@ genesis.block = {
     }
   ]
 
+  # Genesis block timestamp in milliseconds since Unix epoch. Must be >= 0.
+  # Stored as a numeric String to accommodate Long-range values.
   timestamp = "0"
 
+  # Hash of the genesis block's conceptual parent. This is a fixed sentinel value
+  # embedded in the genesis block header; changing it changes the genesis block hash
+  # and therefore the chain identity.
   parentHash = "0xe58f33f9baf9305dc6f82b9f1934ea8f0ade2defb951258d50167028c780351f"
 }
 

docs/configuration-conventions.md

@@ -81,7 +81,7 @@ A HOCON key named `isOpenFullTcpDisconnect` produces the setter `setIsOpenFullTc
 
 ## Nesting Depth
 
-The CI gate enforces a hard ceiling of **5 levels** (the historical maximum in `reference.conf`). New parameters must stay within **3 levels** from the top-level section. The gap between 3 and 5 is reserved for legacy paths that already exist — it is not a license to add new deep keys.
+The CI gate enforces a hard ceiling of **5 levels** (the historical maximum in `reference.conf`). New parameters should stay within **3 levels** from the top-level section. The gap between 3 and 5 is reserved for legacy paths that already exist — it is not a license to add new deep keys.
 
 ```
 level 1:  node { ... }
@@ -93,6 +93,22 @@ level 6+: rejected by CI gate unconditionally
 
 Each level of nesting requires a corresponding inner static bean class. If you find yourself going beyond 3 levels deep, consider flattening by moving the leaf keys up one level or using a longer camelCase key at level 2.
 
+## Configuration Loading Order
+
+java-tron loads configuration in two layers at startup:
+
+```
+Priority (highest wins):
+  1. User config file  — passed via -c; replaces the bundled config.conf entirely
+  2. reference.conf    — always loaded from inside the jar; provides defaults for every key
+```
+
+When a user passes `-c /path/to/node.conf`, the bundled `config.conf` is **not loaded at all** — it is completely replaced by the user's file. `reference.conf` is the only built-in file that is guaranteed to be read in every deployment.
+
+When `-c` is omitted (development or quick-start), the bundled `config.conf` fills the same role a user file would: it overrides `reference.conf` defaults for the keys it declares.
+
+The practical consequence for developers: **the default value you put in `reference.conf` is the value every production node uses.** The bundled `config.conf` only matters for users who start the node without `-c`.
+
 ## Adding a New Parameter: Checklist
 
 When adding a configuration parameter, all four steps are required in the same commit.
@@ -137,6 +153,8 @@ if (myNewOption > 64) {
 
 `config.conf` (in `framework/src/main/resources/`) is the sample user config shipped with the distribution. Only add your new key there if the value users should start with differs from the `reference.conf` default, or if the key needs a visible comment for users.
 
+Remember: in any real deployment the user passes `-c` and the bundled `config.conf` is bypassed entirely (see [Configuration Loading Order](#configuration-loading-order)). `reference.conf` is where your default actually takes effect — make sure it is safe and correct before touching `config.conf`.
+
 ## Field Types and HOCON Value Types
 
 | Java field type | HOCON value | Notes |

docs/configuration.md

@@ -2,21 +2,23 @@
 
 This guide explains the two-layer configuration system used by java-tron and walks through the most common customizations a node operator needs.
 
-## How the Two Config Files Work Together
+## How Configuration Files Work Together
 
-java-tron uses [Typesafe Config](https://github.com/lightbend/config) and applies two layers of configuration at startup:
+java-tron uses [Typesafe Config](https://github.com/lightbend/config) and applies configuration in priority order at startup:
 
 | File | Location | Purpose |
 |------|----------|---------|
 | `reference.conf` | Bundled inside the jar (`common` module) | Declares every parameter with its default value |
-| `config.conf` | Bundled template, optionally edited & passed via -c | Overrides only the values that differ from defaults |
+| Bundled `config.conf` | Bundled inside the jar (`framework` module) | Shipped template; active only when `-c` is omitted |
+| Your config file (e.g. `node.conf`) | Operator-supplied, passed via `-c` | Overrides values that differ from defaults; replaces the bundled `config.conf` entirely |
 
-**Loading priority:** values in `config.conf` always win. Any parameter that your `config.conf` omits is automatically filled in from `reference.conf`. You never need to copy the entire `reference.conf` into your own file — only include the parameters you actually want to change.
+**Loading priority:** values in your config file always win. Any parameter your file omits is automatically filled in from `reference.conf`. You never need to copy the entire `reference.conf` into your own file — only include the parameters you actually want to change.
 
 ```
 startup resolution order (highest wins):
-  1. config.conf  (your file, passed with -c)
-  2. reference.conf  (bundled in jar, fallback for everything)
+  1. your config file    (passed with -c; replaces bundled config.conf)
+  2. bundled config.conf (only when -c is omitted)
+  3. reference.conf      (always loaded; fallback for every key)
 ```
 
 `reference.conf` is the authoritative source of truth for every parameter name and its default. When in doubt, consult that file to see what a parameter does and what value the node will use if you leave it out.
@@ -25,20 +27,20 @@ startup resolution order (highest wins):
 
 ```bash
 # Using the distribution script
-java-tron-1.0.0/bin/FullNode -c /path/to/config.conf
+java-tron-1.0.0/bin/FullNode -c /path/to/node.conf
 
 # Using the jar directly
-java -jar FullNode.jar -c /path/to/config.conf
+java -jar FullNode.jar -c /path/to/node.conf
 
 # SR (Super Representative) mode
-java-tron-1.0.0/bin/FullNode -c /path/to/config.conf -w
+java-tron-1.0.0/bin/FullNode -c /path/to/node.conf -w
 ```
 
 If `-c` is omitted, the node loads the `config.conf` bundled inside the jar (the same file shipped with the distribution) merged with `reference.conf` as fallback. The bundled file already enables discovery/persist for mainnet operation. For production, copy it out, edit, and pass the edited copy via `-c` to make your configuration visible to operators.
 
-## Minimal config.conf
+## Minimal Config File
 
-A `config.conf` only needs to contain what you want to change. The following is sufficient for a mainnet full node:
+Your config file only needs to contain what you want to change. The following is sufficient for a mainnet full node:
 
 ```hocon
 node.discovery = {
@@ -212,7 +214,7 @@ rate.limiter = {
 
 ### Dynamic Config Reload (`node.dynamicConfig`)
 
-When enabled, the node re-reads `config.conf` periodically without restarting:
+When enabled, the node re-reads your config file periodically without restarting:
 
 ```hocon
 node.dynamicConfig = {
@@ -235,7 +237,7 @@ Not all parameters support hot-reload. Parameters that affect node identity, gen
 
 ## Applying a Config Change
 
-1. Edit your `config.conf` — only add or change the keys you need.
+1. Edit your config file — only add or change the keys you need.
 2. If `node.dynamicConfig.enable = true`, wait up to `checkInterval` seconds; the node picks up the change automatically.
 3. Otherwise, restart the node: `kill <pid>` then relaunch with the same `-c` flag.
 4. Check startup logs for a `[config]` line confirming the file was loaded and watch for any `ERROR` lines about unknown or invalid keys.