#32857 wallet: allow skipping script paths

full analysis

https://github.com/bitcoin/bitcoin/pull/32857 · Sjors · +243/-27 in 13 files, 9 commits · labels: Wallet

Goal

  • Allow Taproot spends to skip script paths to avoid exposing fallback scripts on chain
  • Saves transaction fees and protects privacy for users of complex Taproot and MuSig2 setups

This PR adds a `keypath_only` option (defaulting to `false`) to `send`, `sendall`, `walletcreatefundedpsbt`, `walletprocesspsbt`, and `descriptorprocesspsbt`. When enabled, the wallet and PSBT processing code avoid adding new Taproot script-path metadata, avoid generating script-path signatures, and refuse to finalize transactions via script paths even if valid script-path signatures are already present.

Problem: When spending from Taproot descriptors that include both key path and script path alternatives (such as MuSig2 aggregate keys with timelocked fallback scripts), the wallet routinely adds and signs script-path data. This wastes fees, harms privacy by unnecessarily exposing fallback scripts, can trigger firmware bugs in external signing devices, and risks accidental broadcast of fallback paths.

Category: RPC / REST / ZMQ (#11 of 52)

P3 · new feature

  • P3 because it adds an optional parameter to five RPC methods without changing default behavior
  • Gives RPC callers explicit control over Taproot spending metadata and signing paths

Exposes an optional parameter across five RPC methods to control Taproot signing behavior without modifying default RPC responses.

Membership: Adds the keypath_only parameter to multiple wallet and rawtransaction RPC interfaces (send, sendall, walletprocesspsbt, walletcreatefundedpsbt, descriptorprocesspsbt) and updates rpc convert params.

Factors: security/stability 0, bug 0, performance 0, user value 2, leverage 1

Category: Wallet (#32 of 84)

P3 · new feature

  • P3 because it benefits Taproot and MuSig2 users by preventing accidental fallback script spends
  • Remains an opt-in safety feature with no impact on default wallet spending behavior

Provides real value for complex Taproot and MuSig2 descriptor wallets by preventing inadvertent fallback script-path exposure and spending, but remains an optional opt-in flag that can be reasonably deferred.

Membership: Directly touches wallet PSBT construction, coin spending, and signing logic in src/wallet/rpc/spend.cpp and src/psbt.cpp.

Factors: security/stability 1, bug 0, performance 0, user value 2, leverage 1

Reviewability: Ready

  • Ready to review: branch is rebased, CI passes, and prior reviewer suggestions are addressed

Branch is rebased, mergeable, CI is passing, and all prior reviewer suggestions have been addressed.

Author status: Active; author resolved all reviewer feedback and has maintained the branch through several rebases.

Resolved concerns:

  • Extended keypath_only to descriptorprocesspsbt and sendall for consistency across signing RPCs (raised by rkrux)
  • Unified parameter naming to keypath_only instead of mixing avoid_script_path and keypath_only (raised by rkrux)
  • Clarified that keypath_only prevents finalizing pre-existing script-path signatures in PSBTs as a safety feature (raised by jeanpablojp)
  • Disallowed keypath_only in the legacy fundrawtransaction RPC (raised by jeanpablojp)
  • Replaced hardcoded test keys with ExtendedPrivateKey test utilities (raised by rkrux)

Agreement: Strong

  • Strong support citing multi-party MuSig keypath and script-path race scenarios (rkrux)
  • Verified by testing script-path suppression behavior and test coverage (jeanpablojp)
  • Concept approval without stated reasons (w0xlt)

Strong: substantive Concept ACK and review from rkrux, tested ACK from jeanpablojp, no objections.

Reviewers agreed on the motivation and worked with the author to extend the option consistently across PSBT RPCs and functional tests.

  • rkrux Concept ACKed and outlined multi-party MuSig keypath vs script-path race scenarios justifying the change
  • w0xlt Concept ACKed
  • jeanpablojp tested and ACKed earlier iteration, confirming test coverage and script-path suppression behavior

Review verdicts (DrahtBot): 0 (+1)

Files

195 lines under test/bench/ci.

  • test/functional/wallet_taproot.py +74/-13
  • test/functional/rpc_psbt.py +69/-0
  • test/functional/wallet_musig.py +32/-5
  • src/rpc/rawtransaction.cpp +17/-4
  • src/wallet/rpc/spend.cpp +17/-4
  • doc/release-notes-32857.md +8/-0
  • src/script/sign.cpp +8/-0
  • src/common/types.h +6/-0
  • src/rpc/client.cpp +5/-0
  • src/script/sign.h +3/-0
  • src/psbt.cpp +1/-1
  • test/functional/wallet_fundrawtransaction.py +2/-0
  • src/wallet/wallet.h +1/-0

Card

This PR adds a keypath_only option to wallet and PSBT RPCs (send, sendall, walletcreatefundedpsbt, walletprocesspsbt, and descriptorprocesspsbt) to restrict Taproot spending to the key path. This avoids unnecessary script-path signature creation, prevents premature on-chain disclosure of fallback scripts in complex descriptors (such as MuSig2 wallets with recovery branches), and avoids triggering external signer bugs. The PR has strong review support with concept and tested ACKs, is fully rebased, and is ready for final review.

Data

dossier JSON · extract JSON · model openrouter/google/gemini-3.8-flash, generated 2026-09-17T15:49, confidence high, input hash 10aac1e62b432a9e