Implement `create_psbt` for Wallet by ValuedMammal · Pull Request #297 · bitcoindevkit/bdk_wallet

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

It may help to look over the high level design and rationale which is available here https://hackmd.io/@bdk/r11JIeIjxl. See also a chart of how the features compare with TxBuilder #297 (comment).

Changelog notice

Changed

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

Added

psbt::params module
PsbtParams 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: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.

Removed ReplaceParams. Now calling PsbtParams::replace_txs will return a new PsbtParams that is marked by the "RBF" context. I think it's a cleaner approach overall without compromising type safety.

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 ?

Can you elaborate on what you mean by generic CS error?

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	✅	✅	Done
sighash (type)	✅	✅	Done
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	✅	✅	Done
add_foreign_utxo / planned_input	✅	✅	Done
filter_utxos	❌	✅	Done

N/A:
- *_policy_path: deprecated, use add_assets instead
- include_output_redeem_witness_script: deprecated, no longer used
- unspendable: NA, refer to filter_utxos
- change_policy: NA, refer to filter_utxos

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.

aagbotemi · 2026-02-03T23:52:03Z

The bdk_tx update introduced enable_anti_fee_sniping. I think it's okay if we add this field to PsbtParams struct to expose it to users.

evanlinjin · 2026-02-18T15:46:15Z

src/psbt/params.rs

+    /// Optional assets for creating a spend plan.
+    pub(crate) assets: Option<Assets>,
+    /// Fee targeting strategy.
+    pub(crate) fee_strategy: FeeStrategy,


I think it's a better to include BOTH a min-feerate target and a min-absolute-fee target and not have the caller choose either-or.

Payjoin (BIP 78): The payjoin proposal MUST NOT decrease the absolute fee of the original transaction.

However, the receiver might also want a feerate target that ensures the payment gets received in the next block.

c.c. @DanGould

