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

Merged
kuny0707 merged 6 commits into from
Mar 26, 2026
Merged

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

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
6 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
9d6027a
fix(config): add event.subscribe.enable config key and remove incorre…
vividctrlalt Mar 18, 2026
75b1d10
test(config): add tests for event.subscribe.enable and CLI --es override
vividctrlalt Mar 20, 2026
e197a03
fix(config): keep --solidity and --p2p-disable as active CLI params
vividctrlalt Mar 25, 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
23 changes: 22 additions & 1 deletion 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 @@ -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.",
Copy link
Copy Markdown

@warku123 warku123 Mar 17, 2026 •
edited
Loading

Choose a reason for hiding this comment

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

Consider enriching the warning message with the specific config-file key mapping so users know exactly how to migrate.

And if we implement this, it's necessary to add a static map like this:

private static final Map<String, String> DEPRECATED_CLI_TO_CONFIG = Map.ofEntries(
    Map.entry("--storage-db-directory", "storage.db.directory"),
    Map.entry("--storage-db-engine", "storage.db.engine"),
    Map.entry("--storage-db-synchronous", "storage.db.synchronous"),
    // add remaining params...
);

And change this log like this:

   .forEach(pd -> {
      String cliOption = pd.getLongestName();
      String configKey = DEPRECATED_CLI_TO_CONFIG.get(cliOption);
      String suggestion = configKey != null 
          ? String.format(" Please use config key '%s' instead.", configKey)
          : " Please use the corresponding config-file option instead.";
      logger.warn("CLI option '{}' is deprecated and will be removed in a future release.{}",
          cliOption, suggestion);
    });

Copy link
Copy Markdown
Contributor Author

@vividctrlalt vividctrlalt Mar 17, 2026

Choose a reason for hiding this comment

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

Good suggestion! Added a DEPRECATED_CLI_TO_CONFIG map that provides specific config-key hints in deprecation warnings.

For params with a config equivalent:
CLI option '--storage-db-engine' is deprecated and will be removed in a future release. Please use config key 'storage.db.engine' instead.

For params without a config equivalent (--solidity, --p2p-disable):
CLI option '--solidity' is deprecated and will be removed in a future release.

This also addresses @3for's concern about misleading messages. See 5b0e37b.

Copy link
Copy Markdown
Collaborator

@3for 3for Mar 17, 2026

Choose a reason for hiding this comment

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

Some deprecated CLI parameters (e.g., --solidity, --p2p-disable, --es, --fast-forward) have no equivalent "config-file option" in .conf, making the message “Please use the corresponding config-file option instead” misleading.

Copy link
Copy Markdown
Contributor Author

@vividctrlalt vividctrlalt Mar 17, 2026

Choose a reason for hiding this comment

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

Valid point. Params like --solidity and --p2p-disable have no config-file equivalent — they are runtime mode switches being phased out entirely. The warning now omits the "use config-file option" suggestion for these params and simply states they will be removed. See 5b0e37b.

pd.getLongestName()));

if (assigned.contains("--output-directory")) {
PARAMETER.outputDirectory = cmd.outputDirectory;
}
Expand All @@ -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,
Copy link
Copy Markdown

@warku123 warku123 Mar 17, 2026 •
edited
Loading

Choose a reason for hiding this comment

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

I noticed that 3_000_000L is already defined as ENERGY_LIMIT_IN_CONSTANT_TX in Constant.java:

// In common/src/main/java/org/tron/core/Constant.java
public static final long ENERGY_LIMIT_IN_CONSTANT_TX = 3_000_000L;

Would it make sense to reuse this constant here instead of the inline literal?

Copy link
Copy Markdown
Contributor Author

@vividctrlalt vividctrlalt Mar 17, 2026

Choose a reason for hiding this comment

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

Good catch! Replaced both occurrences of 3_000_000L with ENERGY_LIMIT_IN_CONSTANT_TX from Constant.java. See 5b0e37b.

cmd.maxEnergyLimitForConstant, true);
}
if (assigned.contains("--lru-cache-size")) {
PARAMETER.lruCacheSize = cmd.lruCacheSize;
Expand Down Expand Up @@ -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. "
Copy link
Copy Markdown
Collaborator

@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
Copy Markdown
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
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;
Copy link
Copy Markdown

@liuyifei001 liuyifei001 Mar 24, 2026

Choose a reason for hiding this comment

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

SolidityNode.jar is no longer generated during the build process, but the --solidity option is still in use, particularly in synchronization scenarios. Since this command-line parameter has no equivalent configuration item in the config file, it should not be marked as deprecated.

Copy link
Copy Markdown
Contributor Author

@vividctrlalt vividctrlalt Mar 25, 2026

Choose a reason for hiding this comment

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

Agreed. --solidity is a runtime mode switch that determines an entirely different execution path (SolidityNode.start() vs FullNode), not a configuration parameter. It has no config-file equivalent and shouldn't have one — it's choosing which program to run, not how to configure it. Will remove the deprecated annotation.


@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;
Copy link
Copy Markdown

@liuyifei001 liuyifei001 Mar 24, 2026

Choose a reason for hiding this comment

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

The --p2p-disable command-line option also has no equivalent configuration item in the config file and remains useful in certain scenarios. For example, when used together with shutdown, it allows querying the state information of a specific block. Therefore, it should not be marked as deprecated.

Copy link
Copy Markdown
Contributor Author

@vividctrlalt vividctrlalt Mar 25, 2026

Choose a reason for hiding this comment

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

Agreed. --p2p-disable is also a runtime mode switch — it starts the node in offline/local-query mode without P2P networking. This is a distinct execution mode, not a tunable config parameter. Will remove the deprecated annotation as well.


@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