From f55e9cf56a3272b3ca1ee0a3b5bd6492ec97a649 Mon Sep 17 00:00:00 2001 From: vividctrlalt Date: Mon, 16 Mar 2026 06:02:33 +0000 Subject: [PATCH 1/4] fix(config): deprecate CLI params and add safety guardrails for #6569 review follow-up - Mark 23 config-file-replaceable CLI parameters as @Deprecated in CLIParameter - Add runtime deprecation warning via reflection when deprecated CLI options are used - Add max(3_000_000L, ...) guardrail for --max-energy-limit-for-constant CLI path, consistent with config-file validation (addresses waynercheung's review feedback) - Document seedNodes positional parameter behavior and add deprecation warning - Retain 11 essential CLI params: -c, -d, --log-config, -h, -v, -w, -p, --witness-address, --password, --keystore-factory, --debug --- .../java/org/tron/core/config/args/Args.java | 23 ++++++++++++- .../tron/core/config/args/CLIParameter.java | 34 +++++++++++++++++-- 2 files changed, 54 insertions(+), 3 deletions(-) diff --git a/framework/src/main/java/org/tron/core/config/args/Args.java b/framework/src/main/java/org/tron/core/config/args/Args.java index 0e71294d78..475d229b11 100644 --- a/framework/src/main/java/org/tron/core/config/args/Args.java +++ b/framework/src/main/java/org/tron/core/config/args/Args.java @@ -998,6 +998,21 @@ 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 -> logger.warn( + "CLI option '{}' is deprecated and will be removed in a future release. " + + "Please use the corresponding config-file option instead.", + pd.getLongestName())); + if (assigned.contains("--output-directory")) { PARAMETER.outputDirectory = cmd.outputDirectory; } @@ -1008,7 +1023,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(3_000_000L, + cmd.maxEnergyLimitForConstant, true); } if (assigned.contains("--lru-cache-size")) { PARAMETER.lruCacheSize = cmd.lruCacheSize; @@ -1091,7 +1107,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 seeds = new ArrayList<>(); for (String s : cmd.seedNodes) { seeds.add(NetUtil.parseInetSocketAddress(s)); diff --git a/framework/src/main/java/org/tron/core/config/args/CLIParameter.java b/framework/src/main/java/org/tron/core/config/args/CLIParameter.java index b5bd0e2e85..4d68a6990c 100644 --- a/framework/src/main/java/org/tron/core/config/args/CLIParameter.java +++ b/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. + * + *

Parameters marked {@code @Deprecated} are scheduled for removal. + * Use the corresponding config-file options instead.

