feat(wallet): Three-stage PSBT creation over bdk_tx::TxTemplate (PoC for discussion)

[evanlinjin]

Description

This is a proof-of-concept opened for discussion — not a merge-ready PR. It explores an alternative design to #297 so we can compare API shapes side by side and decide on a direction before polishing either one. Plenty here (naming, the missing convenience façade, the upstream bdk_tx dependency) is deliberately unfinished; I'm interested in feedback on the shape, not the finish.

Both approaches add PSBT creation to Wallet and produce identical PSBTs; they differ in where the complexity lives.

To cover the real cases (manual coin selection, foreign inputs, assets, sweep, RBF, fee policy, version/locktime/anti-fee-sniping, ordering, global xpubs), a single create_psbt(params) entry point needs one very large params type — in #297, a ~30-method typestate builder. That shape carries three costs that compound over time:

1. The wallet ends up re-declaring bdk_tx. Version, locktime, anti-fee-sniping, ordering, shuffling, and per-input/fallback sequence already exist in bdk_tx. Surfacing them as wallet options means wrapping and maintaining each, so every bdk_tx change becomes a wallet change and the option list grows to mirror a dependency we should simply be using.
2. Invalid or conflicting options only surface at the final call. A single params type only sorts two things out when create_psbt finally runs: conflicts (an explicit locktime next to anti_fee_sniping_height, both setting nLockTime, precedence hidden in docs) and invalid values (a sequence violating an input's CSV requirement isn't rejected when set — it surfaces only at build time, failing the whole process). The staged flow applies operations in explicit order, and each one (e.g. template.input_mut(op).set_sequence(..)) validates and errors at the call site, leaving the rest intact. This shape also suits frontend / interactive use well: a UI can resolve candidates once, let the user adjust selection and outputs against a live, inspectable CandidateSet/TxTemplate, and surface each error inline at the control that caused it — rather than filling a whole form and getting one wholesale failure at submit.
3. Nothing is reusable. A single call returning a finished PSBT can't resolve a candidate set once and build several transactions, or inspect/adjust the selection before committing.

The direction this PoC explores: the wallet should be a thin, composable layer over bdk_tx, not a façade that hides it. PSBT creation is three genuinely distinct concerns — what can I spend, what do I spend to hit this target, turn that into a PSBT — so it's modeled as three stages instead of one call:

let coins    = wallet.candidates()?;                               // 1. resolve
let template = wallet.select(coins, SelectParams {                 // 2. select → TxTemplate
    recipients, fee_rate, ..Default::default()
})?;
let template = template.shuffle_outputs(&mut rng);                 //    shape (bdk_tx methods)
let (psbt, finalizer) = wallet.finish(template, FinishParams::default())?;  // 3. emit

This makes the three costs go away: each stage has a small, focused params struct; transaction shaping happens on the returned bdk_tx::TxTemplate using bdk_tx's own methods (no re-wrapping, no drift); sweep and RBF become composable axes rather than special types (a sweep is DrainAll with no recipients; RBF is a field on the candidate params); and the intermediate values are real and inspectable.

Because the candidate set and the template are now real values the caller holds, several capabilities that the single-call design structurally could not expose fall out for free:

• Input grouping (CandidateSet::regroup) — group UTXOs by a key (e.g. address / script pubkey) so coin selection treats a group as one unit. This is privacy-relevant: it avoids spending some but not all UTXOs of an address. There was no way to express this through PsbtParams.
• Post-resolution filtering (CandidateSet::filter) — apply arbitrary predicates over the resolved inputs (by value, script, confirmation status, coinbase/maturity), beyond the fixed CandidateParams knobs.
• Resolve-once, select-many — reuse one resolved candidate set across multiple independent selections. This one isn't hypothetical: a large bdk_wallet user has already asked for exactly this, and the single-call design can't accommodate it without re-resolving the whole candidate set every time.
• Foreign inputs go straight onto the set — CandidateSet::push_must_select / push_can_select take pre-built bdk_tx::Inputs, so CandidateParams stays purely about deriving candidates from the wallet rather than also being a pass-through for caller-supplied bdk_tx values.
• RBF batching — for a replacement, CandidateSet::replaced_unspent() exposes the replaced txs' still-unspent wallet outputs, so a caller can re-create those payments when batching several txs into one replacement.
• bdk_tx escape hatch — CandidateSet::into_parts() (yielding the InputCandidates and any RbfParams) and the returned TxTemplate let a caller drop down to bdk_tx primitives for anything the wallet doesn't wrap, instead of being limited to the options the wallet chose to surface.

