Merge bitcoin/bitcoin#36489: wallet: rpc: Add snake_case aliases for wallet funding options
What changed, and why it matters
This update fixes a quirk in Bitcoin Core's wallet commands where some option names using underscores (like subtract_fee_from_outputs) were accepted by the server but not properly handled by the command-line tool or documentation. More importantly, the server was silently ignoring subtract_fee_from_outputs, meaning a user who thought they had told the wallet to deduct the transaction fee from a recipient's payment would actually end up paying the fee themselves. The patch also now rejects supplying both the old camelCase name and the new snake_case name at the same time, preventing confusion. It is a bug fix with a mild financial-impact risk rather than a direct theft or remote-code-execution vulnerability.
Treat as a low-severity wallet bug fix. Users and integrators relying on fundrawtransaction or walletcreatefundedpsbt with snake_case options should upgrade to ensure subtract_fee_from_outputs is honored and to avoid ambiguous parameter errors. No emergency response is warranted; review release notes for the new alias behavior.
Security signals we found
Silent option ignore bug fixed: subtract_fee_from_outputs was previously parsed but not acted on, causing unintended fee payer behavior
New helper GetOptionWithAlias enforces that canonical and deprecated option names cannot both be supplied, preventing ambiguous parameter handling
CLI conversion table and help docs updated to recognize snake_case aliases, reducing mismatches between client and server parameter handling
Functional tests added for duplicate subtract_fee_from_outputs/subtractFeeFromOutputs error and existing tests migrated to snake_case aliases
Evidence from the diff
The commit merges PR #36489, which adds snake_case aliases (change_address, change_position, lock_unspents, subtract_fee_from_outputs) for fundrawtransaction and walletcreatefundedpsbt options in bitcoin-cli conversion tables, RPC help text, and JSON schemas. It introduces GetOptionWithAlias() to read either the canonical snake_case or deprecated camelCase value and throw RPC_INVALID_PARAMETER if both are supplied. The key functional fix is that FundTransaction now reads options[“subtract_fee_from_outputs”] instead of always reading options[“subtractFeeFromOutputs”], which previously caused the snake_case form to be silently ignored. Tests are updated to exercise the new aliases and the mutual-exclusion error.
Changed components
src/rpc/client.cppsrc/wallet/rpc/spend.cppfundrawtransaction RPCwalletcreatefundedpsbt RPCbitcoin-cli parameter conversion for wallet funding optionsInspect captured patch +54 / −18
### doc/release-notes-36489.md
@@ -0,0 +1,7 @@
+Updated RPCs
+------------
+
+- The `fundrawtransaction` and `walletcreatefundedpsbt` RPCs now support the
+ snake_case `change_address`, `change_position`, `lock_unspents`, and
+ `subtract_fee_from_outputs` options as named parameters. Previously,
+ `subtract_fee_from_outputs` was silently ignored.
### src/rpc/client.cpp
@@ -183,11 +183,14 @@ static const CRPCConvertParam vRPCConvertParams[] =
{ "fundrawtransaction", 1, "minconf"},
{ "fundrawtransaction", 1, "maxconf"},
{ "fundrawtransaction", 1, "changePosition"},
+ { "fundrawtransaction", 1, "change_position"},
{ "fundrawtransaction", 1, "includeWatching"},
{ "fundrawtransaction", 1, "lockUnspents"},
+ { "fundrawtransaction", 1, "lock_unspents"},
{ "fundrawtransaction", 1, "fee_rate"},
{ "fundrawtransaction", 1, "feeRate"},
{ "fundrawtransaction", 1, "subtractFeeFromOutputs"},
+ { "fundrawtransaction", 1, "subtract_fee_from_outputs"},
{ "fundrawtransaction", 1, "input_weights"},
{ "fundrawtransaction", 1, "conf_target"},
{ "fundrawtransaction", 1, "replaceable"},
@@ -203,11 +206,14 @@ static const CRPCConvertParam vRPCConvertParams[] =
{ "walletcreatefundedpsbt", 3, "minconf"},
{ "walletcreatefundedpsbt", 3, "maxconf"},
{ "walletcreatefundedpsbt", 3, "changePosition"},
+ { "walletcreatefundedpsbt", 3, "change_position"},
{ "walletcreatefundedpsbt", 3, "includeWatching"},
{ "walletcreatefundedpsbt", 3, "lockUnspents"},
+ { "walletcreatefundedpsbt", 3, "lock_unspents"},
{ "walletcreatefundedpsbt", 3, "fee_rate"},
{ "walletcreatefundedpsbt", 3, "feeRate"},
{ "walletcreatefundedpsbt", 3, "subtractFeeFromOutputs"},
+ { "walletcreatefundedpsbt", 3, "subtract_fee_from_outputs"},
{ "walletcreatefundedpsbt", 3, "conf_target"},
{ "walletcreatefundedpsbt", 3, "replaceable"},
{ "walletcreatefundedpsbt", 3, "solving_data"},
### src/wallet/rpc/spend.cpp
@@ -172,6 +172,20 @@ static void PreventOutdatedOptions(const UniValue& options)
}
}
+static 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];
+}
+
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)
{
EnsureWalletIsUnlocked(wallet);
@@ -527,7 +541,7 @@ CreatedTransactionResult FundTransaction(CWallet& wallet, const CMutableTransact
}
if (options.exists("changeAddress") || options.exists("change_address")) {
- const std::string change_address_str = (options.exists("change_address") ? options["change_address"] : options["changeAddress"]).get_str();
+ const std::string change_address_str = GetOptionWithAlias(options, "change_address", "changeAddress").get_str();
CTxDestination dest = DecodeDestination(change_address_str);
if (!IsValidDestination(dest)) {
@@ -538,7 +552,7 @@ CreatedTransactionResult FundTransaction(CWallet& wallet, const CMutableTransact
}
if (options.exists("changePosition") || options.exists("change_position")) {
- int pos = (options.exists("change_position") ? options["change_position"] : options["changePosition"]).getInt<int>();
+ int pos = GetOptionWithAlias(options, "change_position", "changePosition").getInt<int>();
if (pos < 0 || (unsigned int)pos > recipients.size()) {
throw JSONRPCError(RPC_INVALID_PARAMETER, "changePosition out of bounds");
}
@@ -557,7 +571,7 @@ CreatedTransactionResult FundTransaction(CWallet& wallet, const CMutableTransact
}
if (options.exists("lockUnspents") || options.exists("lock_unspents")) {
- lockUnspents = (options.exists("lock_unspents") ? options["lock_unspents"] : options["lockUnspents"]).get_bool();
+ lockUnspents = GetOptionWithAlias(options, "lock_unspents", "lockUnspents").get_bool();
}
if (options.exists("include_unsafe")) {
@@ -716,7 +730,7 @@ RPCMethod fundrawtransaction()
"fundrawtransaction",
"If the transaction has no inputs, they will be automatically selected to meet its out value.\n"
"It will add at most one change output to the outputs.\n"
- "No existing outputs will be modified unless \"subtractFeeFromOutputs\" is specified.\n"
+ "No existing outputs will be modified unless \"subtract_fee_from_outputs\" is specified.\n"
"Note that inputs which were signed may need to be resigned after completion since in/outputs have been added.\n"
"The inputs added will not be signed, use signrawtransactionwithkey\n"
"or signrawtransactionwithwallet for that.\n"
@@ -739,14 +753,14 @@ RPCMethod fundrawtransaction()
"If that happens, you will need to fund the transaction with different inputs and republish it."},
{"minconf", RPCArg::Type::NUM, RPCArg::Default{0}, "If add_inputs is specified, require inputs with at least this many confirmations."},
{"maxconf", RPCArg::Type::NUM, RPCArg::Optional::OMITTED, "If add_inputs is specified, require inputs with at most this many confirmations."},
- {"changeAddress", RPCArg::Type::STR, RPCArg::DefaultHint{"automatic"}, "The bitcoin address to receive the change"},
- {"changePosition", RPCArg::Type::NUM, RPCArg::DefaultHint{"random"}, "The index of the change output"},
+ {"change_address|changeAddress", RPCArg::Type::STR, RPCArg::DefaultHint{"automatic"}, "The bitcoin address to receive the change"},
+ {"change_position|changePosition", RPCArg::Type::NUM, RPCArg::DefaultHint{"random"}, "The index of the change output"},
{"change_type", RPCArg::Type::STR, RPCArg::DefaultHint{"set by -changetype"}, "The output type to use. Only valid if changeAddress is not specified. Options are " + FormatAllOutputTypes() + "."},
{"includeWatching", RPCArg::Type::BOOL, RPCArg::Default{false}, "(DEPRECATED) No longer used"},
- {"lockUnspents", RPCArg::Type::BOOL, RPCArg::Default{false}, "Lock selected unspent outputs"},
+ {"lock_unspents|lockUnspents", RPCArg::Type::BOOL, RPCArg::Default{false}, "Lock selected unspent outputs"},
{"fee_rate", RPCArg::Type::AMOUNT, RPCArg::DefaultHint{"not set, fall back to wallet fee estimation"}, "Specify a fee rate in " + CURRENCY_ATOM + "/vB."},
{"feeRate", RPCArg::Type::AMOUNT, RPCArg::DefaultHint{"not set, fall back to wallet fee estimation"}, "Specify a fee rate in " + CURRENCY_UNIT + "/kvB."},
- {"subtractFeeFromOutputs", RPCArg::Type::ARR, RPCArg::Default{UniValue::VARR}, "The integers.\n"
+ {"subtract_fee_from_outputs|subtractFeeFromOutputs", RPCArg::Type::ARR, RPCArg::Default{UniValue::VARR}, "The output indices to subtract the fee from.\n"
"The fee will be equally deducted from the amount of each specified output.\n"
"Those recipients will receive less bitcoins than you enter in their corresponding amount field.\n"
"If no outputs are specified here, the sender pays the fee.",
@@ -824,7 +838,8 @@ RPCMethod fundrawtransaction()
std::vector<std::string> dummy(destinations.size(), "dummy");
std::vector<CRecipient> recipients = CreateRecipients(
destinations,
- InterpretSubtractFeeFromOutputInstructions(options["subtractFeeFromOutputs"], dummy)
+ InterpretSubtractFeeFromOutputInstructions(
+ GetOptionWithAlias(options, "subtract_fee_from_outputs", "subtractFeeFromOutputs"), dummy)
);
CCoinControl coin_control;
// Automatically select (additional) coins. Can be overridden by options.add_inputs.
@@ -1745,14 +1760,14 @@ RPCMethod walletcreatefundedpsbt()
"If that happens, you will need to fund the transaction with different inputs and republish it."},
{"minconf", RPCArg::Type::NUM, RPCArg::Default{0}, "If add_inputs is specified, require inputs with at least this many confirmations."},
{"maxconf", RPCArg::Type::NUM, RPCArg::Optional::OMITTED, "If add_inputs is specified, require inputs with at most this many confirmations."},
- {"changeAddress", RPCArg::Type::STR, RPCArg::DefaultHint{"automatic"}, "The bitcoin address to receive the change"},
- {"changePosition", RPCArg::Type::NUM, RPCArg::DefaultHint{"random"}, "The index of the change output"},
+ {"change_address|changeAddress", RPCArg::Type::STR, RPCArg::DefaultHint{"automatic"}, "The bitcoin address to receive the change"},
+ {"change_position|changePosition", RPCArg::Type::NUM, RPCArg::DefaultHint{"random"}, "The index of the change output"},
{"change_type", RPCArg::Type::STR, RPCArg::DefaultHint{"set by -changetype"}, "The output type to use. Only valid if changeAddress is not specified. Options are " + FormatAllOutputTypes() + "."},
{"includeWatching", RPCArg::Type::BOOL, RPCArg::Default{false}, "(DEPRECATED) No longer used"},
- {"lockUnspents", RPCArg::Type::BOOL, RPCArg::Default{false}, "Lock selected unspent outputs"},
+ {"lock_unspents|lockUnspents", RPCArg::Type::BOOL, RPCArg::Default{false}, "Lock selected unspent outputs"},
{"fee_rate", RPCArg::Type::AMOUNT, RPCArg::DefaultHint{"not set, fall back to wallet fee estimation"}, "Specify a fee rate in " + CURRENCY_ATOM + "/vB."},
{"feeRate", RPCArg::Type::AMOUNT, RPCArg::DefaultHint{"not set, fall back to wallet fee estimation"}, "Specify a fee rate in " + CURRENCY_UNIT + "/kvB."},
- {"subtractFeeFromOutputs", RPCArg::Type::ARR, RPCArg::Default{UniValue::VARR}, "The outputs to subtract the fee from.\n"
+ {"subtract_fee_from_outputs|subtractFeeFromOutputs", RPCArg::Type::ARR, RPCArg::Default{UniValue::VARR}, "The outputs to subtract the fee from.\n"
"The fee will be equally deducted from the amount of each specified output.\n"
"Those recipients will receive less bitcoins than you enter in their corresponding amount field.\n"
"If no outputs are specified here, the sender pays the fee.",
@@ -1805,7 +1820,8 @@ RPCMethod walletcreatefundedpsbt()
outputs = NormalizeOutputs(request.params[1]);
std::vector<CRecipient> recipients = CreateRecipients(
ParseOutputs(outputs),
- InterpretSubtractFeeFromOutputInstructions(options["subtractFeeFromOutputs"], outputs.getKeys())
+ InterpretSubtractFeeFromOutputInstructions(
+ GetOptionWithAlias(options, "subtract_fee_from_outputs", "subtractFeeFromOutputs"), outputs.getKeys())
);
// Automatically select coins, unless at least one is manually selected. Can
// be overridden by options.add_inputs.
### test/functional/wallet_basic.py
@@ -183,7 +183,7 @@ def run_test(self):
unspent_0 = self.nodes[1].listunspent()[0]
self.nodes[1].lockunspent(False, [unspent_0])
tx = self.nodes[1].createrawtransaction([unspent_0], { self.nodes[1].getnewaddress() : 1 })
- self.nodes[1].fundrawtransaction(tx,{"lockUnspents": True})
+ self.nodes[1].fundrawtransaction(tx, lock_unspents=True)
# fundrawtransaction can lock an input
self.nodes[1].lockunspent(True, [unspent_0])
### test/functional/wallet_fundrawtransaction.py
@@ -915,6 +915,12 @@ def test_address_reuse(self):
def test_option_subtract_fee_from_outputs(self):
self.log.info("Test fundrawtxn subtractFeeFromOutputs option")
+ assert_raises_rpc_error(
+ -8, "Use subtract_fee_from_outputs (subtractFeeFromOutputs is deprecated). Do not set both.",
+ self.nodes[3].fundrawtransaction, hexstring="02000000000000000000",
+ options={"subtract_fee_from_outputs": [0], "subtractFeeFromOutputs": [0]}
+ )
+
# Make sure there is exactly one input so coin selection can't skew the result.
assert_equal(len(self.nodes[3].listunspent(1)), 1)
### test/functional/wallet_keypool.py
@@ -189,7 +189,7 @@ def run_test(self):
assert_raises_rpc_error(-4, "Transaction needs a change address, but we can't generate it.", w2.walletcreatefundedpsbt, inputs=[], outputs=[{addr.pop(): 0.00005000}], subtractFeeFromOutputs=[0], feeRate=0.00010)
# creating a 10,000 sat transaction without change, with a manual input, should still be possible
- res = w2.walletcreatefundedpsbt(inputs=w2.listunspent(), outputs=[{destination: 0.00010000}], subtractFeeFromOutputs=[0], feeRate=0.00010)
+ res = w2.walletcreatefundedpsbt(inputs=w2.listunspent(), outputs=[{destination: 0.00010000}], subtract_fee_from_outputs=[0], feeRate=0.00010)
assert_equal("psbt" in res, True)
# creating a 10,000 sat transaction without change should still be possible
@@ -209,8 +209,9 @@ def run_test(self):
assert_equal(res["fee"], Decimal("0.00009706"))
# creating a 10,000 sat transaction with a manual change address should be possible
- res = w2.walletcreatefundedpsbt(inputs=[], outputs=[{destination: 0.00010000}], subtractFeeFromOutputs=[0], feeRate=0.00010, changeAddress=addr.pop())
+ res = w2.walletcreatefundedpsbt(inputs=[], outputs=[{destination: 0.00010000}], subtractFeeFromOutputs=[0], feeRate=0.00010, change_address=addr.pop())
assert_equal("psbt" in res, True)
+
if __name__ == '__main__':
KeyPoolTest(__file__).main()
### test/functional/wallet_musig.py
@@ -107,7 +107,7 @@ def setup_musig_scenario(self, pat):
outputs=[{self.def_wallet.getnewaddress(): 5}],
inputs=[utxo],
change_type="bech32m",
- changePosition=1
+ change_position=1,
)["psbt"]
return wallets, psbtWhy this scored 33/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.