From a5cf7bbd0741112dcfbfab9ef4fecf0c37964b3a Mon Sep 17 00:00:00 2001
From: jiangyuanshu <317787106@qq.com>
Date: Fri, 12 Jun 2026 11:55:58 +0800
Subject: [PATCH 1/3] update comment of reference.conf

---
 common/src/main/resources/reference.conf | 12 +++++++-----
 1 file changed, 7 insertions(+), 5 deletions(-)

diff --git a/common/src/main/resources/reference.conf b/common/src/main/resources/reference.conf
index f1e4907274..5905c7cc2e 100644
--- a/common/src/main/resources/reference.conf
+++ b/common/src/main/resources/reference.conf
@@ -196,13 +196,15 @@ node {
   # Max in-flight (requested but not yet processed) blocks during sync. Range: [50, 2000].
   maxPendingBlockSize = 500
 
-  # Number of validate sign threads, default availableProcessors
   # Number of validate sign threads, 0 = auto (availableProcessors)
   validateSignThreadNum = 0
 
   maxConnections = 30           # Maximum peer connections.
   minConnections = 8            # Minimum peer connections to maintain.
   minActiveConnections = 3      # Minimum active peer connections.
+  # 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`.
   maxConnectionsWithSameIp = 2  # Maximum peer connections per IP.
   maxHttpConnectNumber = 50     # Maximum HTTP connections.
   minParticipationRate = 0      # Minimum SR participation rate.
@@ -233,9 +235,9 @@ node {
   inactiveThreshold = 600       // seconds
   maxFastForwardNum = 4      # Number of SRs after the block-producing SR that a fast-forward node forwards blocks to.
 
-  # 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`.
+  # Enable the node's legacy internal metrics: turns on MetricsUtil counters/histograms
+  # and registers the monitor gRPC service (MonitorApi) on the RPC server. This is
+  # independent of the Prometheus exporter configured under node.metrics.prometheus above.
   metricsEnable = false
 
   # P2P protocol version settings.
@@ -453,7 +455,7 @@ node {
 ## Rate limiter config
 rate.limiter = {
   # Each HTTP servlet and gRPC method can have its own rate-limit strategy.
-  # Three blocking strategies are available:
+  # Three API rate-limit strategies are available:
   #   GlobalPreemptibleAdapter – limits maximum concurrent requests globally.
   #                              paramString = "permit=N" (N = max concurrent calls)
   #   QpsRateLimiterAdapter    – limits average QPS across all callers.

From dabd2a97c4d902af4f923672d2de161f47c1e728 Mon Sep 17 00:00:00 2001
From: jiangyuanshu <317787106@qq.com>
Date: Fri, 12 Jun 2026 15:24:00 +0800
Subject: [PATCH 2/3] update comment

---
 common/src/main/resources/reference.conf | 10 ++++------
 1 file changed, 4 insertions(+), 6 deletions(-)

diff --git a/common/src/main/resources/reference.conf b/common/src/main/resources/reference.conf
index 5905c7cc2e..3b2e8afb12 100644
--- a/common/src/main/resources/reference.conf
+++ b/common/src/main/resources/reference.conf
@@ -202,9 +202,7 @@ node {
   maxConnections = 30           # Maximum peer connections.
   minConnections = 8            # Minimum peer connections to maintain.
   minActiveConnections = 3      # Minimum active peer connections.
-  # 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`.
+  # Legacy alias `maxActiveNodesWithSameIp` is still accepted but deprecated
   maxConnectionsWithSameIp = 2  # Maximum peer connections per IP.
   maxHttpConnectNumber = 50     # Maximum HTTP connections.
   minParticipationRate = 0      # Minimum SR participation rate.
@@ -235,9 +233,9 @@ node {
   inactiveThreshold = 600       // seconds
   maxFastForwardNum = 4      # Number of SRs after the block-producing SR that a fast-forward node forwards blocks to.
 
-  # Enable the node's legacy internal metrics: turns on MetricsUtil counters/histograms
-  # and registers the monitor gRPC service (MonitorApi) on the RPC server. This is
-  # independent of the Prometheus exporter configured under node.metrics.prometheus above.
+  # Deprecated and it will be removed in next release. Turns on MetricsUtil counters/histograms and
+  # registers the monitor gRPC service (MonitorApi) on the RPC server. This is not related of the
+  # Prometheus exporter configured under node.metrics.prometheus above.
   metricsEnable = false
 
   # P2P protocol version settings.

From 1c6eb3f226a63ade05d94f3e0191cfafd2745484 Mon Sep 17 00:00:00 2001
From: jiangyuanshu <317787106@qq.com>
Date: Fri, 12 Jun 2026 16:48:58 +0800
Subject: [PATCH 3/3] update comment of node.metricsEnable

---
 common/src/main/resources/reference.conf | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/common/src/main/resources/reference.conf b/common/src/main/resources/reference.conf
index 3b2e8afb12..25fc4832e5 100644
--- a/common/src/main/resources/reference.conf
+++ b/common/src/main/resources/reference.conf
@@ -233,9 +233,9 @@ node {
   inactiveThreshold = 600       // seconds
   maxFastForwardNum = 4      # Number of SRs after the block-producing SR that a fast-forward node forwards blocks to.
 
-  # Deprecated and it will be removed in next release. Turns on MetricsUtil counters/histograms and
-  # registers the monitor gRPC service (MonitorApi) on the RPC server. This is not related of the
-  # Prometheus exporter configured under node.metrics.prometheus above.
+  # Deprecated. Enables legacy MetricsUtil counters/histograms and registers
+  # the monitor gRPC service (MonitorApi) on the RPC server.
+  # This is independent of the Prometheus exporter configured under node.metrics.prometheus.
   metricsEnable = false
 
   # P2P protocol version settings.