refactor(config): overhaul config docs, fix defaults, remove dead params

common/src/main/java/org/tron/common/parameter/CommonParameter.java

@@ -316,9 +316,6 @@ public class CommonParameter {
   public List<String> backupMembers;
   @Getter
   @Setter
-  public long receiveTcpMinDataLength; // clearParam: 2048
-  @Getter
-  @Setter
   public boolean isOpenFullTcpDisconnect;
   @Getter
   @Setter

common/src/main/java/org/tron/core/config/args/NodeConfig.java

@@ -77,7 +77,6 @@ public String getDiscoveryExternalIp() {
   private ValidContractProtoConfig validContractProto = new ValidContractProtoConfig();
   private int shieldedTransInPendingMaxCounts = 10;
   private long blockCacheTimeout = 60;
-  private long receiveTcpMinDataLength = 2048;
   private int maxTransactionPendingSize = 2000;
   private long pendingTransactionTimeout = 60000;
   private int maxTrxCacheSize = 50_000;
@@ -217,10 +216,10 @@ public static class RpcConfig {
     private int pBFTPort = 50071;
 
     private int thread = 0;
-    private int maxConcurrentCallsPerConnection = 2147483647;
+    private int maxConcurrentCallsPerConnection = 0;
     private int flowControlWindow = 1048576;
-    private long maxConnectionIdleInMillis = Long.MAX_VALUE;
-    private long maxConnectionAgeInMillis = Long.MAX_VALUE;
+    private long maxConnectionIdleInMillis = 0;
+    private long maxConnectionAgeInMillis = 0;
     private int maxMessageSize = 4194304;
     private int maxHeaderListSize = 8192;
     private int maxRstStream = 0;
@@ -269,6 +268,9 @@ public static class DynamicConfigSection {
     private long checkInterval = 600;
   }
 
+  /**
+   * All default parameters come from PublishConfig
+   */
   @Getter
   @Setter
   public static class DnsConfig {
@@ -279,8 +281,8 @@ public static class DnsConfig {
     private String dnsPrivate = "";
     private List<String> knownUrls = new ArrayList<>();
     private List<String> staticNodes = new ArrayList<>();
-    private int maxMergeSize = 0;
-    private double changeThreshold = 0.0;
+    private int maxMergeSize = 5;
+    private double changeThreshold = 0.1;
     private String serverType = "";
     private String accessKeyId = "";
     private String accessKeySecret = "";
@@ -306,20 +308,28 @@ public static NodeConfig fromConfig(Config config) {
     // --- Legacy key fallbacks (backward compatibility) ---
     // node.maxActiveNodes (old) -> maxConnections (new)
     if (section.hasPath("maxActiveNodes")) {
+      logger.warn("Configuring [node.maxActiveNodes] is deprecated and will be removed in a future "
+          + "release. Please use [node.maxConnections] instead.");
       nc.maxConnections = section.getInt("maxActiveNodes");
       if (section.hasPath("connectFactor")) {
+        logger.warn("Configuring [node.connectFactor] is deprecated and will be removed in a future "
+            + "release.");
         nc.minConnections = (int) (nc.maxConnections * section.getDouble("connectFactor"));
       }
       if (section.hasPath("activeConnectFactor")) {
+        logger.warn("Configuring [node.activeConnectFactor] is deprecated and will be removed in a "
+            + "future release.");
         nc.minActiveConnections = (int) (nc.maxConnections
             * section.getDouble("activeConnectFactor"));
       }
     }
     if (section.hasPath("maxActiveNodesWithSameIp")) {
+      logger.warn("Configuring [node.maxActiveNodesWithSameIp] is deprecated and will be removed "
+          + "in a future release. Please use [node.maxConnectionsWithSameIp] instead.");
       nc.maxConnectionsWithSameIp = section.getInt("maxActiveNodesWithSameIp");
     }
 
-    // Legacy key fallback: node.fullNodeAllowShieldedTransaction -> allowShieldedTransactionApi.
+    // Legacy key fallback: node.allowShieldedTransactionApi wins fullNodeAllowShieldedTransaction
     if (section.hasPath("allowShieldedTransactionApi")) {
       nc.allowShieldedTransactionApi =
           section.getBoolean("allowShieldedTransactionApi");
@@ -353,6 +363,16 @@ private void postProcess() {
       rpc.thread = (Runtime.getRuntime().availableProcessors() + 1) / 2;
     }
 
+    if (rpc.maxConcurrentCallsPerConnection == 0) {
+      rpc.maxConcurrentCallsPerConnection = Integer.MAX_VALUE;
+    }
+    if (rpc.maxConnectionIdleInMillis == 0) {
+      rpc.maxConnectionIdleInMillis = Long.MAX_VALUE;
+    }
+    if (rpc.maxConnectionAgeInMillis == 0) {
+      rpc.maxConnectionAgeInMillis = Long.MAX_VALUE;
+    }
+
     // validateSignThreadNum: 0 = auto-detect
     if (validateSignThreadNum == 0) {
       validateSignThreadNum = Runtime.getRuntime().availableProcessors();
@@ -376,6 +396,14 @@ private void postProcess() {
       syncFetchBatchNum = 100;
     }
 
+    // fetchBlock.timeout : clamp to [100, 1000]
+    if (fetchBlock.timeout > 1000) {
+      fetchBlock.timeout = 1000;
+    }
+    if (fetchBlock.timeout < 100) {
+      fetchBlock.timeout = 100;
+    }
+
     // maxPendingBlockSize: clamp to [50, 2000]
     if (maxPendingBlockSize > 2000) {
       maxPendingBlockSize = 2000;

common/src/main/resources/reference.conf

@@ -72,19 +72,27 @@ storage {
   # }
   # setting can improve leveldb performance .... end, deprecated for arm
 
-  # Example per-database overrides:
+  # Per-database storage configuration overrides. Otherwise databases use global defaults and store
+  # data in "output-directory" or the directory specified by the "-d" / "--output-directory" option.
+  # Attention: name is a required field that must be set!
+  # The name and path properties take effect for both LevelDB and RocksDB storage engines,
+  # while additional properties (createIfMissing, paranoidChecks, compressionType, etc.)
+  # only take effect when using LevelDB.
+  # Example:
+  # properties = [
   #   {
   #     name = "account",
   #     path = "storage_directory_test",
-  #     createIfMissing = true,
+  #     createIfMissing = true,     // deprecated for arm start
   #     paranoidChecks = true,
   #     verifyChecksums = true,
   #     compressionType = 1,        // compressed with snappy
   #     blockSize = 4096,           // 4  KB =         4 * 1024 B
   #     writeBufferSize = 10485760, // 10 MB = 10 * 1024 * 1024 B
   #     cacheSize = 10485760,       // 10 MB = 10 * 1024 * 1024 B
-  #     maxOpenFiles = 100
+  #     maxOpenFiles = 100          // deprecated for arm end
   #   }
+  # ]
   properties = []
 
   needToUpdateAsset = true
@@ -138,12 +146,11 @@ node.discovery = {
 # }
 
 node.backup {
-  port = 10001
-  priority = 0
-  keepAliveInterval = 3000
+  port = 10001             # UDP listen port; each member should have the same configuration
+  priority = 0             # Node priority; each member should use a different priority
+  keepAliveInterval = 3000 # Keep-alive interval (ms); each member should have the same configuration
   members = [
-    # "ip",
-    # "ip"
+    # "ip",               # Peer IP list, better to add at most one IP; must not contain this node's own IP
   ]
 }
 
@@ -188,7 +195,17 @@ node {
   maxHttpConnectNumber = 50
   minParticipationRate = 0
 
-  # Whether to enable shielded transaction API
+  # Deprecate, don't use
+  activeConnectFactor = 0.1
+  # Deprecate, don't use
+  connectFactor = 0.6
+
+  # WARNING: Some shielded transaction APIs require sending private keys as parameters.
+  # Calling these APIs on untrusted or remote nodes may leak your private keys.
+  # It is recommended to invoke them locally for development and testing.
+  # To opt in, set: allowShieldedTransactionApi = true
+  # Migration: the legacy key node.fullNodeAllowShieldedTransaction is still supported
+  # but deprecated; please migrate to node.allowShieldedTransactionApi.
   # allowShieldedTransactionApi = false
 
   # Whether to print config log at startup
@@ -207,8 +224,7 @@ node {
   isOpenFullTcpDisconnect = false
   inactiveThreshold = 600       // seconds
   maxFastForwardNum = 4
-  activeConnectFactor = 0.1
-  connectFactor = 0.6
+
   # Legacy alias `maxActiveNodesWithSameIp` is still accepted from user config
   # (see NodeConfig alias-fallback) but is intentionally NOT defaulted here —
   # shipping it in reference.conf would always mask the modern `maxConnectionsWithSameIp`.
@@ -243,7 +259,10 @@ node {
     PBFTEnable = true
     PBFTPort = 8092
 
-    # Maximum HTTP request body size, default 4MB. Independent from rpc.maxMessageSize.
+    # Maximum HTTP request body size (default 4MB). Supports human-readable sizes: 4m, 4MB, 4194304.
+    # Must be non-negative and <= 2147483647 (Integer.MAX_VALUE, ~2 GiB).
+    # Setting to 0 rejects all non-empty request bodies (not "unlimited").
+    # Independent from rpc.maxMessageSize.
     maxMessageSize = 4M
     maxNestingDepth = 100
     maxTokenCount = 100000
@@ -261,19 +280,21 @@ node {
     thread = 0
 
     # Maximum concurrent calls per incoming connection
-    # No limit on concurrent calls per connection
-    maxConcurrentCallsPerConnection = 2147483647
+    # 0 means No limit on concurrent calls per connection
+    maxConcurrentCallsPerConnection = 0
 
     # HTTP/2 flow control window (bytes), default 1MB
     flowControlWindow = 1048576
 
-    # Connection idle timeout (ms). No limit by default.
-    maxConnectionIdleInMillis = 9223372036854775807
+    # Connection idle timeout (ms). Connections idle longer than this are gracefully terminated. 0 = no limit
+    maxConnectionIdleInMillis = 0
 
-    # Connection max age (ms). No limit by default.
-    maxConnectionAgeInMillis = 9223372036854775807
+    # Connection max age (ms). 0 = no limit
+    maxConnectionAgeInMillis = 0
 
-    # Maximum message size (bytes), default 4MB
+    # Maximum gRPC message size (default 4MB). Supports human-readable sizes: 4m, 4MB, 4194304.
+    # Must be non-negative and <= 2147483647 (Integer.MAX_VALUE, ~2 GiB).
+    # Setting to 0 rejects all non-empty request bodies (not "unlimited").
     maxMessageSize = 4194304
 
     # Maximum header list size (bytes), default 8192
@@ -326,7 +347,6 @@ node {
   blockCacheTimeout = 60
 
   # TCP and transaction limits
-  receiveTcpMinDataLength = 2048
   maxTransactionPendingSize = 2000
   pendingTransactionTimeout = 60000
   # total cached trx across handler queues + pending + rePush
@@ -343,28 +363,45 @@ node {
   validContractProto.threads = 0
 
   dns {
+    # DNS URLs to discover peers, format: tree://{pubkey}@{domain}. Default: empty.
     treeUrls = [
       # "tree://AKMQMNAJJBL73LXWPXDI4I5ZWWIZ4AWO34DWQ636QOBBXNFXH3LQS@main.trondisco.net",
     ]
+
+    # Enable or disable DNS publish. Default: false.
     publish = false
+    # DNS domain to publish nodes, required if publish is true.
     dnsDomain = ""
+    # DNS private key used to publish, required if publish is true, hex string of length 64.
     dnsPrivate = ""
+    # Known DNS URLs to publish if publish is true, format: tree://{pubkey}@{domain}. Default: empty.
     knownUrls = []
+    # Static nodes to publish on DNS, "ip:port".
     staticNodes = []
-    maxMergeSize = 0
-    changeThreshold = 0.0
+    # Merge several nodes into a leaf of tree, should be 1~5.
+    maxMergeSize = 5
+    # Only update DNS data when node change percent exceeds this threshold.
+    changeThreshold = 0.1
+    # DNS server to publish, required if publish is true. Supported values: "aws", "aliyun".
     serverType = ""
+    # Access key ID of AWS or Aliyun API, required if publish is true.
     accessKeyId = ""
+    # Access key secret of AWS or Aliyun API, required if publish is true.
     accessKeySecret = ""
+    # Endpoint of Aliyun DNS server, required if serverType is "aliyun".
     aliyunDnsEndpoint = ""
+    # Region of AWS API (e.g. "us-east-1"), required if serverType is "aws".
     awsRegion = ""
+    # Host zone ID of AWS domain, required if serverType is "aws".
     awsHostZoneId = ""
   }
 
   # Open history query APIs on lite FullNode (may return null for some queries)
   openHistoryQueryWhenLiteFN = false
 
   jsonrpc {
+    # Note: Before release_4.8.1, if you turn on jsonrpc and run it for a while and then turn it off,
+    # you will not be able to get the data from eth_getLogs for that period of time. Default: false
     httpFullNodeEnable = false
     httpFullNodePort = 8545
     httpSolidityEnable = false
@@ -699,7 +736,16 @@ vm = {
   # Max retry time for executing transaction in estimating energy
   estimateEnergyMaxRetry = 3
 
-  # Max TVM execution time (ms) for constant calls. 0 means no effect
+  # Max TVM execution time (ms) for constant calls — applies to
+  # triggerconstantcontract, triggersmartcontract dispatched to view/pure
+  # functions, estimateenergy, eth_call, eth_estimateGas, and any other RPC
+  # routed through the constant-call path. When set, must be a positive
+  # integer that fits VM deadline conversion and is used verbatim as the
+  # per-call deadline (no clamp against the network's maxCpuTimeOfOneTx).
+  # Omit the property entirely to keep the default behaviour of sharing the
+  # block-processing deadline. Migration note: if previously running --debug
+  # to extend constant calls, switch to this option (--debug also extends
+  # block-processing, which is unsafe; see issue #6266). Default: 0 (no effect).
   constantCallTimeoutMs = 0
 }
 
@@ -758,46 +804,50 @@ event.subscribe = {
   enable = false
 
   native = {
-    useNativeQueue = false
-    bindport = 5555
-    sendqueuelength = 1000
+    useNativeQueue = false // if true, use native message queue, else use event plugin.
+    bindport = 5555        // bind port
+    sendqueuelength = 1000 // max length of send queue
   }
 
   version = 0
+  # Specify the starting block number to sync historical events. Only applicable when version = 1.
+  # After performing a full event sync, set this value to 0 or a negative number.
   startSyncBlockNum = 0
-  path = ""
-  server = ""
+  path = ""   // absolute path of plugin
+  server = "" // target server address to receive event triggers, "ip:port"
+  # dbname|username|password. To auto-create indexes on missing collections, append |2:
+  # dbname|username|password|2 (if collection exists, indexes must be created manually).
   dbconfig = ""
   contractParse = true
 
   topics = [
     {
-      triggerName = "block"
+      triggerName = "block" // block trigger, the value can't be modified
       enable = false
-      topic = "block"
-      solidified = false
+      topic = "block"       // plugin topic, the value could be modified
+      solidified = false    // if set true, just need solidified block. Default: false
     },
     {
       triggerName = "transaction"
       enable = false
       topic = "transaction"
       solidified = false
-      ethCompatible = false
+      ethCompatible = false // if set true, add transactionIndex, cumulativeEnergyUsed, preCumulativeLogCount, logList, energyUnitPrice. Default: false
     },
     {
-      triggerName = "contractevent"
+      triggerName = "contractevent" // contractevent represents contractlog data decoded by the ABI.
       enable = false
       topic = "contractevent"
     },
     {
       triggerName = "contractlog"
       enable = false
       topic = "contractlog"
-      redundancy = false
+      redundancy = false // if set true, contractevent will also be regarded as contractlog
     },
     {
-      triggerName = "solidity"
-      enable = true
+      triggerName = "solidity" // solidity block trigger (just block number and timestamp), the value can't be modified
+      enable = true            // Default: true
       topic = "solidity"
     },
     {
@@ -809,18 +859,18 @@ event.subscribe = {
       triggerName = "soliditylog"
       enable = false
       topic = "soliditylog"
-      redundancy = false
+      redundancy = false // if set true, solidityevent will also be regarded as soliditylog
     }
   ]
 
   filter = {
-    fromblock = ""
-    toblock = ""
+    fromblock = "" // "", "earliest", or a specific block number as the beginning of the queried range
+    toblock = ""   // "", "latest", or a specific block number as end of the queried range
     contractAddress = [
-      ""
+      "" // contract address to subscribe; "" means any contract address
     ]
     contractTopic = [
-      ""
+      "" // contract topic to subscribe; "" means any contract topic
     ]
   }
 }