Implement `create_psbt` for Wallet #297

ValuedMammal · 2025-08-12T18:34:41Z

Description

Use the new bdk_tx transaction building library to create PSBTs in BDK Wallet. Primary benefits include the use of bdk_coin_select as well as miniscript::plan module under the hood.

close #164

Notes to the reviewers

Remaining TODOs can be done in subsequent PRs, including adding support for sorting transaction inputs and outputs, i.e. TxOrdering.

Changelog notice

Added

- new type `PsbtParams`
- new type `ReplaceParams`
- methods `Wallet::create_psbt{_with_aux_rand}`
- method `Wallet::replace_by_fee_and_recipients`
- method `Wallet::replace_by_fee_with_aux_rand`
- `examples/psbt.rs`
- `examples/rbf.rs`

Checklists

All Submissions:

I've signed all my commits
I followed the contribution guidelines

New Features:

I've added tests for the new feature
I've added docs for the new feature

Bugfixes:

~~This pull request breaks the existing API~~
I'm linking the issue being fixed by this PR

coveralls · 2025-08-26T13:17:25Z

Pull Request Test Coverage Report for Build 18172758369

Details

318 of 354 (89.83%) changed or added relevant lines in 3 files are covered.
No unchanged relevant lines lost coverage.
Overall coverage increased (+0.5%) to 85.735%

Changes Missing Coverage	Covered Lines	Changed/Added Lines	%
src/wallet/tx_builder.rs	7	12	58.33%
src/wallet/mod.rs	311	324	95.99%
src/wallet/error.rs	0	18	0.0%

Totals
Change from base Build 18099939060:	0.5%
Covered Lines:	4219
Relevant Lines:	4921

💛 - Coveralls

thunderbiscuit · 2025-08-26T13:37:38Z

I like the create_psbt name for the function. The Params struct I need to do a quick search but off the top of my head it feels like we have a few of those scattered across the crates named exactly that, so it gets confusing. In my exploration PR I used TransactionParams, but that's a bit long and verbose.

What do you envision the API for replace-by-fee transactions look like in this new bdk-tx world? I'm picturing something like Wallet::create_replacement_psbt which takes a WalletTx and another Params struct.

thunderbiscuit

So this is more of a conceptual review/question set, as I'm getting acquainted with the PR, and it also requires knowledge and understanding of the bdk-tx crate/workflow.

One general question I have is do you think is missing in functionality between this and the current TxBuilder? Can we make a todo list that compares functionality with the current TxBuilder to better visualize how close of a replacement this is, or if it only provides part of the functionality for now (and if so which parts)?

I haven't had time to look/test the examples and my day is over, but I'll come back to this on Monday.

thunderbiscuit · 2025-09-12T20:27:25Z

src/wallet/mod.rs

