fix(config): deprecate CLI params and add guardrails by vividctrlalt · Pull Request #6580 · tronprotocol/java-tron

vividctrlalt · 2026-03-16T07:24:49Z

Summary

Follow-up to #6569 review feedback:

Deprecate 23 CLI parameters that can be replaced by config-file options, marking them with @Deprecated in CLIParameter and logging runtime warnings via reflection when used
Add max(3_000_000L, ...) guardrail for --max-energy-limit-for-constant CLI path, consistent with config-file validation (addresses @waynercheung's review in refactor(config): extract CLIParameter and restructure Args init flow #6569)
Document seedNodes positional parameter behavior with comment explaining why isEmpty() is used instead of isAssigned(), plus deprecation warning

Retained CLI params (11)

-c, -d, --log-config, -h, -v, -w, -p, --witness-address, --password, --keystore-factory, --debug

Deprecated CLI params (23)

All storage, VM, network/thread, and misc runtime parameters — these should be configured via config file.

Test plan

./gradlew compileJava — all modules compile successfully
All CI checks passed on fork PR (fix(config): deprecate CLI params and add safety guardrails vividctrlalt/java-tron#11)
./gradlew :framework:test --tests "org.tron.core.config.args.*" — parameter tests pass
./gradlew :framework:test — full framework tests pass

Fixes review comments from refactor(config): extract CLIParameter and restructure Args init flow #6569
Addresses @waynercheung's feedback on CLI validation consistency
Addresses @halibobo1205's note on seedNodes positional parameter (CLI flags silently overridden by config file for 13 parameters #6567)

@deprecated

…rotocol#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

3for · 2026-03-16T11:30:01Z

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

+    // 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. "


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));

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.

Mark deprecated options with "(deprecated)" in help text and add a note below the Usage line that positional seedNode args are deprecated.

warku123 · 2026-03-17T07:27:02Z

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

+        })
+        .forEach(pd -> logger.warn(
+            "CLI option '{}' is deprecated and will be removed in a future release. "
+                + "Please use the corresponding config-file option instead.",


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); });

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.

warku123 · 2026-03-17T07:43:10Z

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

    }
    if (assigned.contains("--max-energy-limit-for-constant")) {
-      PARAMETER.maxEnergyLimitForConstant = cmd.maxEnergyLimitForConstant;
+      PARAMETER.maxEnergyLimitForConstant = max(3_000_000L,


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?

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

3for · 2026-03-17T08:04:01Z

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

+        })
+        .forEach(pd -> logger.warn(
+            "CLI option '{}' is deprecated and will be removed in a future release. "
+                + "Please use the corresponding config-file option instead.",


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.

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.

- 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 tronprotocol#6580.

vividctrlalt changed the title ~~fix(config): deprecate CLI params and add safety guardrails (#6569 follow-up)~~ fix(config): deprecate CLI params and add guardrails Mar 16, 2026

3for reviewed Mar 16, 2026

View reviewed changes

fix(config): add deprecated hints to --help output for CLI params

84027da

Mark deprecated options with "(deprecated)" in help text and add a note below the Usage line that positional seedNode args are deprecated.

warku123 reviewed Mar 17, 2026

View reviewed changes

3for reviewed Mar 17, 2026

View reviewed changes

vividctrlalt force-pushed the fix/pr6569-review-followup branch from 731abdb to 5b0e37b Compare March 17, 2026 13:07

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

fix(config): deprecate CLI params and add guardrails#6580
vividctrlalt wants to merge 3 commits intotronprotocol:developfrom
vividctrlalt:fix/pr6569-review-followup

vividctrlalt commented Mar 16, 2026

Uh oh!

3for Mar 16, 2026

Uh oh!

vividctrlalt Mar 16, 2026

Uh oh!

warku123 Mar 17, 2026 •

edited

Loading

Uh oh!

vividctrlalt Mar 17, 2026

Uh oh!

warku123 Mar 17, 2026 •

edited

Loading

Uh oh!

vividctrlalt Mar 17, 2026

Uh oh!

3for Mar 17, 2026

Uh oh!

vividctrlalt Mar 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

vividctrlalt commented Mar 16, 2026

Summary

Retained CLI params (11)

Deprecated CLI params (23)

Test plan

Related

Uh oh!

3for Mar 16, 2026

Choose a reason for hiding this comment

Uh oh!

vividctrlalt Mar 16, 2026

Choose a reason for hiding this comment

Uh oh!

warku123 Mar 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

vividctrlalt Mar 17, 2026

Choose a reason for hiding this comment

Uh oh!

warku123 Mar 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

vividctrlalt Mar 17, 2026

Choose a reason for hiding this comment

Uh oh!

3for Mar 17, 2026

Choose a reason for hiding this comment

Uh oh!

vividctrlalt Mar 17, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

warku123 Mar 17, 2026 •

edited

Loading

warku123 Mar 17, 2026 •

edited

Loading