This feature should be upstreamed to bdk_coin_select and bdk_tx (I'm currently working on it!).

This is what our API looks like to solve our fee problems for receivers: https://docs.rs/payjoin/1.0.0-rc.1/payjoin/receive/v2/struct.Receiver.html#impl-Receiver%3CWantsFeeRange%3E

Internally we enforce the minimum absolute fee and we enable a receiver to specify their minimum fee rate when the initialize the receiver (though I suppose in time it should really be a function rather than a value) as well as a maximum fee rate to prevent overspending by a counterparty who insists on a higher feerate.

very much a nit, but '"ensures" the [transaction] gets received in the next block' is necessarily interactive, and still only a best effort, since all we can do is estimate in this function afaiu.

Sounds good.

`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` 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. `PsbtParams<C>` contains a type parameter `C` indicating the context in which the parameters can be used. Methods related to PSBT creation exist within the `CreateTx` context, and methods related to replacements (RBF) exist within the `ReplaceTx` context. In `lib.rs` re-export everything under `psbt` module. - deps: Add `bdk_tx` 0.1.0 - deps: Add `bdk_coin_select` 0.4.1

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 additional tests to exercise `PsbtParams` logic and PSBT creation. - test-utils: Add `insert_tx_anchor` test helper for adding a transaction to the wallet with associated anchor block.

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

Made a number of API changes to `PsbtParams` - Add `PsbtParams::sighash_type` - psbt: Change `change_descriptor` to `change_script` - Add `PsbtParams::change_policy` - psbt: Change `feerate` to `fee` using `FeeStrategy` - Remove `longterm_feerate` TODO: - This should be updated to depend on `bdk_tx` version 0.2.0 which is still unreleased.

This enables the corresponding option in `bdk_tx::PsbtParams`. By default the feature is disabled, and allows opting in to LockTime- or Sequence-based (taproot only) anti-fee-sniping protection as specified in BIP326.

doc: Add special consideration regarding time-based absolute timelocks By default when no locktime is specified for the transaction, the wallet uses the height of the current chain tip as a fallback. However this will clash with a time-based absolute timelock of a planned input when deciding the locktime to put in the transaction. To clarify the behavior we update the docs to state that if spending coins locked to a certain timestamp, the `PsbtParams::locktime` must also be time-based. The highest available locktime is the one that is used.

ValuedMammal · 2026-02-28T20:47:32Z

src/psbt/params.rs

+    /// If adding a time-based absolute timelock here, you must also set a [`PsbtParams::locktime`]
+    /// which is time-based (i.e. UNIX timestamp) to use as a fallback, otherwise a
+    /// `LockTypeMismatch` error will occur.


I find this slightly annoying and there could be an alternative way to handle it. Rationale in 4afed0e.

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 Feb 23, 2026

Is there a way to specify the absolute fee of a transaction? bitcoindevkit/coin-select#41

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

9 tasks

ValuedMammal force-pushed the feat/create_psbt branch 2 times, most recently from f00d309 to 3988abb Compare December 3, 2025 18:44

ValuedMammal force-pushed the feat/create_psbt branch 2 times, most recently from d98d8f1 to 14c1d2c Compare December 18, 2025 12:42

ValuedMammal added new feature New feature or request and removed summit To review at rust bitcoin summit. labels Dec 18, 2025

thunderbiscuit mentioned this pull request Jan 14, 2026

Release Guide Pages for 3.0 bitcoindevkit/book-of-bdk#137

Open

7 tasks

ValuedMammal force-pushed the feat/create_psbt branch from cc0dcd8 to 73a7db9 Compare January 14, 2026 18:23

aagbotemi mentioned this pull request Jan 19, 2026

Add CPFP Support #370

Open

8 tasks

ValuedMammal force-pushed the feat/create_psbt branch from 661cfc8 to 7c7e59e Compare February 17, 2026 16:06

evanlinjin reviewed Feb 18, 2026

View reviewed changes

ValuedMammal modified the milestones: Wallet 3.0.0, Wallet 3.1.0 Feb 23, 2026

oleonardolima self-requested a review February 27, 2026 01:36

ValuedMammal added 11 commits February 27, 2026 00:06

test: Add coverage for create_psbt

7df909e

Adds additional tests to exercise `PsbtParams` logic and PSBT creation. - test-utils: Add `insert_tx_anchor` test helper for adding a transaction to the wallet with associated anchor block.

docs: Add example code snippets to examples directory

7f9a868

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

docs(psbt): correct docs for UtxoFilter

e706deb

docs(psbt): Document PsbtParams members

590a5dd

feat(psbt): Derive Clone for UtxoFilter

5000aff

feat(psbt): Add PsbtParams::enable_anti_fee_sniping

e564c74

This enables the corresponding option in `bdk_tx::PsbtParams`. By default the feature is disabled, and allows opting in to LockTime- or Sequence-based (taproot only) anti-fee-sniping protection as specified in BIP326.

ValuedMammal force-pushed the feat/create_psbt branch from 7c7e59e to 4afed0e Compare February 28, 2026 19:30

ValuedMammal commented Feb 28, 2026

View reviewed changes

deps: Fix bdk_tx no default features

151a96e

ValuedMammal force-pushed the feat/create_psbt branch from e6579cb to 151a96e Compare February 28, 2026 21:16

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

Changed

Added

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!

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!

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!

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!

aagbotemi commented Feb 3, 2026

Uh oh!

evanlinjin Feb 18, 2026 • 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

ValuedMammal commented Aug 12, 2025 •

edited

Loading

coveralls commented Aug 26, 2025 •

edited

Loading

thunderbiscuit Sep 16, 2025 •

edited

Loading

ValuedMammal commented Sep 20, 2025 •

edited

Loading

ValuedMammal commented Oct 1, 2025 •

edited

Loading

evanlinjin Feb 18, 2026 •

edited

Loading