Merge bitcoin/bitcoin#36785: rpc: wallet: Add snake_case aliases for listunspent options
What changed, and why it matters
This change adds snake_case aliases (like minimum_amount) for existing camelCase options (like minimumAmount) in the listunspent RPC command. It also refactors some helper code so other wallet RPCs can reuse the same alias-handling logic. There is no security vulnerability here; it is a backward-compatible usability and consistency improvement.
No security action required. Treat as a normal code-quality/RPC-consistency merge.
Security signals we found
No strong security signals were identified.
Evidence from the diff
The commit introduces snake_case aliases for listunspent query_options and a shared GetOptionWithAlias helper that returns a pointer (nullptr if neither alias is present) instead of a reference. Existing camelCase names remain accepted, and using both names together now throws a clear RPC_INVALID_PARAMETER error. The spend.cpp refactor updates existing alias handling to use the new shared helper and adjusts InterpretSubtractFeeFromOutputInstructions to accept a pointer. No behavior changes that would affect consensus, wallet security, or RPC authorization.
Changed components
src/wallet/rpc/coins.cppsrc/wallet/rpc/spend.cppsrc/rpc/client.cpptest/functional/wallet_listtransactions.pyInspect captured patch +59 / −38
### doc/release-notes-listunspent-snake-case.md
@@ -0,0 +1,6 @@
+Updated RPCs
+------------
+
+- The `listunspent` RPC now accepts the snake_case `minimum_amount`,
+ `maximum_amount`, `maximum_count`, and `minimum_sum_amount` options as named
+ arguments. (#36785)
### src/rpc/client.cpp
@@ -147,9 +147,13 @@ static const CRPCConvertParam vRPCConvertParams[] =
{ "listunspent", 2, "addresses" },
{ "listunspent", 3, "include_unsafe" },
{ "listunspent", 4, "query_options" },
+ { "listunspent", 4, "minimum_amount" },
{ "listunspent", 4, "minimumAmount" },
+ { "listunspent", 4, "maximum_amount" },
{ "listunspent", 4, "maximumAmount" },
+ { "listunspent", 4, "maximum_count" },
{ "listunspent", 4, "maximumCount" },
+ { "listunspent", 4, "minimum_sum_amount" },
{ "listunspent", 4, "minimumSumAmount" },
{ "listunspent", 4, "include_immature_coinbase" },
{ "getblock", 1, "verbosity" },
### src/wallet/rpc/coins.cpp
@@ -454,6 +454,23 @@ RPCMethod getbalances()
};
}
+const UniValue* GetOptionWithAlias(
+ const UniValue& options,
+ const std::string& canonical_name,
+ const std::string& deprecated_name)
+{
+ if (options.exists(canonical_name) && options.exists(deprecated_name)) {
+ throw JSONRPCError(RPC_INVALID_PARAMETER, "Use " + canonical_name + " (" + deprecated_name + " is deprecated). Do not set both.");
+ }
+ if (options.exists(deprecated_name)) {
+ return &options[deprecated_name];
+ }
+ if (options.exists(canonical_name)) {
+ return &options[canonical_name];
+ }
+ return nullptr;
+}
+
RPCMethod listunspent()
{
return RPCMethod{
@@ -473,10 +490,10 @@ RPCMethod listunspent()
"See description of \"safe\" attribute below."},
{"query_options", RPCArg::Type::OBJ_NAMED_PARAMS, RPCArg::Optional::OMITTED, "",
{
- {"minimumAmount", RPCArg::Type::AMOUNT, RPCArg::Default{FormatMoney(0)}, "Minimum value of each UTXO in " + CURRENCY_UNIT + ""},
- {"maximumAmount", RPCArg::Type::AMOUNT, RPCArg::DefaultHint{"unlimited"}, "Maximum value of each UTXO in " + CURRENCY_UNIT + ""},
- {"maximumCount", RPCArg::Type::NUM, RPCArg::DefaultHint{"unlimited"}, "Maximum number of UTXOs"},
- {"minimumSumAmount", RPCArg::Type::AMOUNT, RPCArg::DefaultHint{"unlimited"}, "Minimum sum value of all UTXOs in " + CURRENCY_UNIT + ""},
+ {"minimum_amount|minimumAmount", RPCArg::Type::AMOUNT, RPCArg::Default{FormatMoney(0)}, "Minimum value of each UTXO in " + CURRENCY_UNIT + ""},
+ {"maximum_amount|maximumAmount", RPCArg::Type::AMOUNT, RPCArg::DefaultHint{"unlimited"}, "Maximum value of each UTXO in " + CURRENCY_UNIT + ""},
+ {"maximum_count|maximumCount", RPCArg::Type::NUM, RPCArg::DefaultHint{"unlimited"}, "Maximum number of UTXOs"},
+ {"minimum_sum_amount|minimumSumAmount", RPCArg::Type::AMOUNT, RPCArg::DefaultHint{"unlimited"}, "Minimum sum value of all UTXOs in " + CURRENCY_UNIT + ""},
{"include_immature_coinbase", RPCArg::Type::BOOL, RPCArg::Default{false}, "Include immature coinbase UTXOs"}
},
RPCArgOptions{.oneline_description="query_options"}},
@@ -515,8 +532,8 @@ RPCMethod listunspent()
HelpExampleCli("listunspent", "")
+ HelpExampleCli("listunspent", "6 9999999 \"[\\\"" + EXAMPLE_ADDRESS[0] + "\\\",\\\"" + EXAMPLE_ADDRESS[1] + "\\\"]\"")
+ HelpExampleRpc("listunspent", strprintf(R"(6, 9999999, ["%s","%s"])", EXAMPLE_ADDRESS[0], EXAMPLE_ADDRESS[1]))
- + HelpExampleCli("listunspent", "6 9999999 '[]' true '{ \"minimumAmount\": 0.005 }'")
- + HelpExampleRpc("listunspent", "6, 9999999, [] , true, { \"minimumAmount\": 0.005 } ")
+ + HelpExampleCli("listunspent", "6 9999999 '[]' true '{ \"minimum_amount\": 0.005 }'")
+ + HelpExampleRpc("listunspent", "6, 9999999, [] , true, { \"minimum_amount\": 0.005 } ")
},
[](const RPCMethod& self, const JSONRPCRequest& request) -> UniValue
{
@@ -551,25 +568,29 @@ RPCMethod listunspent()
RPCTypeCheckObj(options,
{
+ {"minimum_amount", UniValueType()},
{"minimumAmount", UniValueType()},
+ {"maximum_amount", UniValueType()},
{"maximumAmount", UniValueType()},
+ {"minimum_sum_amount", UniValueType()},
{"minimumSumAmount", UniValueType()},
+ {"maximum_count", UniValueType(UniValue::VNUM)},
{"maximumCount", UniValueType(UniValue::VNUM)},
{"include_immature_coinbase", UniValueType(UniValue::VBOOL)}
},
true, true);
- if (options.exists("minimumAmount"))
- filter_coins.min_amount = AmountFromValue(options["minimumAmount"]);
+ if (const UniValue* value = GetOptionWithAlias(options, "minimum_amount", "minimumAmount"))
+ filter_coins.min_amount = AmountFromValue(*value);
- if (options.exists("maximumAmount"))
- filter_coins.max_amount = AmountFromValue(options["maximumAmount"]);
+ if (const UniValue* value = GetOptionWithAlias(options, "maximum_amount", "maximumAmount"))
+ filter_coins.max_amount = AmountFromValue(*value);
- if (options.exists("minimumSumAmount"))
- filter_coins.min_sum_amount = AmountFromValue(options["minimumSumAmount"]);
+ if (const UniValue* value = GetOptionWithAlias(options, "minimum_sum_amount", "minimumSumAmount"))
+ filter_coins.min_sum_amount = AmountFromValue(*value);
- if (options.exists("maximumCount"))
- filter_coins.max_count = options["maximumCount"].getInt<int64_t>();
+ if (const UniValue* value = GetOptionWithAlias(options, "maximum_count", "maximumCount"))
+ filter_coins.max_count = value->getInt<int64_t>();
if (options.exists("include_immature_coinbase")) {
filter_coins.include_immature_coinbase = options["include_immature_coinbase"].get_bool();
### src/wallet/rpc/spend.cpp
@@ -69,12 +69,12 @@ static void InterpretFeeEstimationInstructions(const UniValue& conf_target, cons
}
}
-std::set<int> InterpretSubtractFeeFromOutputInstructions(const UniValue& sffo_instructions, const std::vector<std::string>& destinations)
+std::set<int> InterpretSubtractFeeFromOutputInstructions(const UniValue* sffo_instructions, const std::vector<std::string>& destinations)
{
std::set<int> sffo_set;
- if (sffo_instructions.isNull()) return sffo_set;
+ if (!sffo_instructions || sffo_instructions->isNull()) return sffo_set;
- for (const auto& sffo : sffo_instructions.getValues()) {
+ for (const auto& sffo : sffo_instructions->getValues()) {
int pos{-1};
if (sffo.isStr()) {
auto it = find(destinations.begin(), destinations.end(), sffo.get_str());
@@ -172,19 +172,10 @@ static void PreventOutdatedOptions(const UniValue& options)
}
}
-static const UniValue& GetOptionWithAlias(
+const UniValue* GetOptionWithAlias(
const UniValue& options,
const std::string& canonical_name,
- const std::string& deprecated_name)
-{
- if (options.exists(canonical_name) && options.exists(deprecated_name)) {
- throw JSONRPCError(RPC_INVALID_PARAMETER, strprintf("Use %s (%s is deprecated). Do not set both.", canonical_name, deprecated_name));
- }
- if (options.exists(deprecated_name)) {
- return options[deprecated_name];
- }
- return options[canonical_name];
-}
+ const std::string& deprecated_name);
UniValue SendMoney(CWallet& wallet, const CCoinControl &coin_control, std::vector<CRecipient> &recipients, std::optional<std::string> comment, std::optional<std::string> comment_to, bool verbose)
{
@@ -443,7 +434,7 @@ RPCMethod sendmany()
std::vector<CRecipient> recipients = CreateRecipients(
ParseOutputs(sendTo),
- InterpretSubtractFeeFromOutputInstructions(request.params[4], sendTo.getKeys())
+ InterpretSubtractFeeFromOutputInstructions(&request.params[4], sendTo.getKeys())
);
const bool verbose{self.Arg<bool>("verbose")};
@@ -540,9 +531,8 @@ CreatedTransactionResult FundTransaction(CWallet& wallet, const CMutableTransact
coinControl.m_allow_other_inputs = options["add_inputs"].get_bool();
}
- if (options.exists("changeAddress") || options.exists("change_address")) {
- const std::string change_address_str = GetOptionWithAlias(options, "change_address", "changeAddress").get_str();
- CTxDestination dest = DecodeDestination(change_address_str);
+ if (const UniValue* change_address = GetOptionWithAlias(options, "change_address", "changeAddress")) {
+ CTxDestination dest{DecodeDestination(change_address->get_str())};
if (!IsValidDestination(dest)) {
throw JSONRPCError(RPC_INVALID_ADDRESS_OR_KEY, "Change address must be a valid bitcoin address");
@@ -551,8 +541,8 @@ CreatedTransactionResult FundTransaction(CWallet& wallet, const CMutableTransact
coinControl.destChange = dest;
}
- if (options.exists("changePosition") || options.exists("change_position")) {
- int pos = GetOptionWithAlias(options, "change_position", "changePosition").getInt<int>();
+ if (const UniValue* change_position_option = GetOptionWithAlias(options, "change_position", "changePosition")) {
+ int pos = change_position_option->getInt<int>();
if (pos < 0 || (unsigned int)pos > recipients.size()) {
throw JSONRPCError(RPC_INVALID_PARAMETER, "changePosition out of bounds");
}
@@ -570,8 +560,8 @@ CreatedTransactionResult FundTransaction(CWallet& wallet, const CMutableTransact
}
}
- if (options.exists("lockUnspents") || options.exists("lock_unspents")) {
- lockUnspents = GetOptionWithAlias(options, "lock_unspents", "lockUnspents").get_bool();
+ if (const UniValue* lock_unspents = GetOptionWithAlias(options, "lock_unspents", "lockUnspents")) {
+ lockUnspents = lock_unspents->get_bool();
}
if (options.exists("include_unsafe")) {
@@ -1295,7 +1285,7 @@ RPCMethod send()
outputs = NormalizeOutputs(request.params[0]);
std::vector<CRecipient> recipients = CreateRecipients(
ParseOutputs(outputs),
- InterpretSubtractFeeFromOutputInstructions(options["subtract_fee_from_outputs"], outputs.getKeys())
+ InterpretSubtractFeeFromOutputInstructions(&options["subtract_fee_from_outputs"], outputs.getKeys())
);
CCoinControl coin_control;
coin_control.m_version = self.Arg<uint32_t>("version");
### test/functional/wallet_listtransactions.py
@@ -156,7 +156,7 @@ def normalize_list(txs):
def run_coinjoin_test(self):
self.log.info('Check "coin-join" transaction')
- input_0 = next(i for i in self.nodes[0].listunspent(query_options={"minimumAmount": 0.2}, include_unsafe=False))
+ input_0 = next(i for i in self.nodes[0].listunspent(minimum_amount=0.2, include_unsafe=False))
input_1 = next(i for i in self.nodes[1].listunspent(query_options={"minimumAmount": 0.2}, include_unsafe=False))
raw_hex = self.nodes[0].createrawtransaction(
inputs=[Why this scored 16/100
Community notes
Notes can correct, qualify, or add evidence to the AI analysis. Every note shown here has been validated by a human moderator.
The AI analysis stands alone for now. Submit a note if you can add evidence or important context.