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

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

Description

This PR introduces a new PSBT construction flow and associated wallet APIs.

Primary additions:

New PsbtParams<Ctx> API with typed contexts (CreateTx and ReplaceTx) for transaction creation and replacement.
New wallet entry points for PSBT construction and RBF:
- Wallet::create_psbt and Wallet::create_psbt_with_rng
- Wallet::replace_by_fee, Wallet::replace_by_fee_with_rng, and Wallet::replace_by_fee_and_recipients
New error types for the new create-PSBT and RBF paths.
Supporting wallet helpers for transaction insertion and canonicalization-aware transaction listing.
New examples and expanded test coverage for expected PSBT/RBF behavior.
Generic TxOrdering<In, Out> updates used by the new selection/PSBT path

This work is part of the broader migration of transaction construction to bdk_tx, which uses miniscript's plan module under the hood. A key long-term goal is the move away from legacy policy-based transaction construction internals (#4).

fix #204

Notes to the reviewers

Suggested review order for this PR:

Start with examples/psbt.rs and examples/replace_by_fee.rs for a high-level API walkthrough.
Review src/psbt/params.rs in detail (types, state transitions, params semantics, and so on).
Review the new wallet implementation in src/wallet/mod.rs (create-PSBT and RBF execution paths plus shared helpers).
Review tests in tests/psbt.rs, tests/wallet.rs to ensure expected behavior and edge cases are covered.

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

Added examples

examples/psbt.rs
examples/replace_by_fee.rs

Checklists

I followed the contribution guidelines
~~This pull request breaks the existing API~~

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.

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:43:41Z

+    /// 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?

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	✅	❌	_
sighash (type)	✅	✅	Done
ordering	✅	✅	Done
add_global_xpubs	✅	✅	Done
allow_dust	✅	❌	_
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.

Bridge between bdk_wallet and bdk_tx, exposed as a `WalletTxExt` extension trait on `bdk_wallet::Wallet`. Keeping it in its own crate means neither base crate depends on the other: `bdk_wallet` stays stable, `bdk_tx` stays free to move, and the bridge absorbs the coupling (the decoupling argument from bitcoindevkit/bdk_wallet#297). Three-stage pipeline: - `candidates`/`candidates_with`/`rbf_candidates` -> `CandidateSet` (stage 1). - `select`/`select_with_rng` -> `(TxTemplate, Option<AddressInfo>)` (stage 2): a pure read that peeks the auto-derived change address; commit it with `commit_change` (reveal + mark used) when you use the tx, or ignore it on abandon. Emit the PSBT directly via `bdk_tx::TxTemplate::build_psbt`. - `add_global_xpubs` fills the PSBT's global xpubs (the only emission step that needs the wallet). Ported from the bdk_wallet#502 PoC, re-expressed over the integrated bdk_tx API and the wallet's public accessors. MTP is faked from the confirmation block time; UTXO locking is honored; `longterm_feerate` lives on `SelectParams` and feeds the waste-aware change policy for every strategy. End-to-end tests cover the pipeline, RBF-free candidate filtering, change commit, and error paths. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Bridge between bdk_wallet and bdk_tx, exposed as a `WalletTxExt` extension trait on `bdk_wallet::Wallet`. Keeping it in its own crate means neither base crate depends on the other: `bdk_wallet` stays stable, `bdk_tx` stays free to move, and the bridge absorbs the coupling (the decoupling argument from bitcoindevkit/bdk_wallet#297). Three-stage pipeline: - `candidates`/`candidates_with`/`rbf_candidates` -> `CandidateSet` (stage 1). - `select` -> `(TxTemplate, Option<AddressInfo>)` (stage 2): a pure read over a borrowed `&CandidateSet` (re-runnable) that peeks the auto-derived change address; commit it with `commit_change` (reveal + mark used) when you use the tx, or ignore it on abandon. The caller supplies the RNG. Emit the PSBT directly via `bdk_tx::TxTemplate::build_psbt`. - `add_global_xpubs` fills the PSBT's global xpubs (the only emission step that needs the wallet). Ported from the bdk_wallet#502 PoC, re-expressed over the integrated bdk_tx API and the wallet's public accessors. MTP is faked from the confirmation block time; UTXO locking is honored; `longterm_feerate` lives on `SelectParams` and feeds the waste-aware change policy for every strategy. End-to-end tests cover the pipeline, candidate filtering, change commit, and error paths. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

evanlinjin · 2026-06-28T10:04:46Z

+    /// One of the transactions to be replaced is already confirmed
+    TransactionConfirmed(Txid),


I don't think this error variant earns it's keep.

Most callers would want to check whether the transaction is still unconfirmed before trying to replace it. A caller that doesn't do that obviously wants to create a transaction that conflicts with a confirmed one.

The guard is partial. It only catches "already confirmed at build time". The original transaction can be confirmed before the replacement is ready to broadcast.

Bridge between bdk_wallet and bdk_tx, exposed as a `WalletTxExt` extension trait on `bdk_wallet::Wallet`. Keeping it in its own crate means neither base crate depends on the other: `bdk_wallet` stays stable, `bdk_tx` stays free to move, and the bridge absorbs the coupling (the decoupling argument from bitcoindevkit/bdk_wallet#297). Three-stage pipeline: - `candidates`/`candidates_with`/`rbf_candidates` -> `CandidateSet` (stage 1). - `select` -> `(TxTemplate, Option<AddressInfo>)` (stage 2): a pure read over a borrowed `&CandidateSet` (re-runnable) that peeks the auto-derived change address; commit it with `commit_change` (reveal + mark used) when you use the tx, or ignore it on abandon. The caller supplies the RNG. Emit the PSBT directly via `bdk_tx::TxTemplate::build_psbt`. - `add_global_xpubs` fills the PSBT's global xpubs (the only emission step that needs the wallet). Ported from the bdk_wallet#502 PoC, re-expressed over the integrated bdk_tx API and the wallet's public accessors. MTP is faked from the confirmation block time; UTXO locking is honored; `longterm_feerate` lives on `SelectParams` and feeds the waste-aware change policy for every strategy. End-to-end tests cover the pipeline, candidate filtering, change commit, and error paths. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

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

Comment thread src/wallet/mod.rs

Comment thread src/psbt/params.rs Outdated

Comment thread src/psbt/params.rs

Comment thread src/psbt/params.rs Outdated

Comment thread src/psbt/params.rs Outdated

Comment thread src/wallet/mod.rs Outdated

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

evanlinjin reviewed Jun 28, 2026

View reviewed changes

bitcoindevkit locked as too heated and limited conversation to collaborators Jun 30, 2026

		/// One of the transactions to be replaced is already confirmed
		TransactionConfirmed(Txid),

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

Changed

Added

Checklists

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!

Uh oh!

Uh oh!

Uh oh!

oleonardolima left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

oleonardolima Sep 15, 2025

Choose a reason for hiding this comment

Uh oh!

ValuedMammal Dec 18, 2025

Choose a reason for hiding this comment

Uh oh!

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!

evanlinjin Jun 28, 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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

12 participants

ValuedMammal commented Aug 12, 2025 •

edited

Loading

coveralls commented Aug 26, 2025 •

edited

Loading

ValuedMammal commented Sep 20, 2025 •

edited

Loading

ValuedMammal commented Oct 1, 2025 •

edited

Loading

evanlinjin Jun 28, 2026 •

edited

Loading