bitcoin · ajtowns · Dec 5, 2023 · Nov 6, 2023 · Nov 6, 2023 · Nov 18, 2025
diff --git a/src/bitcoin-wallet.cpp b/src/bitcoin-wallet.cpp
@@ -36,14 +36,14 @@ static void SetupWalletToolArgs(ArgsManager& argsman)
     argsman.AddArg("-version", "Print version and exit", ArgsManager::ALLOW_ANY, OptionsCategory::OPTIONS);
     argsman.AddArg("-datadir=<dir>", "Specify data directory", ArgsManager::ALLOW_ANY | ArgsManager::DISALLOW_NEGATION, OptionsCategory::OPTIONS);
     argsman.AddArg("-wallet=<wallet-name>", "Specify wallet name", ArgsManager::ALLOW_ANY | ArgsManager::NETWORK_ONLY, OptionsCategory::OPTIONS);
-    argsman.AddArg("-dumpfile=<file name>", "When used with 'dump', writes out the records to this file. When used with 'createfromdump', loads the records into a new wallet.", ArgsManager::ALLOW_ANY | ArgsManager::DISALLOW_NEGATION, OptionsCategory::OPTIONS);
+    argsman.AddArg("-dumpfile=<file name>", "When used with 'dump', writes out the records to this file. When used with 'createfromdump', loads the records into a new wallet.", ArgsManager::ALLOW_ANY | ArgsManager::DISALLOW_NEGATION, OptionsCategory::COMMAND_OPTIONS);
-    argsman.AddArg("-dumpfile=<file name>", "When used with 'dump', writes out the records to this file. When used with 'createfromdump', loads the records into a new wallet.", ArgsManager::ALLOW_ANY | ArgsManager::DISALLOW_NEGATION, OptionsCategory::COMMAND_OPTIONS);
+    argsman.AddArg("-dumpfile=<file name>", "{'dump':'Writes out the records to this file.','createfromdump':'Loads the records into a new wallet.'}", ArgsManager::ALLOW_ANY | ArgsManager::DISALLOW_NEGATION, OptionsCategory::COMMAND_OPTIONS);```
-    argsman.AddArg("-dumpfile=<file name>", "When used with 'dump', writes out the records to this file. When used with 'createfromdump', loads the records into a new wallet.", ArgsManager::ALLOW_ANY | ArgsManager::DISALLOW_NEGATION, OptionsCategory::COMMAND_OPTIONS);
+    argsman.AddArg("-dumpfile=<file name>", "{'dump':'Writes out the records to this file.','createfromdump':'Loads the records into a new wallet.'}", ArgsManager::ALLOW_ANY | ArgsManager::DISALLOW_NEGATION, OptionsCategory::COMMAND_OPTIONS);```
     argsman.AddArg("-debug=<category>", "Output debugging information (default: 0).", ArgsManager::ALLOW_ANY, OptionsCategory::DEBUG_TEST);
     argsman.AddArg("-printtoconsole", "Send trace/debug info to console (default: 1 when no -debug is true, 0 otherwise).", ArgsManager::ALLOW_ANY, OptionsCategory::DEBUG_TEST);
 
     argsman.AddCommand("info", "Get wallet info");
     argsman.AddCommand("create", "Create a new descriptor wallet file");
-    argsman.AddCommand("dump", "Print out all of the wallet key-value records");
-    argsman.AddCommand("createfromdump", "Create new wallet file from dumped records");
+    argsman.AddCommand("dump", "Print out all of the wallet key-value records", {"-dumpfile"});
+    argsman.AddCommand("createfromdump", "Create new wallet file from dumped records", {"-dumpfile"});
 }
 
 static std::optional<int> WalletAppInit(ArgsManager& args, int argc, char* argv[])

diff --git a/src/common/args.cpp b/src/common/args.cpp
@@ -363,6 +363,31 @@ std::optional<const ArgsManager::Command> ArgsManager::GetCommand() const
     return ret;
 }
 