+    ///
+    /// Return `None` if `outpoint` doesn't correspond to an indexed txout, or
+    /// if the assets are not sufficient to create a plan.
+    fn try_plan(&self, outpoint: OutPoint, assets: &Assets) -> Option<Plan> {


Do you have a favourite resource for learning about this plan thing? I'm looking at the docs here and I get a rough idea of how it must work but I'm wondering if there is this "standard expected reading" on it or something similar that I've just missed.

https://hackmd.io/@valuedmammal/B1lxzomj0 It could use an update though.

Perfect thank you! Quick and easy read. Cements my high-level understanding of it.

thunderbiscuit · 2025-09-12T20:32:17Z

src/psbt/params.rs

+/// Coin select strategy.
+#[derive(Debug, Clone, Copy, Default)]
+#[non_exhaustive]
+pub enum SelectionStrategy {


I like the coin selection strategy as a simple enum rather than the CoinSelectionAlgorithm trait. Easier to use and reason about, and most people will only ever need the standard ones (which I assume can eventually get added to this enum) or pick the individual UTXOs themselves.

thunderbiscuit · 2025-09-12T20:34:14Z

src/psbt/params.rs

+    ///
+    /// A single outpoint may appear at most once in the list of UTXOs to spend. The caller is
+    /// responsible for ensuring that elements of `outpoints` correspond to outputs of previous
+    /// transactions and are currently unspent.


Where is the error thrown if this requirement is not met? It's a good place to let people know and I would add it to the docs here.

Wallet::create_psbt will throw a CreatePsbtError::UnknownUtxo if the outpoint doesn't match a previously indexed outpoint (i.e. a wallet-owned tx output). I agree it should be documented somewhere.

thunderbiscuit · 2025-09-12T20:41:05Z

src/psbt/params.rs

+    }
+
+    /// Set the definite descriptor used for generating the change output.
+    pub fn change_descriptor(&mut self, desc: DefiniteDescriptor) -> &mut Self {


Is it correct to think that if not defined here, the change just goes to:

The next index on Keychain::Internal if available

If no internal keychain is available, the next index on the KeychainKind::External

Ok awesome thanks for confirming. In this case, I'd just mention this in the docs (that this method is basically "if you want to send change elsewhere than your default change location").

thunderbiscuit · 2025-09-12T20:46:20Z

src/psbt/params.rs

+/// `ReplaceParams` provides a thin wrapper around [`PsbtParams`] and is intended for
+/// crafting Replace-By-Fee transactions (RBF).
+#[derive(Debug, Default)]
+pub struct ReplaceParams {


Can you tell me more about why we want this new ReplaceParams type? Naively I would have thought you'd just call PsbtParams::replace and you'd get a sort of pre-populated PsbtParams ready for replacing your tx, but I assume this doesn't quite work?

Naively I would have thought you'd just call PsbtParams::replace and you'd get a sort of pre-populated PsbtParams ready for replacing your tx

That works too.

If that works that's my preferred approach, unless there is something I'm not seeing.

Sorry I didn't elaborate before. We want to provide some separation to make it difficult to misuse the API. Once you've committed to replacing a tx, you can't go back and fiddle with the params, instead you're limited to doing only what is permitted by the ReplaceParams, at least that's the general idea. This prevents a situation where some params override others and the implementation becomes unwieldy.

Right now the key difference is that you're not allowed to add more utxos (outpoints) in addition the ones being replaced, because it may lead to creating an invalid tx. Still open to suggestions for improvement.

thunderbiscuit · 2025-09-12T20:59:31Z

src/wallet/mod.rs

+    /// # Ok::<_, anyhow::Error>(())
+    /// ```
+    #[cfg(feature = "std")]
+    pub fn create_psbt(&self, params: PsbtParams) -> Result<(Psbt, Finalizer), CreatePsbtError> {


Why do we return this Finalizer? I'd like to see that expanded upon in the docs. When looking into it I see that the Finalizer is

pub struct Finalizer { pub(crate) plans: HashMap<OutPoint, Plan>, }

so probably something that helps the signers figure out what to sign and how to sign once you give them a psbt, but I'm not sure. The docs on Finalizer are also a bit... brief 😂😂

I still need to take a deeper look into bdk-tx, but I think the name could be misleading with Input Finalizer from the PSBT BIP-174 (if it's not following the same proposed idea).

It is meant to handle the role of a PSBT input finalizer as described in BIP174.

oleonardolima

I did an initial review, with simple comments/questions. Still need to take a deeper look into bdk-tx and do a more thorough review here.

oleonardolima · 2025-09-15T01:35:29Z

wallet/Cargo.toml

 bip39 = { version = "2.0", optional = true }
 bdk_file_store = { version = "0.21.1", optional = true }
+anyhow = { version = "1.0.98", optional = true }
+tempfile = { version = "3.20.0", optional = true }


I guess this can be removed, as it's not being used.

oleonardolima · 2025-09-15T01:43:41Z

src/wallet/error.rs

+    /// No Bnb solution.
+    Bnb(bdk_coin_select::NoBnbSolution),
+    /// Non-sufficient funds
+    InsufficientFunds(bdk_coin_select::InsufficientFunds),


Can't we have a generic CS error instead ?

oleonardolima · 2025-09-15T01:50:27Z

src/wallet/mod.rs

+    /// # Ok::<_, anyhow::Error>(())
+    /// ```
+    #[cfg(feature = "std")]
+    pub fn create_psbt(&self, params: PsbtParams) -> Result<(Psbt, Finalizer), CreatePsbtError> {


I still need to take a deeper look into bdk-tx, but I think the name could be misleading with Input Finalizer from the PSBT BIP-174 (if it's not following the same proposed idea).

ValuedMammal · 2025-09-16T18:13:40Z

Thank you for the quick review @thunderbiscuit @oleonardolima.

ValuedMammal · 2025-09-20T15:02:10Z

TxBuilder vs PsbtParams feature comparison

subject to change

Feature	TxBuilder	PsbtParams	Status
internal_policy_path	✅	❌	deprecated
external_policy_path	✅	❌	deprecated
manually_selected_only	✅	❌	unknown**
include_output_redeem_witness_script	✅	❌	deprecated
current_height	✅	❌	unknown**
fee_policy	✅	✅ ❌	TODO
sighash (type)	✅	❌	TODO
ordering	✅	✅	Done
add_global_xpubs	✅	❌	TODO
allow_dust	✅	❌	unknown**
unspendable	✅	❌	unknown**
recipients	✅	✅	Done
utxos	✅	✅	Done
drain_wallet	✅	✅	Done
drain_to/change_script	✅	✅	Done
locktime	✅	✅	Done
version	✅	✅	Done
fallback_sequence	✅	✅	Done
bumping_fee	✅	✅	Done*
only_witness_utxo	✅	❌	unknown**
change_policy	✅	❌	TODO
utxo_filter	❌	✅	Done

* See RbfParams
** or undecided

Add module psbt/params.rs and introduce PsbtParams. test: Add `test_create_psbt` Introduce `ReplaceParams` Add `Wallet::replace_by_fee_and_recipients` Add `Wallet::replace_by_fee_with_aux_rand` test: `test_sanitize_rbf_set` test: Add `test_replace_by_fee` test: Add `test_spend_non_canonical_txout`

`UtxoFilter` is a user-defined Fn closure which takes a `&FullTxOut` and decides whether to exclude it from coin selection. This can be used, for example, to mark an output unspendable or apply custom UTXO filtering logic.

..by exposing the generic from `TxSort` function. We use bitcoin `TxIn` and `TxOut` as the default type parameter for backward compatibility. Add `sort_with_aux_rand` for `TxOrdering<In, Out>` for sorting two generic mutable slices.

..function on the Selection inputs and outputs.

This is a simple data structure which contains the manually selected outpoints enforcing order and uniqueness.

Check that adding duplicate outpoints only results in a single outpoint added, and that it is contained within the inner set.

ValuedMammal · 2025-10-01T19:17:46Z

We need a way to implement fee_absolute or find out if this is possible using bdk_coin_select.
Note that UtxoFilter can accomplish a number of things from the old interface, such as "change policy" and "unspendable".
To prevent multiple parameters from trying to dictate the current height, the current_height option can be achieved via the assets.absolute_timelock.

github-project-automation bot added this to BDK Wallet Aug 12, 2025

ValuedMammal moved this to In Progress in BDK Wallet Aug 12, 2025

ValuedMammal added this to the Wallet 3.0.0 milestone Aug 12, 2025

ValuedMammal self-assigned this Aug 12, 2025

ValuedMammal force-pushed the feat/create_psbt branch from 673d602 to 77e1d20 Compare August 26, 2025 13:12

thunderbiscuit mentioned this pull request Aug 26, 2025

Exploring bdk-tx for Wallet type #15

Closed

This was referenced Sep 5, 2025

API surface of the TxBuilder type bitcoindevkit/bdk-ffi#597

Closed

Add coin selection to tx_builder bitcoindevkit/bdk-ffi#821

Closed

ValuedMammal force-pushed the feat/create_psbt branch from 2c54be1 to 6f525d1 Compare September 10, 2025 16:46

thunderbiscuit mentioned this pull request Sep 11, 2025

Expose add_foreign_utxo for TxBuilder bitcoindevkit/bdk-ffi#329

Closed

ValuedMammal force-pushed the feat/create_psbt branch from 6f525d1 to 4493cbd Compare September 11, 2025 15:36

ValuedMammal moved this from In Progress to Needs Review in BDK Wallet Sep 11, 2025

ValuedMammal marked this pull request as ready for review September 11, 2025 15:39

ValuedMammal requested a review from thunderbiscuit September 11, 2025 15:40

ValuedMammal changed the title ~~[WIP] Implement create_psbt for Wallet~~ Implement create_psbt for Wallet Sep 11, 2025

thunderbiscuit reviewed Sep 12, 2025

View reviewed changes

oleonardolima reviewed Sep 15, 2025

View reviewed changes

notmandatory added the summit To review at rust bitcoin summit. label Sep 23, 2025

notmandatory mentioned this pull request Sep 25, 2025

Socratic Seminar #36 Topics NashBitDevs/nashbitdevs.org#107

Open

ValuedMammal added 2 commits September 29, 2025 13:43

docs: Improve documentation

a7afecb

ValuedMammal force-pushed the feat/create_psbt branch from 4493cbd to a7afecb Compare September 29, 2025 17:44

ValuedMammal added 4 commits October 1, 2025 13:45

feat(psbt_params): Add filter_utxos

f15c99c

`UtxoFilter` is a user-defined Fn closure which takes a `&FullTxOut` and decides whether to exclude it from coin selection. This can be used, for example, to mark an output unspendable or apply custom UTXO filtering logic.

feat(psbt_params): Add method ordering for PsbtParams

71ef226

wallet: Update create_psbt_from_selector to call the TxOrdering

8749311

..function on the Selection inputs and outputs.

ValuedMammal added 3 commits October 1, 2025 14:56

feat(psbt_params): Add newtype SelectedOutpoints

726a53a

This is a simple data structure which contains the manually selected outpoints enforcing order and uniqueness.

refactor(psbt_params): Change type of utxos field to SelectedOutpoints

160350d

test(psbt_params): Add test_selected_outpoints_are_unique

d056aa3

Check that adding duplicate outpoints only results in a single outpoint added, and that it is contained within the inner set.

Implement create_psbt for Wallet #297

Are you sure you want to change the base?

Implement create_psbt for Wallet #297

Uh oh!

Conversation

ValuedMammal commented Aug 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Notes to the reviewers

Changelog notice

Checklists

All Submissions:

New Features:

Bugfixes:

Uh oh!

coveralls commented Aug 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pull Request Test Coverage Report for Build 18172758369

Details

💛 - Coveralls

Uh oh!

thunderbiscuit commented Aug 26, 2025

Uh oh!

thunderbiscuit left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ValuedMammal Sep 16, 2025 • 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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ValuedMammal Sep 16, 2025 • 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!

Choose a reason for hiding this comment

Uh oh!

thunderbiscuit Sep 16, 2025 • 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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

oleonardolima left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ValuedMammal commented Sep 16, 2025

Uh oh!

ValuedMammal commented Sep 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

TxBuilder vs PsbtParams feature comparison

Uh oh!

ValuedMammal commented Oct 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Implement `create_psbt` for Wallet #297

Implement `create_psbt` for Wallet #297

ValuedMammal commented Aug 12, 2025 •

edited

Loading

coveralls commented Aug 26, 2025 •

edited

Loading

ValuedMammal Sep 16, 2025 •

edited

Loading

ValuedMammal Sep 16, 2025 •

edited

Loading

thunderbiscuit Sep 16, 2025 •

edited

Loading

ValuedMammal commented Sep 20, 2025 •

edited

Loading

ValuedMammal commented Oct 1, 2025 •

edited

Loading