feat: add bdk_wallet_tx bridge crate (workspace)

[evanlinjin]

Description

Adds bdk_wallet_tx, a bridge crate that drives bdk_tx's multi-stage transaction building from a bdk_wallet::Wallet, and converts this repo into a Cargo workspace to house it (tx/ = bdk_tx, wallet_tx/ = bdk_wallet_tx).

This is an alternative to embedding bdk_tx in bdk_wallet (bitcoindevkit/bdk_wallet#297, #502). Putting bdk_tx's pre-stable types in bdk_wallet's public API would couple the stable crate to a fast-moving one — every breaking bdk_tx release would force a bdk_wallet major. A separate crate depending on both means neither base crate depends on the other; the bridge absorbs the coupling and is versioned on its own. (Rationale: bitcoindevkit/bdk_wallet#297 comment.)

WalletTxExt for bdk_wallet::Wallet exposes a three-stage pipeline (ported from the bdk_wallet#502 PoC, re-expressed over the integrated bdk_tx API and the wallet's public accessors):

use bdk_tx::BuildPsbtParams;
use bdk_wallet_tx::{WalletTxExt, SelectParams, SelectionStrategy};

// 1. Candidates — resolve the wallet's spendable inputs (incl. RBF via `rbf_candidates`).
let coins = wallet.candidates()?;

// 2. Select — a *pure read*: returns the `TxTemplate` and the auto-derived change address (peeked).
let (template, change) = wallet.select(&coins, SelectParams {
    recipients: vec![(recipient_spk, amount)],
    coin_selection: SelectionStrategy::SingleRandomDraw,
    feerate,
    longterm_feerate: None,
    change_script: None,
}, &mut rng)?;

// 3. Emit the PSBT directly via bdk_tx. Reserve the change address so a later `select` won't
//    reuse it (reveal + mark used; then persist the change set); optionally add global xpubs.
let (mut psbt, finalizer) = template.build_psbt(BuildPsbtParams::default())?;
if let Some(c) = &change { wallet.reserve_change(c); }
wallet.add_global_xpubs(&mut psbt)?;

Notes to the reviewers

⚠️ This branch is stacked on #73, #74, #79, #81, #82 (cherry-picked onto master), so most of the diff is their commits. The load-bearing dependency is the TxTemplate stage (#73) — without the multi-stage pipeline there's nothing to bridge; #82 reshapes the selection entry point this crate calls, and #74/#79/#81 are independent bdk_tx improvements bundled here for the integrated state. They don't all need to land in lockstep — once the TxTemplate line is in, this rebases down to just the workspace + bridge commits.

The commits worth reviewing here — everything else is a cherry-pick (review those in their own PRs):

Commit	What
59a29ff	feat: add bdk_wallet_tx bridge crate — the crux of this PR
0010fe4	convert the repo into a Cargo workspace
e97ef02, df09bd3	reconcile the #74 / #79 tests with #73's TxTemplate / build_psbt API
b5eca4e	trivial rustfmt after the #73 / #82 merge

One caveat: the #82 commits as they appear here (4c0262d, 2de1dce, 3d49606) carry conflict resolution against #73 — the merged entry point is InputCandidates::into_tx_template(algorithm, SelectionParams) -> Result<TxTemplate, IntoTxTemplateError> (#73's tx-template staging on #82's single-pass internals, Selector removed). If you care about that reconciliation, diff them against pristine #82.

Change-address lifecycle (a deliberate departure from TxBuilder)

bdk_wallet's TxBuilder::finish() revealed and staged the change address implicitly, as a side effect of building the PSBT — building a transaction always mutated wallet state, whether or not you went on to broadcast it. Here it is explicit and caller-driven: select only peeks the change address (a pure &self read returning the change AddressInfo alongside the template, or None when caller-supplied / no change output), and you reserve_change it (= reveal_addresses_to + mark_used) to claim a distinct change address — reversible with unmark_used if that selection ends up unused. Benefits:

• Abandon is free. Speculative builds — fee estimation, trying different params, UI previews, picking the cheapest of several strategies — cost nothing in wallet state: no revealed-but-unused change addresses, no changeset to discard. The peeked address is simply reused next time.
• Selection is a side-effect-free read. select mutates nothing, so it is re-runnable (over a borrowed &CandidateSet) and safe to call freely; the only changeset to persist comes from reserve_change, so persistence is deliberate rather than "after every build".
• Reuse control is correct and explicit. reserve_change bundles reveal and mark_used, so reserving a selection guarantees the next select draws a fresh change address. Batching several txs before broadcasting is therefore correct by construction — no address reuse — and you choose exactly which selections to reserve. (Excluding an already-built tx's inputs from the next candidate set is just coins.filter(..), since select borrows coins.) The returned AddressInfo.keychain is pre-mapped, so it's safe for mark_used/unmark_used (which don't map it) on single-descriptor wallets — an upstream bug fixed by bitcoindevkit/bdk_wallet#507; once that lands the pre-mapping workaround here can be dropped.

The trade-off is explicitness: you must reserve_change (and persist) the selections you might broadcast, and unmark_used any you drop — finish() revealed automatically. That's the intended shift: from automatic but always-mutating to explicit but controllable.

Other design notes for the bridge (59a29ff):

• No stage-3 wrapper. TxTemplate::build_psbt needs nothing from the wallet, so callers invoke it directly; the only wallet-specific emission step, filling global xpubs, is add_global_xpubs(&mut Psbt).
• Candidate spendability filtering (CandidateParams). Auto-gathered candidates are filtered after planning, via InputCandidates::filter (so manually-selected must_spend inputs are never dropped): coins locked through Wallet::lock_outpoint, already-spent outputs, and — gated by allow_immature / allow_timelocked (both default false) — immature coinbase and not-yet-spendable CLTV/CSV outputs are excluded. Height-based timelocks resolve exactly; time-based locks need median-time-past, which bdk_wallet doesn't retain, so the caller supplies it: tip_mtp (a single value — absolute CLTV-time and the tip side of relative locks) and fetch_mtp: Option<Box<MtpOracle>> (a per-input Fn(BlockId) -> Option<Time> oracle filling each input's prev_mtp — relative CSV-time locks). Without them, time-based-locked inputs stay unresolved and are conservatively excluded. Unlike #502 we never fabricate MTP (prev_mtp is None absent an oracle); the eventual clean fix is MTP retained on checkpoints upstream.
• No anti-fee-sniping. The template is unshuffled with no AFS — the caller applies template.apply_anti_fee_sniping(tip_height, rng) / shuffle_outputs(rng) before emitting the PSBT.
• longterm_feerate lives on SelectParams (not SelectionStrategy::LowestFee): it feeds the waste-aware change policy for every strategy, and post-refactor!: Replace Selector with a single into_selection pass #82 the bnb metric reads it from SelectionParams.
• Errors: CandidatesError (stage 1), SelectError (stage 2), MissingKeyOrigin (add_global_xpubs).
• Target: bdk_wallet master @ 58fe631 (the commit #502 is based on), pinned as a git dependency. Its test-utils needs tempfile >= 3.26, bumped in the lockfile.

Tested via wallet_tx/tests/three_stage.rs (SingleRandomDraw, DrainAll, LowestFee, change peek/reserve, locked-outpoint exclusion, add_global_xpubs, and the NoRecipients error) against a deterministically-funded bdk_wallet — no bitcoind. cargo fmt/clippy/doc/test are green across the workspace; bdk_tx still builds no_std.

Changelog notice

Added:
- New `bdk_wallet_tx` bridge crate: a `WalletTxExt` extension trait on `bdk_wallet::Wallet`
  exposing a three-stage transaction-building pipeline over `bdk_tx`
  (`candidates`/`rbf_candidates` -> `select` -> `add_global_xpubs`), with `reserve_change`
  for the auto-derived change address.

Changed:
- The repository is now a Cargo workspace; the `bdk_tx` crate has moved to `tx/`.

Before submitting

• I followed the contribution guidelines
• This PR breaks the existing API