+bool ArgsManager::CheckCommandOptions(const std::string& command, std::vector<std::string>* errors) const
+{
+    LOCK(cs_args);
+
+    auto command_options = m_available_args.find(OptionsCategory::COMMAND_OPTIONS);
+    if (command_options == m_available_args.end()) return true;
+
+    const auto command_args = m_command_args.find(command);
+    auto is_valid_opt = [&](const auto& opt) EXCLUSIVE_LOCKS_REQUIRED(cs_args) -> bool {
+        if (command_args == m_command_args.end()) return false;
+        return command_args->second.contains(opt);
+    };
+
+    bool ok = true;
+    for (const auto& [arg, _] : command_options->second) {
+        if (!IsArgSet(arg)) continue;
+        if (is_valid_opt(arg)) continue;
+        if (errors != nullptr) {
+            errors->emplace_back(strprintf("The %s option cannot be used with the '%s' command.", arg, command));
+            ok = false;
+        }
+    }
+    return ok;
+}
+
 std::vector<std::string> ArgsManager::GetArgs(const std::string& strArg) const
 {
     std::vector<std::string> result;
@@ -553,7 +578,7 @@ void ArgsManager::ForceSetArg(const std::string& strArg, const std::string& strV
     m_settings.forced_settings[SettingName(strArg)] = strValue;
 }
 
-void ArgsManager::AddCommand(const std::string& cmd, const std::string& help)
+void ArgsManager::AddCommand(const std::string& cmd, const std::string& help, std::set<std::string>&& options)
 {
     Assert(cmd.find('=') == std::string::npos);
     Assert(cmd.at(0) != '-');
@@ -562,6 +587,9 @@ void ArgsManager::AddCommand(const std::string& cmd, const std::string& help)
     m_accept_any_command = false; // latch to false
     std::map<std::string, Arg>& arg_map = m_available_args[OptionsCategory::COMMANDS];
     auto ret = arg_map.emplace(cmd, Arg{"", help, ArgsManager::COMMAND});
+    if (!options.empty()) {
+        m_command_args.try_emplace(cmd, std::move(options));
+    }
     Assert(ret.second); // Fail on duplicate commands
 }
 
@@ -618,14 +646,46 @@ void ArgsManager::CheckMultipleCLIArgs() const
     }
 }
 
