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.

fix #164
fix #204

Notes to the reviewers

Remaining TODOs are listed in the table below #297 (comment).

It may help to look over the high level design and rationale which is available here.

Changelog notice

### Changed

- `TxOrdering::Custom` is generic over the input and output types.

### Added

- `psbt::params` module
- `PsbtParams` struct
- `ReplaceParams` struct
- `CoinSelectionStrategy` enum
- `UtxoFilter` struct

Added `pub` methods on `Wallet`

- `Wallet::create_psbt{_with_rng}`
- `Wallet::replace_by_fee{_with_rng}`
- `Wallet::replace_by_fee_and_recipients`
- `Wallet::transactions_with_params`
- `Wallet::insert_tx`

- docs: Add `examples/psbt.rs`
- docs: Add `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 19016316365

Warning: This coverage report may be inaccurate.

This pull request's base commit is no longer the HEAD commit of its target branch. This means it includes changes from outside the original pull request, including, potentially, unrelated coverage changes.

For more information on this, see Tracking coverage changes with pull request builds.
To avoid this issue with future PRs, see these Recommended CI Configurations.
For a quick fix, rebase this PR at GitHub. Your next report should be accurate.

Details

524 of 656 (79.88%) changed or added relevant lines in 5 files are covered.
299 unchanged lines in 8 files lost coverage.
Overall coverage decreased (-0.03%) to 84.779%

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	317	357	88.8%
src/psbt/params.rs	183	251	72.91%

Files with Coverage Reduction	New Missed Lines	%
src/wallet/signer.rs	3	81.11%
src/wallet/params.rs	9	76.24%
src/descriptor/template.rs	10	97.46%
src/descriptor/mod.rs	13	88.04%
src/descriptor/dsl.rs	16	95.36%
src/keys/mod.rs	69	79.49%
src/descriptor/policy.rs	89	79.17%
src/wallet/mod.rs	90	84.1%

Totals
Change from base Build 18318022693:	-0.03%
Covered Lines:	7536
Relevant Lines:	8889

💛 - 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.

src/wallet/mod.rs

src/psbt/params.rs

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.

wallet/Cargo.toml

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.

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.

`TxOrdering` is made generic by exposing the generic from `TxSort` function. The benefit is that we're no longer limited to ordering lists of only `TxIn` or `TxOut`. We use bitcoin `TxIn` and `TxOut` as the default type parameter to maintain backward compatibility. Add `sort_with_rng` for `TxOrdering<In, Out>` for sorting two generic mutable slices. This will be useful in a later commit by applying a `TxOrdering` to the Input/Output sets of a `Selection`.

We add the `psbt::params` module along with new types including `PsbtParams`, `ReplaceParams`, and `SelectionStrategy`. `PsbtParams` is mostly inspired by `TxParams` from `tx_builder.rs`, except that we've removed support for `policy_path` in favor of `add_assets` API. Further enhancements include `.utxo_filter` and `.canonical_params` member fields. In `lib.rs` re-export everything under `psbt` module. - deps: Add `bdk_tx` 0.1.0 - deps: Add `bdk_coin_select` 0.4.1

codecov · 2025-12-02T03:42:38Z

Codecov Report

❌ Patch coverage is 80.64024% with 127 lines in your changes missing coverage. Please review.
✅ Project coverage is 84.77%. Comparing base (36f98df) to head (f00d309).
⚠️ Report is 14 commits behind head on master.

Files with missing lines	Patch %	Lines
src/psbt/params.rs	72.90%	68 Missing ⚠️
src/wallet/mod.rs	90.19%	35 Missing ⚠️
src/wallet/error.rs	0.00%	19 Missing ⚠️
src/wallet/tx_builder.rs	58.33%	5 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #297      +/-   ##
==========================================
- Coverage   84.81%   84.77%   -0.04%     
==========================================
  Files          23       24       +1     
  Lines        8145     8889     +744     
==========================================
+ Hits         6908     7536     +628     
- Misses       1237     1353     +116

Flag	Coverage Δ
rust	`84.77% <80.64%> (-0.04%)`	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

We use the new `PsbtParams` to add methods on `Wallet` for creating PSBTs, including RBF transactions. `Wallet::create_psbt` and `Wallet::replace_by_fee` each have no-std counterparts that take an additional `impl RngCore` parameter. Also adds a high level convenience method `Wallet::replace_by_fee_and_recipients` that exposes the minimum information needed to create an RBF. This commit re-introduces the `Wallet::insert_tx` API for adding transaction data to the wallet that may or may not be canonical from the point of view of the TxGraph. Added `Wallet::transactions_with_params` that allows customizing the internal canonicalization logic. Added new errors to `wallet::errors` - `CreatePsbtError` - `ReplaceByFeeError`

Adds several tests to exercise create-psbt logic and user flow. - test-utils: Add `insert_tx_anchor` test helper for adding a transaction to the wallet with associated anchor block. - deps: Bump `bitcoin` to 0.32.7 in order to make use of `ScriptBuf::new_p2a`.

- `examples/psbt.rs` - `examples/rbf.rs`

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 force-pushed the feat/create_psbt branch from 3d7bd2e to 5285937 Compare October 24, 2025 18:40

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

thunderbiscuit mentioned this pull request Oct 30, 2025

Lining Up The Big 3.0 PRs #339

Open

ValuedMammal mentioned this pull request Nov 6, 2025

Improve documentation of Finalizer bitcoindevkit/bdk-tx#28

Open

ValuedMammal added 2 commits December 1, 2025 22:19

ValuedMammal force-pushed the feat/create_psbt branch from 596565f to d562584 Compare December 2, 2025 03:38

ValuedMammal added 3 commits December 2, 2025 00:11

docs: Add example code snippets to examples directory

f00d309

- `examples/psbt.rs` - `examples/rbf.rs`

ValuedMammal force-pushed the feat/create_psbt branch from d562584 to f00d309 Compare December 2, 2025 05:11

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 19016316365

Warning: This coverage report may be inaccurate.

Details

💛 - Coveralls

Uh oh!

thunderbiscuit commented Aug 26, 2025

Uh oh!

thunderbiscuit left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

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!

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

Uh oh!

codecov bot commented Dec 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Reviewers

Assignees

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

thunderbiscuit Sep 16, 2025 •

edited

Loading

ValuedMammal commented Sep 20, 2025 •

edited

Loading

ValuedMammal commented Oct 1, 2025 •

edited

Loading

codecov bot commented Dec 2, 2025 •

edited

Loading