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 are listed in the table below #297 (comment).

Changelog notice

Added

- new type `PsbtParams`
- new type `ReplaceParams`
- methods `Wallet::create_psbt{_with_aux_rand}`
- methods `Wallet::replace_by_fee{_with_aux_rand}`
- convenience method `Wallet::replace_by_fee_and_recipients`
- `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 18791891690

Details

517 of 644 (80.28%) changed or added relevant lines in 5 files are covered.
No unchanged relevant lines lost coverage.
Overall coverage decreased (-0.2%) to 84.587%

Changes Missing Coverage	Covered Lines	Changed/Added Lines	%
src/wallet/tx_builder.rs	7	12	58.33%
src/wallet/error.rs	0	19	0.0%
src/wallet/mod.rs	320	357	89.64%
src/psbt/params.rs	173	239	72.38%

Totals
Change from base Build 18318022693:	-0.2%
Covered Lines:	7431
Relevant Lines:	8785

💛 - 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	✅	❌	NA
external_policy_path	✅	❌	NA
manually_selected_only	✅	✅	Done
include_output_redeem_witness_script	✅	❌	NA
current_height	✅	✅	Done
fee_rate	✅	✅	Done
fee_absolute	✅	❌	TODO
sighash (type)	✅	❌	TODO
ordering	✅	✅	Done
add_global_xpubs	✅	✅	Done
allow_dust	✅	✅	Done
unspendable	✅	❌	NA
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	✅	✅	Done
change_policy	✅	❌	NA
add_foreign_utxo / planned_input	✅	✅	Done
utxo_filter	❌	✅	Done

N/A:
- *_policy_path: deprecated, ref: add_assets
- include_output_redeem_witness_script: deprecated, not used
- unspendable: NA, ref: utxo_filter
- change_policy: NA, ref: utxo_filter

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~~.
current_height renamed to maturity_height, as it's only used as a parameter to is_mature.

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.

Also re-export types in `psbt` module

This can be used to add inputs that come with a plan or PSBT input provided.

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

`add_global_xpubs` is a boolean which decides whether to fill in the PSBT global xpubs. If true, we proceed to gather extended keys of the wallet's descriptors and add them to the map of global xpubs with their origin.

ValuedMammal · 2025-10-26T22:26:53Z

We need a way to implement fee_absolute or find out if this is possible using bdk_coin_select.

I think a straightforward approach is to set a target feerate of 0 and add the fee amount to the output value_sum. The effect is to raise the cost of meeting the target by the amount of the target fee.

I can see it being relevant to CPFP, since there we're less concerned about the feerate of an individual tx and more so with the fee needed to bump a package to a target feerate.

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

Closed

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

ValuedMammal added 5 commits October 24, 2025 14:37

docs: Improve documentation

c162237

feat(psbt_params): Add filter_utxos

735a5fb

`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

c9e5597

ValuedMammal added 16 commits October 24, 2025 14:37

wallet: Update create_psbt_from_selector to call the TxOrdering

3143640

..function on the Selection inputs and outputs.

Fix imports

88582b1

Also re-export types in `psbt` module

fix(wallet): Use Output::with_descriptor for self sending outputs

353a49c

wallet: Add missing replace_by_fee method which calls the thread-rng

8471247

psbt: Add method PsbtParams::add_planned_input

7925bc9

This can be used to add inputs that come with a plan or PSBT input provided.

test(psbt): Add test_selected_outpoints_are_unique

187d5b2

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

test: Add test_add_planned_psbt_input

003e2f5

UtxoFilter has a Default implementation that applies no filtering

8dc6229

docs: Add docsrs cfg attribute for methods gated by "std"

9f0e256

psbt: Add PsbtParams::maturity_height

5d99f60

psbt: Add PsbtParams::locktime

f257aba

feat(psbt): Add PsbtParams::manually_selected_only

5ef1274

psbt: Return InsufficientFunds if InputCandidates is empty

c73001c

feat(psbt): Add PsbtParams::only_witness_utxo

a1a8c5b

test: Add test_create_psbt_csv

bf51f18

psbt: Add PsbtParams::canonicalization_params

5285937

ValuedMammal force-pushed the feat/create_psbt branch from 3d7bd2e to 5285937 Compare October 24, 2025 18:40

feat(psbt): Add PsbtParams::add_global_xpubs

25e4b4e

`add_global_xpubs` is a boolean which decides whether to fill in the PSBT global xpubs. If true, we proceed to gather extended keys of the wallet's descriptors and add them to the map of global xpubs with their origin.

ValuedMammal mentioned this pull request Oct 26, 2025

Is there a way to specify the absolute fee of a transaction? bitcoindevkit/bdk-tx#26

Open

ValuedMammal moved this from Needs Review to In Progress in BDK Wallet Oct 28, 2025

Implement create_psbt for Wallet #297

Are you sure you want to change the base?

Implement create_psbt for Wallet #297

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 18791891690

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!

ValuedMammal commented Oct 26, 2025

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