+namespace {
+/** Helper class for iterating over COMMAND_OPTIONS applicable to a given command */
+template <typename T>
+class CommandOptionsGetter
+{
+private:
+    const typename T::const_iterator m_end;
+    const typename T::const_iterator m_iter;
+public:
+    CommandOptionsGetter(const T& available_args)
+    : m_end{available_args.end()},
+      m_iter{available_args.find(OptionsCategory::COMMAND_OPTIONS)}
+    {
+    }
+
+    template <typename Fn>
+    void Iterate(const std::set<std::string>& select, bool with_debug, Fn&& fn) const
+    {
+        if (select.empty()) return;
+        if (m_iter == m_end) return;
+        for (const auto& [cmdopt_name, cmdopt_info] : m_iter->second) {
+            if (!with_debug && (cmdopt_info.m_flags & ArgsManager::DEBUG_ONLY)) continue;
+            if (!select.contains(cmdopt_name)) continue;
+            fn(cmdopt_name, cmdopt_info);
+        }
+    }
+};
+} // anonymous namespace
+
 std::string ArgsManager::GetHelpMessage() const
 {
     const bool show_debug = GetBoolArg("-help-debug", false);
 
     std::string usage;
     LOCK(cs_args);
-    for (const auto& arg_map : m_available_args) {
-        switch(arg_map.first) {
+
+    const auto command_options = CommandOptionsGetter(m_available_args);
+
+    for (const auto& [category, category_args] : m_available_args) {
+        switch(category) {
             case OptionsCategory::OPTIONS:
                 usage += HelpMessageGroup("Options:");
                 break;
@@ -671,22 +731,29 @@ std::string ArgsManager::GetHelpMessage() const
             case OptionsCategory::CLI_COMMANDS:
                 usage += HelpMessageGroup("CLI Commands:");
                 break;
+            case OptionsCategory::COMMAND_OPTIONS:
+                break;
             default:
                 break;
         }
 
+        if (category == OptionsCategory::COMMAND_OPTIONS) continue;
+
         // When we get to the hidden options, stop
-        if (arg_map.first == OptionsCategory::HIDDEN) break;
-
-        for (const auto& arg : arg_map.second) {
-            if (show_debug || !(arg.second.m_flags & ArgsManager::DEBUG_ONLY)) {
-                std::string name;
-                if (arg.second.m_help_param.empty()) {
-                    name = arg.first;
-                } else {
-                    name = arg.first + arg.second.m_help_param;
+        if (category == OptionsCategory::HIDDEN) break;
+
+        for (const auto& [arg_name, arg_info] : category_args) {
+            if (show_debug || !(arg_info.m_flags & ArgsManager::DEBUG_ONLY)) {
+                usage += HelpMessageOpt(arg_name, arg_info.m_help_param, arg_info.m_help_text);
+
+                if (category == OptionsCategory::COMMANDS) {
+                    const auto cmd_args = m_command_args.find(arg_name);
+                    if (cmd_args != m_command_args.end()) {
+                        command_options.Iterate(cmd_args->second, show_debug, [&](const auto& cmdopt_name, const auto& cmdopt_info) {
+                            usage += HelpMessageSubOpt(cmdopt_name, cmdopt_info.m_help_param, cmdopt_info.m_help_text);
+                        });
+                    }
                 }
-                usage += HelpMessageOpt(name, arg.second.m_help_text);
             }
         }
     }
@@ -712,11 +779,11 @@ std::string HelpMessageGroup(const std::string &message) {
     return std::string(message) + std::string("\n\n");
 }
 
-std::string HelpMessageOpt(const std::string &option, const std::string &message) {
-    return std::string(optIndent,' ') + std::string(option) +
-           std::string("\n") + std::string(msgIndent,' ') +
-           FormatParagraph(message, screenWidth - msgIndent, msgIndent) +
-           std::string("\n\n");
+std::string HelpMessageOpt(std::string_view option, std::string_view help_param, std::string_view message, int indent)
+{
+    return strprintf("%*s%s%s\n%*s%s\n\n",
+           (optIndent + indent), "", option, help_param,
+           (msgIndent + indent), "", FormatParagraph(message, screenWidth - msgIndent - indent, msgIndent + indent));
 }
 
 const std::vector<std::string> TEST_OPTIONS_DOC{
@@ -733,6 +800,11 @@ bool HasTestOption(const ArgsManager& args, const std::string& test_option)
     });
 }
 
+std::string HelpMessageSubOpt(std::string_view option, std::string_view help_param, std::string_view message)
+{
+    return HelpMessageOpt(option, help_param, message, msgIndent - optIndent);
+}
+
 fs::path GetDefaultDataDir()
 {
     // Windows:

diff --git a/src/common/args.h b/src/common/args.h
@@ -18,6 +18,7 @@
 #include <optional>
 #include <set>
 #include <string>
+#include <string_view>
 #include <variant>
 #include <vector>
 
@@ -66,6 +67,8 @@ enum class OptionsCategory {
     CLI_COMMANDS,
     IPC,
 
+    COMMAND_OPTIONS, // Specific to one or more commands
+
     HIDDEN // Always the last option to avoid printing these in the help
 };
 
@@ -138,6 +141,7 @@ class ArgsManager
     std::set<std::string> m_network_only_args GUARDED_BY(cs_args);
     std::map<OptionsCategory, std::map<std::string, Arg>> m_available_args GUARDED_BY(cs_args);
     std::optional<unsigned int> m_default_flags GUARDED_BY(cs_args){};
+    std::map<std::string, std::set<std::string>> m_command_args GUARDED_BY(cs_args);
     bool m_accept_any_command GUARDED_BY(cs_args){true};
     std::list<SectionInfo> m_config_sections GUARDED_BY(cs_args);
     std::optional<fs::path> m_config_path GUARDED_BY(cs_args);
@@ -213,6 +217,11 @@ class ArgsManager
      */
     std::optional<const Command> GetCommand() const;
 
+    /**
+     * Check for invalid command options
+     */
+    bool CheckCommandOptions(const std::string& command, std::vector<std::string>* errors = nullptr) const;
+
     /**
      * Get blocks directory path
      *
@@ -348,9 +357,9 @@ class ArgsManager
     void AddArg(const std::string& name, const std::string& help, unsigned int flags, const OptionsCategory& cat);
 
     /**
-     * Add subcommand
+     * Add command
      */
-    void AddCommand(const std::string& cmd, const std::string& help);
+    void AddCommand(const std::string& cmd, const std::string& help, std::set<std::string>&& options={});
 
     /**
      * Add many hidden arguments
@@ -474,10 +483,22 @@ std::string HelpMessageGroup(const std::string& message);
 /**
  * Format a string to be used as option description in help messages
  *
- * @param option Option message (e.g. "-rpcuser=<user>")
+ * @param option Option name (e.g. "-rpcuser")
+ * @param help_param Help parameter (e.g. "=<user>" or "")
+ * @param message Option description (e.g. "Username for JSON-RPC connections")
+ * @param indent Additional indentation
+ * @return the formatted string
+ */
+std::string HelpMessageOpt(std::string_view option, std::string_view help_param, std::string_view message, int indent=0);
+
+/**
+ * Same as HelpMessageOpt, but indents for command-specific options
+ *
+ * @param option Option name (e.g. "-rpcuser")
+ * @param help_param Help parameter (e.g. "=<user>" or "")
  * @param message Option description (e.g. "Username for JSON-RPC connections")
  * @return the formatted string
  */
-std::string HelpMessageOpt(const std::string& option, const std::string& message);
+std::string HelpMessageSubOpt(std::string_view option, std::string_view help_param, std::string_view message);
 
 #endif // BITCOIN_COMMON_ARGS_H
diff --git a/src/test/argsman_tests.cpp b/src/test/argsman_tests.cpp
@@ -640,6 +640,51 @@ BOOST_AUTO_TEST_CASE(util_GetArg)
     BOOST_CHECK_EQUAL(testArgs.GetArg("pritest4", "default"), "b");
 }
 
+BOOST_AUTO_TEST_CASE(util_AddCommand)
+{
+    enum TestFail { SUCCESS, PARSE_FAIL, PARSE_ERROR, NO_COMMAND, COMMAND_OPTS };
+
+    auto testfn = [&](const auto& argv) -> TestFail {
+        TestArgsManager test_args;
+        test_args.AddArg("-opt1=<file name>", "Opt 1", ArgsManager::ALLOW_ANY | ArgsManager::DISALLOW_NEGATION, OptionsCategory::COMMAND_OPTIONS);
+        test_args.AddArg("-opt2=<file name>", "Opt 2", ArgsManager::ALLOW_ANY | ArgsManager::DISALLOW_NEGATION, OptionsCategory::COMMAND_OPTIONS);
+        test_args.AddArg("-opt3=<file name>", "Opt 3", ArgsManager::ALLOW_ANY | ArgsManager::DISALLOW_NEGATION, OptionsCategory::OPTIONS);
+
+        test_args.AddCommand("cmd1", "No specific options");
+        test_args.AddCommand("cmd2", "Opt 1", {"-opt1"});
+        test_args.AddCommand("cmd3", "Opt 1 or 2", {"-opt1", "-opt2"});
+
+        std::string error;
+        if (!test_args.ParseParameters(argv.size(), argv.data(), error)) return PARSE_FAIL;
+        if (!error.empty()) return PARSE_ERROR;
+        const auto command = test_args.GetCommand();
+        if (!command) return NO_COMMAND;
+        std::vector<std::string> details;
+        if (!test_args.CheckCommandOptions(command->command, &details)) return COMMAND_OPTS;
+        return SUCCESS;
+    };
+
+    BOOST_CHECK_EQUAL(COMMAND_OPTS, testfn(std::array{"x", "-opt1=foo", "cmd1"}));
+    BOOST_CHECK_EQUAL(SUCCESS,      testfn(std::array{"x", "cmd1", "-opt1=foo"})); // things after the command are "args" and left unparsed, not options
+
+    BOOST_CHECK_EQUAL(SUCCESS,      testfn(std::array{"x", "-opt1=foo", "cmd2"}));
+    BOOST_CHECK_EQUAL(SUCCESS,      testfn(std::array{"x", "-opt1=foo", "cmd3"}));
+    BOOST_CHECK_EQUAL(COMMAND_OPTS, testfn(std::array{"x", "-opt2=foo", "cmd1"}));
+    BOOST_CHECK_EQUAL(COMMAND_OPTS, testfn(std::array{"x", "-opt2=foo", "cmd2"}));
+    BOOST_CHECK_EQUAL(SUCCESS,      testfn(std::array{"x", "-opt2=foo", "cmd3"}));
+    BOOST_CHECK_EQUAL(SUCCESS,      testfn(std::array{"x", "-opt3=foo", "cmd1"}));
+    BOOST_CHECK_EQUAL(SUCCESS,      testfn(std::array{"x", "-opt3=foo", "cmd2"}));
+    BOOST_CHECK_EQUAL(SUCCESS,      testfn(std::array{"x", "-opt3=foo", "cmd3"}));
+
+    BOOST_CHECK_EQUAL(COMMAND_OPTS, testfn(std::array{"x", "-opt1=foo", "-opt3=bar", "-opt2=baz", "cmd1"}));
+    BOOST_CHECK_EQUAL(COMMAND_OPTS, testfn(std::array{"x", "-opt1=foo", "-opt3=bar", "-opt2=baz", "cmd2"}));
+    BOOST_CHECK_EQUAL(SUCCESS,      testfn(std::array{"x", "-opt1=foo", "-opt3=bar", "-opt2=baz", "cmd3"}));
+
+    BOOST_CHECK_EQUAL(PARSE_FAIL,   testfn(std::array{"x", "cmd4"}));
+    BOOST_CHECK_EQUAL(NO_COMMAND,   testfn(std::array{"x", "-opt3=foo"}));
+    BOOST_CHECK_EQUAL(PARSE_FAIL,   testfn(std::array{"x", "-opt4=foo"}));
+}
+
 BOOST_AUTO_TEST_CASE(util_GetChainTypeString)
 {
     TestArgsManager test_args;

diff --git a/src/test/fuzz/string.cpp b/src/test/fuzz/string.cpp
@@ -68,7 +68,8 @@ FUZZ_TARGET(string)
     (void)HelpExampleCli(random_string_1, random_string_2);
     (void)HelpExampleRpc(random_string_1, random_string_2);
     (void)HelpMessageGroup(random_string_1);
-    (void)HelpMessageOpt(random_string_1, random_string_2);
+    (void)HelpMessageOpt(random_string_1, "", random_string_2);
+    (void)HelpMessageOpt(random_string_1, random_string_2, "");
     (void)IsDeprecatedRPCEnabled(random_string_1);
     (void)Join(random_string_vector, random_string_1);
     (void)JSONRPCError(fuzzed_data_provider.ConsumeIntegral<int>(), random_string_1);

diff --git a/src/wallet/wallettool.cpp b/src/wallet/wallettool.cpp
@@ -107,9 +107,12 @@ static void WalletShowInfo(CWallet* wallet_instance)
 
 bool ExecuteWalletToolFunc(const ArgsManager& args, const std::string& command)
 {
-    if (args.IsArgSet("-dumpfile") && command != "dump" && command != "createfromdump") {
-        tfm::format(std::cerr, "The -dumpfile option can only be used with the \"dump\" and \"createfromdump\" commands.\n");
-        return false;
+    {
+        std::vector<std::string> details;
+        if (!args.CheckCommandOptions(command, &details)) {
+            tfm::format(std::cerr, "Error: Invalid arguments provided:\n%s\n", util::MakeUnorderedList(details));
+            return false;
+        }
     }
     if (command == "create" && !args.IsArgSet("-wallet")) {
         tfm::format(std::cerr, "Wallet name must be provided when creating a new wallet.\n");

diff --git a/test/functional/tool_wallet.py b/test/functional/tool_wallet.py
@@ -420,6 +420,7 @@ def test_no_create_legacy(self):
         assert not (self.nodes[0].wallets_path / "legacy").exists()
         self.assert_raises_tool_error("Invalid parameter -descriptors", "-wallet=legacy", "-descriptors=false", "create")
         assert not (self.nodes[0].wallets_path / "legacy").exists()
+        self.assert_raises_tool_error("The -dumpfile option cannot be used with the 'create' command.", "-wallet=legacy", "-dumpfile=wallet.dump", "create")
 
     def run_test(self):
         self.wallet_path = self.nodes[0].wallets_path / self.default_wallet_name / self.wallet_data_filename