Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
vividctrlalt wants to merge 3 commits into
base: develop
Choose a base branch
from
+114 −5
Open

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
f55e9cf
fix(config): deprecate CLI params and add safety guardrails for #6569…
vividctrlalt Mar 16, 2026
84027da
fix(config): add deprecated hints to --help output for CLI params
vividctrlalt Mar 16, 2026
5b0e37b
fix(config): enrich deprecation warnings with config-key mapping
vividctrlalt Mar 17, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
85 changes: 82 additions & 3 deletions framework/src/main/java/org/tron/core/config/args/Args.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down Expand Up @@ -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<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");
m.put("--fast-forward", "node.fastForward");
DEPRECATED_CLI_TO_CONFIG = Collections.unmodifiableMap(m);
}

@Getter
private static String configFilePath = "";

Expand Down Expand Up @@ -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)) {
Expand Down Expand Up @@ -998,6 +1034,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;
}
Expand All @@ -1008,7 +1066,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;
Expand Down Expand Up @@ -1091,7 +1150,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. "
Copy link

@3for 3for Mar 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since seedNodes is deprecated, the corresponding help info should also be removed, such as: helpStr.append(String.format("%nUsage: java -jar %s [options] [seedNode ...]%n", programName));

Copy link
Contributor Author

@vividctrlalt vividctrlalt Mar 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the feedback! Since seedNodes is deprecated but not yet removed, users may still want to use it, so I kept the Usage line but added a deprecation note right below it. Also noticed that --es and --solidity in the help output are deprecated too (marked in this PR), so I added (deprecated) hints to all deprecated options in the help text. See 84027da.

+ "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));
Expand Down Expand Up @@ -1677,6 +1741,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()));

Expand All @@ -1698,9 +1765,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);
}
}
Expand Down
34 changes: 32 additions & 2 deletions framework/src/main/java/org/tron/core/config/args/CLIParameter.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand Down Expand Up @@ -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<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;
Expand All @@ -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;
}
Loading