These aren't features bolted on — they're a direct consequence of modeling the stages as values rather than hiding them behind one call.

If anything the staged design is more ergonomic and transparent: the single-call approach is one large params struct where the options' relationships are hard to follow, whereas each stage here scopes its options so what's valid where is obvious. The one thing it gives up is the single-call one-liner for the trivial "send X to Y" case — and that convenience can be layered on top of the composable stages later, whereas composability can't be retrofitted onto a sealed call.

Full API surface (CandidateParams/SelectParams/FinishParams, SelectionStrategy, CandidateSet, and the per-stage CandidatesError/CreatePsbtError) is in the diff and rustdoc. Examples: examples/psbt.rs, examples/replace_by_fee.rs.

Notes to the reviewers

As a PoC, these are open for discussion rather than settled — they're the main things I'd want a decision on:

• Privacy default. select returns an unshuffled template; the caller must call shuffle_outputs. Deliberate and loudly documented, but it gives up Implement create_psbt for Wallet #297's shuffle-by-default safety. Should finish shuffle by default with an opt-out instead?
• No convenience façade. Intentionally omitted — add a one-call helper now, or wait for demand?
• Params are not #[non_exhaustive], so adding a field is breaking; kept this way to allow inline ..Default::default() construction. Open to revisiting.
• Determinism. Candidate construction is RNG-free; randomness lives only in select (via Selector::select_with_algorithm).
• Upstream dependency. Requires bdk_tx's TxTemplate (feat: introduce TxTemplate as an intermediate stage bdk-tx#73) plus two small additions currently on the fork: a single_random_draw selection algorithm and InputCandidates::push_must_select / push_can_select. The branch points bdk_tx at that fork and must be repointed to upstream before merge.

Changelog notice

• Added a three-stage PSBT-creation API to Wallet: candidates/rbf_candidates/candidates_with, select/select_with_rng, and finish, along with CandidateParams, SelectParams, FinishParams, SelectionStrategy, CandidateSet, and the CandidatesError/CreatePsbtError error types. CandidateSet supports push_must_select/push_can_select (foreign inputs), filter/regroup, replaced_unspent (RBF batching), and into_parts (bdk_tx escape hatch).

Checklists

All Submissions:

• I've signed all my commits
• I followed the contribution guidelines
• I ran just p before pushing

New Features:

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

[codecov]

Codecov Report

❌ Patch coverage is 83.66534% with 82 lines in your changes missing coverage. Please review.
✅ Project coverage is 81.54%. Comparing base (39de6ed) to head (e57a536).
⚠️ Report is 8 commits behind head on master.

Files with missing lines	Patch %	Lines
src/wallet/mod.rs	91.21%	27 Missing and 9 partials ⚠️
src/wallet/error.rs	0.00%	25 Missing ⚠️
src/psbt/params.rs	68.65%	21 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #502      +/-   ##
==========================================
+ Coverage   80.93%   81.54%   +0.60%     
==========================================
  Files          24       25       +1     
  Lines        5482     6004     +522     
  Branches      247      276      +29     
==========================================
+ Hits         4437     4896     +459     
- Misses        968     1022      +54     
- Partials       77       86       +9     

Flag	Coverage Δ
rust	81.54% <83.66%> (+0.60%)	⬆️

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

☔ View full report in Codecov by Harness.
📢 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.