*/ @NoArgsConstructor public class CLIParameter { @@ -44,63 +47,78 @@ public class CLIParameter { @Parameter(names = {"--password"}, description = "password") public String password; + @Deprecated @Parameter(names = {"--solidity"}, description = "running a solidity node for java tron") public boolean solidityNode; @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; + @Deprecated @Parameter(names = {"--p2p-disable"}, description = "Switch for p2p module initialization. " + "(default: false)", arity = 1) public boolean p2pDisable; + @Deprecated @Parameter(description = "--seed-nodes") public List 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 +127,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; } From 84027da2487c6f55a05a1b2ab7bd9df44b5681f0 Mon Sep 17 00:00:00 2001 From: vividctrlalt Date: Mon, 16 Mar 2026 17:38:39 +0000 Subject: [PATCH 2/4] fix(config): add deprecated hints to --help output for CLI params Mark deprecated options with "(deprecated)" in help text and add a note below the Usage line that positional seedNode args are deprecated. --- .../java/org/tron/core/config/args/Args.java | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/framework/src/main/java/org/tron/core/config/args/Args.java b/framework/src/main/java/org/tron/core/config/args/Args.java index 475d229b11..533e7a663c 100644 --- a/framework/src/main/java/org/tron/core/config/args/Args.java +++ b/framework/src/main/java/org/tron/core/config/args/Args.java @@ -1698,6 +1698,9 @@ public static void printHelp(JCommander jCommander) { jCommander.getProgramName(); helpStr.append(String.format("%nUsage: java -jar %s [options] [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())); @@ -1719,9 +1722,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); } } From 5b0e37be7c7beaf443a7ce70939951a67cfdd475 Mon Sep 17 00:00:00 2001 From: vividctrlalt Date: Tue, 17 Mar 2026 12:56:30 +0000 Subject: [PATCH 3/4] fix(config): enrich deprecation warnings with config-key mapping - Add DEPRECATED_CLI_TO_CONFIG map for CLI-to-config key lookup - Show specific config key in warning for params that have equivalents - Use generic "will be removed" message for params without config equiv (--solidity, --p2p-disable) - Replace magic literal 3_000_000L with ENERGY_LIMIT_IN_CONSTANT_TX Addresses review feedback from warku123 and 3for on #6580. --- .../java/org/tron/core/config/args/Args.java | 55 +++++++++++++++++-- 1 file changed, 49 insertions(+), 6 deletions(-) diff --git a/framework/src/main/java/org/tron/core/config/args/Args.java b/framework/src/main/java/org/tron/core/config/args/Args.java index 533e7a663c..74d2c46b03 100644 --- a/framework/src/main/java/org/tron/core/config/args/Args.java +++ b/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,41 @@ @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 DEPRECATED_CLI_TO_CONFIG; + + static { + Map 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"); + m.put("--fast-forward", "node.fastForward"); + DEPRECATED_CLI_TO_CONFIG = Collections.unmodifiableMap(m); + } + @Getter private static String configFilePath = ""; @@ -152,7 +188,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)) { @@ -1008,10 +1044,17 @@ private static void applyCLIParams(CLIParameter cmd, JCommander jc) { return false; } }) - .forEach(pd -> logger.warn( - "CLI option '{}' is deprecated and will be removed in a future release. " - + "Please use the corresponding config-file option instead.", - pd.getLongestName())); + .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; @@ -1023,7 +1066,7 @@ private static void applyCLIParams(CLIParameter cmd, JCommander jc) { PARAMETER.supportConstant = cmd.supportConstant; } if (assigned.contains("--max-energy-limit-for-constant")) { - PARAMETER.maxEnergyLimitForConstant = max(3_000_000L, + PARAMETER.maxEnergyLimitForConstant = max(ENERGY_LIMIT_IN_CONSTANT_TX, cmd.maxEnergyLimitForConstant, true); } if (assigned.contains("--lru-cache-size")) { From 9d6027aa5b9cfc68133aaec7ec874e6614ffa486 Mon Sep 17 00:00:00 2001 From: vividctrlalt Date: Wed, 18 Mar 2026 04:17:55 +0000 Subject: [PATCH 4/4] fix(config): add event.subscribe.enable config key and remove incorrect --fast-forward mapping - Add event.subscribe.enable as config equivalent for deprecated --es CLI flag - Remove --fast-forward from CLI-to-config mapping (no config equivalent; fast-forward is a node runtime mode, not a config option) - Config reads event.subscribe.enable with CLI --es taking priority --- framework/src/main/java/org/tron/core/config/args/Args.java | 6 ++++-- .../src/main/java/org/tron/core/config/args/ConfigKey.java | 1 + framework/src/main/resources/config.conf | 1 + 3 files changed, 6 insertions(+), 2 deletions(-) diff --git a/framework/src/main/java/org/tron/core/config/args/Args.java b/framework/src/main/java/org/tron/core/config/args/Args.java index 74d2c46b03..2a80d6a14c 100644 --- a/framework/src/main/java/org/tron/core/config/args/Args.java +++ b/framework/src/main/java/org/tron/core/config/args/Args.java @@ -114,8 +114,7 @@ public class Args extends CommonParameter { 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"); - m.put("--fast-forward", "node.fastForward"); + m.put("--es", "event.subscribe.enable"); DEPRECATED_CLI_TO_CONFIG = Collections.unmodifiableMap(m); } @@ -697,6 +696,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); diff --git a/framework/src/main/java/org/tron/core/config/args/ConfigKey.java b/framework/src/main/java/org/tron/core/config/args/ConfigKey.java index dbb872febc..06dd7d9d57 100644 --- a/framework/src/main/java/org/tron/core/config/args/ConfigKey.java +++ b/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 = diff --git a/framework/src/main/resources/config.conf b/framework/src/main/resources/config.conf index 661a592e43..069b51286d 100644 --- a/framework/src/main/resources/config.conf +++ b/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