fix(config): deprecate CLI params and add guardrails (#6580)

Author: vividctrlalt

framework/src/main/java/org/tron/core/config/args/Args.java

@@ -7,6 +7,7 @@
 import static org.tron.core.Constant.DEFAULT_PROPOSAL_EXPIRE_TIME;
 import static org.tron.core.Constant.DYNAMIC_ENERGY_INCREASE_FACTOR_RANGE;
 import static org.tron.core.Constant.DYNAMIC_ENERGY_MAX_FACTOR_RANGE;
+import static org.tron.core.Constant.ENERGY_LIMIT_IN_CONSTANT_TX;
 import static org.tron.core.Constant.MAX_PROPOSAL_EXPIRE_TIME;
 import static org.tron.core.Constant.MIN_PROPOSAL_EXPIRE_TIME;
 import static org.tron.core.config.Parameter.ChainConstant.BLOCK_PRODUCE_TIMEOUT_PERCENT;
@@ -83,6 +84,40 @@
 @Component
 public class Args extends CommonParameter {
 
+  /**
+   * Maps deprecated CLI option names to their config-file equivalents.
+   * Options not in this map have no config equivalent and are being removed entirely.
+   */
+  private static final Map<String, String> DEPRECATED_CLI_TO_CONFIG;
+
+  static {
+    Map<String, String> m = new HashMap<>();
+    m.put("--storage-db-directory", "storage.db.directory");
+    m.put("--storage-db-engine", "storage.db.engine");
+    m.put("--storage-db-synchronous", "storage.db.sync");
+    m.put("--storage-index-directory", "storage.index.directory");
+    m.put("--storage-index-switch", "storage.index.switch");
+    m.put("--storage-transactionHistory-switch", "storage.transHistory.switch");
+    m.put("--contract-parse-enable", "event.subscribe.contractParse");
+    m.put("--support-constant", "vm.supportConstant");
+    m.put("--max-energy-limit-for-constant", "vm.maxEnergyLimitForConstant");
+    m.put("--lru-cache-size", "vm.lruCacheSize");
+    m.put("--min-time-ratio", "vm.minTimeRatio");
+    m.put("--max-time-ratio", "vm.maxTimeRatio");
+    m.put("--save-internaltx", "vm.saveInternalTx");
+    m.put("--save-featured-internaltx", "vm.saveFeaturedInternalTx");
+    m.put("--save-cancel-all-unfreeze-v2-details", "vm.saveCancelAllUnfreezeV2Details");
+    m.put("--long-running-time", "vm.longRunningTime");
+    m.put("--max-connect-number", "node.maxHttpConnectNumber");
+    m.put("--rpc-thread", "node.rpc.thread");
+    m.put("--solidity-thread", "node.solidity.threads");
+    m.put("--validate-sign-thread", "node.validateSignThreadNum");
+    m.put("--trust-node", "node.trustNode");
+    m.put("--history-balance-lookup", "storage.balance.history.lookup");
+    m.put("--es", "event.subscribe.enable");
+    DEPRECATED_CLI_TO_CONFIG = Collections.unmodifiableMap(m);
+  }
+
   @Getter
   private static String configFilePath = "";
 
@@ -169,7 +204,7 @@ public static void applyConfigParams(
 
     if (config.hasPath(ConfigKey.VM_MAX_ENERGY_LIMIT_FOR_CONSTANT)) {
       long configLimit = config.getLong(ConfigKey.VM_MAX_ENERGY_LIMIT_FOR_CONSTANT);
-      PARAMETER.maxEnergyLimitForConstant = max(3_000_000L, configLimit, true);
+      PARAMETER.maxEnergyLimitForConstant = max(ENERGY_LIMIT_IN_CONSTANT_TX, configLimit, true);
     }
 
     if (config.hasPath(ConfigKey.VM_LRU_CACHE_SIZE)) {
@@ -678,6 +713,9 @@ public static void applyConfigParams(
     PARAMETER.eventFilter =
         config.hasPath(ConfigKey.EVENT_SUBSCRIBE_FILTER) ? getEventFilter(config) : null;
 
+    PARAMETER.eventSubscribe = config.hasPath(ConfigKey.EVENT_SUBSCRIBE_ENABLE)
+        && config.getBoolean(ConfigKey.EVENT_SUBSCRIBE_ENABLE);
+
     if (config.hasPath(ConfigKey.ALLOW_SHIELDED_TRANSACTION_API)) {
       PARAMETER.allowShieldedTransactionApi =
           config.getBoolean(ConfigKey.ALLOW_SHIELDED_TRANSACTION_API);
@@ -1012,6 +1050,28 @@ private static void applyCLIParams(CLIParameter cmd, JCommander jc) {
         .map(ParameterDescription::getLongestName)
         .collect(Collectors.toSet());
 
+    jc.getParameters().stream()
+        .filter(ParameterDescription::isAssigned)
+        .filter(pd -> {
+          try {
+            return CLIParameter.class.getDeclaredField(pd.getParameterized().getName())
+                .isAnnotationPresent(Deprecated.class);
+          } catch (NoSuchFieldException e) {
+            return false;
+          }
+        })
+        .forEach(pd -> {
+          String cliOption = pd.getLongestName();
+          String configKey = DEPRECATED_CLI_TO_CONFIG.get(cliOption);
+          if (configKey != null) {
+            logger.warn("CLI option '{}' is deprecated and will be removed in a future release."
+                + " Please use config key '{}' instead.", cliOption, configKey);
+          } else {
+            logger.warn("CLI option '{}' is deprecated and will be removed in a future release.",
+                cliOption);
+          }
+        });
+
     if (assigned.contains("--output-directory")) {
       PARAMETER.outputDirectory = cmd.outputDirectory;
     }
@@ -1022,7 +1082,8 @@ private static void applyCLIParams(CLIParameter cmd, JCommander jc) {
       PARAMETER.supportConstant = cmd.supportConstant;
     }
     if (assigned.contains("--max-energy-limit-for-constant")) {
-      PARAMETER.maxEnergyLimitForConstant = cmd.maxEnergyLimitForConstant;
+      PARAMETER.maxEnergyLimitForConstant = max(ENERGY_LIMIT_IN_CONSTANT_TX,
+          cmd.maxEnergyLimitForConstant, true);
     }
     if (assigned.contains("--lru-cache-size")) {
       PARAMETER.lruCacheSize = cmd.lruCacheSize;
@@ -1105,7 +1166,12 @@ private static void applyCLIParams(CLIParameter cmd, JCommander jc) {
     if (assigned.contains("--log-config")) {
       PARAMETER.logbackPath = cmd.logbackPath;
     }
+    // seedNodes is a JCommander positional (main) parameter, which does not support
+    // isAssigned(). An empty-check is used instead — this is safe because the default
+    // is an empty list, so non-empty means the user explicitly passed values on CLI.
     if (!cmd.seedNodes.isEmpty()) {
+      logger.warn("Positional seed-node arguments are deprecated. "
+          + "Please use seed.node.ip.list in the config file instead.");
       List<InetSocketAddress> seeds = new ArrayList<>();
       for (String s : cmd.seedNodes) {
         seeds.add(NetUtil.parseInetSocketAddress(s));
@@ -1691,6 +1757,9 @@ public static void printHelp(JCommander jCommander) {
         jCommander.getProgramName();
     helpStr.append(String.format("%nUsage: java -jar %s [options] [seedNode <seedNode> ...]%n",
         programName));
+    helpStr.append(String.format(
+        "%nNote: Positional seedNode arguments are deprecated."
+            + " Use seed.node.ip.list in the config file instead.%n"));
     helpStr.append(String.format("%nVERSION: %n%s-%s%n", Version.getVersion(),
         getCommitIdAbbrev()));
 
@@ -1712,9 +1781,21 @@ public static void printHelp(JCommander jCommander) {
           logger.warn("Miss option:{}", option);
           continue;
         }
+        boolean isDeprecated;
+        try {
+          isDeprecated = CLIParameter.class.getDeclaredField(
+              parameterDescription.getParameterized().getName())
+              .isAnnotationPresent(Deprecated.class);
+        } catch (NoSuchFieldException e) {
+          isDeprecated = false;
+        }
+        String desc = upperFirst(parameterDescription.getDescription());
+        if (isDeprecated) {
+          desc += " (deprecated)";
+        }
         String tmpOptionDesc = String.format("%s\t\t\t%s%n",
             Strings.padEnd(parameterDescription.getNames(), optionMaxLength, ' '),
-            upperFirst(parameterDescription.getDescription()));
+            desc);
         helpStr.append(tmpOptionDesc);
       }
     }

framework/src/main/java/org/tron/core/config/args/CLIParameter.java

@@ -10,6 +10,9 @@
  * Fields here have NO default values — defaults live in CommonParameter.
  * JCommander only populates fields that are explicitly passed on the
  * command line.
+ *
+ * <p>Parameters marked {@code @Deprecated} are scheduled for removal.
+ * Use the corresponding config-file options instead.</p>
  */
 @NoArgsConstructor
 public class CLIParameter {
@@ -50,57 +53,70 @@ public class CLIParameter {
   @Parameter(names = {"--keystore-factory"}, description = "running KeystoreFactory")
   public boolean keystoreFactory;
 
+  @Deprecated
   @Parameter(names = {"--fast-forward"})
   public boolean fastForward;
 
+  @Deprecated
   @Parameter(names = {"--es"}, description = "Start event subscribe server")
   public boolean eventSubscribe;
 
   @Parameter(names = {"--p2p-disable"}, description = "Switch for p2p module initialization. "
       + "(default: false)", arity = 1)
   public boolean p2pDisable;
 
+  @Deprecated
   @Parameter(description = "--seed-nodes")
   public List<String> seedNodes = new ArrayList<>();
 
-  // -- Storage parameters --
+  // -- Storage parameters (deprecated, use config file instead) --
 
+  @Deprecated
   @Parameter(names = {"--storage-db-directory"}, description = "Storage db directory")
   public String storageDbDirectory;
 
+  @Deprecated
   @Parameter(names = {"--storage-db-engine"},
       description = "Storage db engine.(leveldb or rocksdb)")
   public String storageDbEngine;
 
+  @Deprecated
   @Parameter(names = {"--storage-db-synchronous"},
       description = "Storage db is synchronous or not.(true or false)")
   public String storageDbSynchronous;
 
+  @Deprecated
   @Parameter(names = {"--storage-index-directory"}, description = "Storage index directory")
   public String storageIndexDirectory;
 
+  @Deprecated
   @Parameter(names = {"--storage-index-switch"},
       description = "Storage index switch.(on or off)")
   public String storageIndexSwitch;
 
+  @Deprecated
   @Parameter(names = {"--storage-transactionHistory-switch"},
       description = "Storage transaction history switch.(on or off)")
   public String storageTransactionHistorySwitch;
 
+  @Deprecated
   @Parameter(names = {"--contract-parse-enable"}, description = "Switch for contract parses in "
       + "java-tron. (default: true)")
   public String contractParseEnable;
 
-  // -- Runtime parameters --
+  // -- Runtime parameters (deprecated except --debug, use config file instead) --
 
+  @Deprecated
   @Parameter(names = {"--support-constant"}, description = "Support constant calling for TVM. "
       + "(default: false)")
   public boolean supportConstant;
 
+  @Deprecated
   @Parameter(names = {"--max-energy-limit-for-constant"},
       description = "Max energy limit for constant calling. (default: 100,000,000)")
   public long maxEnergyLimitForConstant;
 
+  @Deprecated
   @Parameter(names = {"--lru-cache-size"}, description = "Max LRU size for caching bytecode and "
       + "result of JUMPDEST analysis. (default: 500)")
   public int lruCacheSize;
@@ -109,48 +125,60 @@ public class CLIParameter {
       + "will not check for timeout. (default: false)")
   public boolean debug;
 
+  @Deprecated
   @Parameter(names = {"--min-time-ratio"}, description = "Minimum CPU tolerance when executing "
       + "timeout transactions while synchronizing blocks. (default: 0.0)")
   public double minTimeRatio;
 
+  @Deprecated
   @Parameter(names = {"--max-time-ratio"}, description = "Maximum CPU tolerance when executing "
       + "non-timeout transactions while synchronizing blocks. (default: 5.0)")
   public double maxTimeRatio;
 
+  @Deprecated
   @Parameter(names = {"--save-internaltx"}, description = "Save internal transactions generated "
       + "during TVM execution, such as create, call and suicide. (default: false)")
   public boolean saveInternalTx;
 
+  @Deprecated
   @Parameter(names = {"--save-featured-internaltx"}, description = "Save featured internal "
       + "transactions generated during TVM execution, such as freeze, vote and so on. "
       + "(default: false)")
   public boolean saveFeaturedInternalTx;
 
+  @Deprecated
   @Parameter(names = {"--save-cancel-all-unfreeze-v2-details"},
       description = "Record the details of the internal transactions generated by the "
           + "CANCELALLUNFREEZEV2 opcode, such as bandwidth/energy/tronpower cancel amount. "
           + "(default: false)")
   public boolean saveCancelAllUnfreezeV2Details;
 
+  @Deprecated
   @Parameter(names = {"--long-running-time"})
   public int longRunningTime;
 
+  @Deprecated
   @Parameter(names = {"--max-connect-number"}, description = "Http server max connect number "
       + "(default:50)")
   public int maxHttpConnectNumber;
 
+  @Deprecated
   @Parameter(names = {"--rpc-thread"}, description = "Num of gRPC thread")
   public int rpcThreadNum;
 
+  @Deprecated
   @Parameter(names = {"--solidity-thread"}, description = "Num of solidity thread")
   public int solidityThreads;
 
+  @Deprecated
   @Parameter(names = {"--validate-sign-thread"}, description = "Num of validate thread")
   public int validateSignThreadNum;
 
+  @Deprecated
   @Parameter(names = {"--trust-node"}, description = "Trust node addr")
   public String trustNodeAddr;
 
+  @Deprecated
   @Parameter(names = {"--history-balance-lookup"})
   public boolean historyBalanceLookup;
 }

framework/src/main/java/org/tron/core/config/args/ConfigKey.java

@@ -272,6 +272,7 @@ private ConfigKey() {
 
   // event
   public static final String EVENT_SUBSCRIBE = "event.subscribe";
+  public static final String EVENT_SUBSCRIBE_ENABLE = "event.subscribe.enable";
   public static final String EVENT_SUBSCRIBE_FILTER = "event.subscribe.filter";
   public static final String EVENT_SUBSCRIBE_VERSION = "event.subscribe.version";
   public static final String EVENT_SUBSCRIBE_START_SYNC_BLOCK_NUM =

framework/src/main/resources/config.conf

@@ -762,6 +762,7 @@ committee = {
 }
 
 event.subscribe = {
+  enable = false // enable event subscribe, replaces deprecated CLI flag --es
   native = {
     useNativeQueue = true // if true, use native message queue, else use event plugin.
     bindport = 5555 // bind port

framework/src/test/java/org/tron/core/config/args/ArgsTest.java

@@ -318,6 +318,28 @@ public void testCliOverridesStorageConfig() {
     Args.clearParam();
   }
 
+  /**
+   * Verify that event.subscribe.enable = false from config is read correctly.
+   */
+  @Test
+  public void testEventSubscribeFromConfig() {
+    Args.setParam(new String[] {}, TestConstants.TEST_CONF);
+    Assert.assertFalse(Args.getInstance().isEventSubscribe());
+    Args.clearParam();
+  }
+
+  /**
+   * Verify that CLI --es overrides event.subscribe.enable from config.
+   * config-test.conf defines: event.subscribe.enable = false,
+   * passing --es explicitly sets eventSubscribe = true, overriding config.
+   */
+  @Test
+  public void testCliEsOverridesConfig() {
+    Args.setParam(new String[] {"--es"}, TestConstants.TEST_CONF);
+    Assert.assertTrue(Args.getInstance().isEventSubscribe());
+    Args.clearParam();
+  }
+
   /**
    * Verify that config file storage values are applied when no CLI override is present.
    *

framework/src/test/resources/config-test.conf

@@ -382,4 +382,8 @@ rate.limiter.http = [
 ]
 
 node.dynamicConfig.enable = true
+
+event.subscribe = {
+  enable = false
+}
 node.dynamicConfig.checkInterval = 0