feat(wallet): descriptors + PSBT v2 + bdk_coin_select + fee bump + NO signing surface

Op: extend

Author: bitcoin-rs

.github/workflows/ci.yml

@@ -14,6 +14,13 @@ env:
   PORTABLE_FEATURES: "rocksdb,fjall,redb"
 
 jobs:
+  wallet-no-seckey:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: |
+          ! grep -r 'SecretKey\|secp256k1::Secret\|seckey' crates/wallet/src
+
   fmt:
     runs-on: ubuntu-latest
     steps:

crates/wallet/Cargo.toml

@@ -12,3 +12,32 @@ description = "bitcoin-rs :: wallet"
 workspace = true
 
 [dependencies]
+bitcoin-rs-primitives.workspace = true
+bitcoin-rs-script.workspace = true
+bitcoin-rs-index.workspace = true
+bitcoin-rs-storage.workspace = true
+bitcoin.workspace = true
+miniscript.workspace = true
+bdk_coin_select.workspace = true
+secp256k1 = { workspace = true, default-features = false, features = ["std", "alloc"] }
+parking_lot.workspace = true
+arc-swap.workspace = true
+hashbrown.workspace = true
+tinyvec.workspace = true
+smallvec.workspace = true
+thiserror.workspace = true
+tracing.workspace = true
+serde.workspace = true
+serde_json.workspace = true
+
+[dev-dependencies]
+bitcoin-rs-consensus.workspace = true
+proptest.workspace = true
+tempfile = "3"
+
+[features]
+default = []
+rocksdb = ["bitcoin-rs-storage/rocksdb"]
+fjall = ["bitcoin-rs-storage/fjall"]
+redb = ["bitcoin-rs-storage/redb"]
+mdbx = ["bitcoin-rs-storage/mdbx"]

crates/wallet/src/coin_selection.rs

@@ -0,0 +1,180 @@
+use bdk_coin_select::metrics::{Changeless, LowestFee};
+use bdk_coin_select::{
+    Candidate as BdkCandidate, ChangePolicy, CoinSelector, DrainWeights, FeeRate,
+    Target as BdkTarget, TargetFee, TargetOutputs,
+};
+use serde::{Deserialize, Serialize};
+
+use crate::WalletError;
+
+/// Candidate input for wallet coin selection.
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub struct Candidate {
+    /// Candidate value in satoshis.
+    pub value: u64,
+    /// Estimated satisfaction weight in weight units.
+    pub satisfaction_weight: u64,
+    /// Whether spending this candidate uses segwit witness data.
+    pub is_segwit: bool,
+}
+
+impl Candidate {
+    /// Converts into the upstream selector candidate type.
+    #[must_use]
+    pub fn to_bdk(self) -> BdkCandidate {
+        BdkCandidate::new(self.value, self.satisfaction_weight, self.is_segwit)
+    }
+}
+
+/// Funding target for coin selection.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub struct Target {
+    /// Output value that must be funded.
+    pub value: u64,
+    /// Minimum absolute fee in satoshis.
+    pub minimum_fee: u64,
+    /// Target feerate for input-weight-aware selection.
+    pub fee_rate: FeeRate,
+}
+
+impl Target {
+    /// Creates a target from value, minimum fee, and feerate.
+    #[must_use]
+    pub const fn new(value: u64, minimum_fee: u64, fee_rate: FeeRate) -> Self {
+        Self {
+            value,
+            minimum_fee,
+            fee_rate,
+        }
+    }
+
+    fn to_bdk(self) -> Result<BdkTarget, WalletError> {
+        let value_sum = self
+            .value
+            .checked_add(self.minimum_fee)
+            .ok_or_else(|| WalletError::Psbt("target value overflow".to_owned()))?;
+        Ok(BdkTarget {
+            fee: TargetFee::from_feerate(self.fee_rate),
+            outputs: TargetOutputs {
+                value_sum,
+                weight_sum: 0,
+                n_outputs: 1,
+            },
+        })
+    }
+}
+
+/// Coin selection strategy.
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub enum SelectStrategy {
+    /// Branch-and-bound changeless-first selection.
+    BnB,
+    /// Greedy knapsack-style selection.
+    Knapsack,
+    /// Waste metric selection using long-term feerate accounting.
+    WasteMetric,
+}
+
+/// Selected input set.
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub struct Selection {
+    /// Indices selected from the candidate slice.
+    pub selected_indices: Vec<usize>,
+    /// Sum of selected candidate values.
+    pub selected_value: u64,
+    /// Fee implied by selected value minus target output value.
+    pub fee: u64,
+}
+
+/// Selects coins with the requested strategy.
+pub fn select_coins(
+    target: &Target,
+    candidates: &[Candidate],
+    strategy: SelectStrategy,
+) -> Result<Selection, WalletError> {
+    let bdk_candidates: Vec<BdkCandidate> =
+        candidates.iter().copied().map(Candidate::to_bdk).collect();
+    let bdk_target = target.to_bdk()?;
+    let mut selector = CoinSelector::new(&bdk_candidates);
+
+    match strategy {
+        SelectStrategy::BnB => select_bnb(&mut selector, bdk_target)?,
+        SelectStrategy::Knapsack => select_knapsack(&mut selector, bdk_target)?,
+        SelectStrategy::WasteMetric => select_waste(&mut selector, bdk_target)?,
+    }
+
+    to_selection(&selector, target)
+}
+
+fn select_bnb(selector: &mut CoinSelector<'_>, target: BdkTarget) -> Result<(), WalletError> {
+    let change_policy = ChangePolicy::min_value(DrainWeights::TR_KEYSPEND, 0);
+    selector.sort_candidates_by_descending_value_pwu();
+    let metric = Changeless {
+        target,
+        change_policy,
+    };
+    if selector.run_bnb(metric, 100_000).is_ok() {
+        return Ok(());
+    }
+    selector
+        .select_until_target_met(target)
+        .map_err(|error| WalletError::InsufficientFunds {
+            missing: error.missing,
+        })
+}
+
+fn select_knapsack(selector: &mut CoinSelector<'_>, target: BdkTarget) -> Result<(), WalletError> {
+    selector.sort_candidates_by_key(|(_index, candidate)| core::cmp::Reverse(candidate.value));
+    selector
+        .select_until_target_met(target)
+        .map_err(|error| WalletError::InsufficientFunds {
+            missing: error.missing,
+        })
+}
+
+fn select_waste(selector: &mut CoinSelector<'_>, target: BdkTarget) -> Result<(), WalletError> {
+    selector.sort_candidates_by_descending_value_pwu();
+    let change_policy = ChangePolicy::min_value_and_waste(
+        DrainWeights::TR_KEYSPEND,
+        0,
+        target.fee.rate,
+        FeeRate::DEFAULT_MIN_RELAY,
+    );
+    let metric = LowestFee {
+        target,
+        long_term_feerate: FeeRate::DEFAULT_MIN_RELAY,
+        change_policy,
+    };
+    if let Err(error) = selector.run_bnb(metric, 100_000) {
+        selector.select_until_target_met(target).map_err(|funds| {
+            WalletError::InsufficientFunds {
+                missing: funds.missing,
+            }
+        })?;
+        if !selector.is_target_met(target) {
+            return Err(WalletError::NoBnbSolution {
+                rounds: error.rounds,
+                max_rounds: error.max_rounds,
+            });
+        }
+    }
+    Ok(())
+}
+
+fn to_selection(selector: &CoinSelector<'_>, target: &Target) -> Result<Selection, WalletError> {
+    let selected_value = selector.selected_value();
+    let target_with_fee = target
+        .value
+        .checked_add(target.minimum_fee)
+        .ok_or_else(|| WalletError::Psbt("target value overflow".to_owned()))?;
+    if selected_value < target_with_fee {
+        return Err(WalletError::InsufficientFunds {
+            missing: target_with_fee - selected_value,
+        });
+    }
+    Ok(Selection {
+        selected_indices: selector.selected_indices().iter().copied().collect(),
+        selected_value,
+        fee: selected_value - target.value,
+    })
+}

crates/wallet/src/descriptor.rs

@@ -0,0 +1,89 @@
+use core::str::FromStr;
+
+use bitcoin::bip32::{ChildNumber, DerivationPath, Fingerprint};
+use bitcoin::{Address, Network, PublicKey};
+use miniscript::Descriptor as MiniscriptDescriptor;
+use miniscript::descriptor::DescriptorType;
+use serde::{Deserialize, Serialize};
+
+use crate::WalletError;
+
+/// Public BIP32 origin metadata attached to descriptor keys.
+#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
+pub struct BIP32Derivation {
+    /// Master key fingerprint for the origin key, when known.
+    pub fingerprint: Option<Fingerprint>,
+    /// Non-hardened public derivation path, when known.
+    pub path: DerivationPath,
+}
+
+impl BIP32Derivation {
+    /// Returns a copy with `index` appended as a normal child number.
+    pub fn with_child(&self, index: u32) -> Result<Self, WalletError> {
+        let child = ChildNumber::from_normal_idx(index)
+            .map_err(|error| WalletError::Descriptor(error.to_string()))?;
+        let mut children: Vec<ChildNumber> = self.path.into_iter().copied().collect();
+        children.push(child);
+        Ok(Self {
+            fingerprint: self.fingerprint,
+            path: DerivationPath::from(children),
+        })
+    }
+}
+
+/// Public, watch-only output descriptor.
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub struct Descriptor {
+    /// Parsed miniscript descriptor with public keys only.
+    pub inner: MiniscriptDescriptor<PublicKey>,
+    /// Public BIP32 derivation metadata.
+    pub derivation: BIP32Derivation,
+}
+
+impl Descriptor {
+    /// Parses one supported public descriptor form.
+    pub fn parse(text: &str) -> Result<Self, WalletError> {
+        let inner = MiniscriptDescriptor::<PublicKey>::from_str(text)
+            .map_err(|error| WalletError::Descriptor(error.to_string()))?;
+        ensure_supported(&inner)?;
+        Ok(Self {
+            inner,
+            derivation: BIP32Derivation::default(),
+        })
+    }
+
+    /// Derives the receive address for a descriptor index.
+    pub fn derive_address(&self, network: Network, index: u32) -> Result<Address, WalletError> {
+        let _derivation = self.derivation.with_child(index)?;
+        self.inner
+            .address(network)
+            .map_err(|error| WalletError::Descriptor(error.to_string()))
+    }
+
+    /// Returns the descriptor script pubkey.
+    #[must_use]
+    pub fn script_pubkey(&self) -> bitcoin::ScriptBuf {
+        self.inner.script_pubkey()
+    }
+}
+
+impl FromStr for Descriptor {
+    type Err = WalletError;
+
+    fn from_str(text: &str) -> Result<Self, Self::Err> {
+        Self::parse(text)
+    }
+}
+
+fn ensure_supported(descriptor: &MiniscriptDescriptor<PublicKey>) -> Result<(), WalletError> {
+    match descriptor.desc_type() {
+        DescriptorType::Pkh
+        | DescriptorType::Wpkh
+        | DescriptorType::ShWpkh
+        | DescriptorType::Wsh
+        | DescriptorType::Tr => Ok(()),
+        other => Err(WalletError::Descriptor(format!(
+            "unsupported descriptor type {other:?}"
+        ))),
+    }
+}