feat(selector)!: allow multiple change sources

Changed `change_descriptor` to `change_script: ScriptSource`
in both Selector and SelectorParams.

Added `change_weights` as a field of SelectorParams and removed
`to_cs_change_weights`. An alternative is to require the
ChangePolicy directly, or perhaps make ChangePolicyType more flexible.

Implement `From<(ScriptSource, Amount)>` for Output.

example: Add helper on example Wallet to return the drain weights
which can then be passed to `SelectorParams::new`.

Author: ValuedMammal

examples/common.rs

@@ -4,9 +4,10 @@ use bdk_bitcoind_rpc::{Emitter, NO_EXPECTED_MEMPOOL_TXIDS};
 use bdk_chain::{
     bdk_core, Anchor, Balance, CanonicalizationParams, ChainPosition, ConfirmationBlockTime,
 };
+use bdk_coin_select::DrainWeights;
 use bdk_testenv::{bitcoincore_rpc::RpcApi, TestEnv};
 use bdk_tx::{CanonicalUnspents, Input, InputCandidates, RbfParams, TxStatus, TxWithStatus};
-use bitcoin::{absolute, Address, BlockHash, OutPoint, Transaction, Txid};
+use bitcoin::{absolute, Address, Amount, BlockHash, OutPoint, Transaction, TxOut, Txid};
 use miniscript::{
     plan::{Assets, Plan},
     Descriptor, DescriptorPublicKey, ForEachKey,
@@ -134,6 +135,30 @@ impl Wallet {
             .map(|c_tx| (c_tx.tx_node.tx, status_from_position(c_tx.chain_position)))
     }
 
+    /// Computes an upper bound on the weight of a change output plus the future weight to spend it.
+    pub fn change_weight(&self) -> DrainWeights {
+        let desc = self
+            .graph
+            .index
+            .get_descriptor(INTERNAL)
+            .unwrap()
+            .at_derivation_index(0)
+            .unwrap();
+        let output_weight = TxOut {
+            script_pubkey: desc.script_pubkey(),
+            value: Amount::ZERO,
+        }
+        .weight()
+        .to_wu();
+        let spend_weight = desc.max_weight_to_satisfy().unwrap().to_wu();
+
+        DrainWeights {
+            output_weight,
+            spend_weight,
+            n_outputs: 1,
+        }
+    }
+
     pub fn all_candidates(&self) -> bdk_tx::InputCandidates {
         let index = &self.graph.index;
         let assets = self.assets();

examples/synopsis.rs

@@ -1,7 +1,7 @@
 use bdk_testenv::{bitcoincore_rpc::RpcApi, TestEnv};
 use bdk_tx::{
     filter_unspendable_now, group_by_spk, selection_algorithm_lowest_fee_bnb, ChangePolicyType,
-    Output, PsbtParams, SelectorParams, Signer,
+    Output, PsbtParams, ScriptSource, SelectorParams, Signer,
 };
 use bitcoin::{key::Secp256k1, Amount, FeeRate, Sequence};
 use miniscript::Descriptor;
@@ -60,8 +60,9 @@ fn main() -> anyhow::Result<()> {
                     recipient_addr.script_pubkey(),
                     Amount::from_sat(21_000_000),
                 )],
-                bdk_tx::ScriptSource::Descriptor(Box::new(internal.at_derivation_index(0)?)),
-                bdk_tx::ChangePolicyType::NoDustAndLeastWaste { longterm_feerate },
+                ScriptSource::Descriptor(Box::new(internal.at_derivation_index(0)?)),
+                ChangePolicyType::NoDustAndLeastWaste { longterm_feerate },
+                wallet.change_weight(),
             ),
         )?;
 
@@ -134,10 +135,11 @@ fn main() -> anyhow::Result<()> {
                     // be less wasteful to have no output, however that will not be a valid tx).
                     // If you only want to fee bump, put the original txs' recipients here.
                     target_outputs: vec![],
-                    change_source: bdk_tx::ScriptSource::Descriptor(Box::new(
+                    change_script: ScriptSource::Descriptor(Box::new(
                         internal.at_derivation_index(1)?,
                     )),
                     change_policy: ChangePolicyType::NoDustAndLeastWaste { longterm_feerate },
+                    change_weight: wallet.change_weight(),
                     // This ensures that we satisfy mempool-replacement policy rules 4 and 6.
                     replace: Some(rbf_params),
                 },

src/output.rs

@@ -1,26 +1,21 @@
 use alloc::boxed::Box;
-use bitcoin::{Amount, ScriptBuf, TxOut, Weight};
+use bitcoin::{Amount, ScriptBuf, TxOut};
 use miniscript::bitcoin;
 
 use crate::DefiniteDescriptor;
 
 /// Source of the output script pubkey
 #[derive(Debug, Clone)]
 pub enum ScriptSource {
-    /// a bitcoin script pubkey optionally with its max satisfaction weight
-    Script {
-        /// the script
-        script_pubkey: ScriptBuf,
-        /// the max weight at which the script can be satisfied
-        max_weight_to_satisfy: Option<Weight>,
-    },
+    /// bitcoin script
+    Script(ScriptBuf),
     /// definite descriptor
     Descriptor(Box<DefiniteDescriptor>),
 }
 
 impl From<ScriptBuf> for ScriptSource {
     fn from(script: ScriptBuf) -> Self {
-        Self::from_script(script, None)
+        Self::from_script(script)
     }
 }
 
@@ -32,11 +27,8 @@ impl From<DefiniteDescriptor> for ScriptSource {
 
 impl ScriptSource {
     /// From script
-    pub fn from_script(script_pubkey: ScriptBuf, max_weight_to_satisfy: Option<u64>) -> Self {
-        Self::Script {
-            script_pubkey,
-            max_weight_to_satisfy: max_weight_to_satisfy.map(Weight::from_wu),
-        }
+    pub fn from_script(script: ScriptBuf) -> Self {
+        Self::Script(script)
     }
 
     /// From descriptor
@@ -47,15 +39,15 @@ impl ScriptSource {
     /// To ScriptBuf
     pub fn script(&self) -> ScriptBuf {
         match self {
-            ScriptSource::Script { script_pubkey, .. } => script_pubkey.clone(),
+            ScriptSource::Script(spk) => spk.clone(),
             ScriptSource::Descriptor(descriptor) => descriptor.script_pubkey(),
         }
     }
 
     /// Get descriptor (if any).
     pub fn descriptor(&self) -> Option<&DefiniteDescriptor> {
         match self {
-            ScriptSource::Script { .. } => None,
+            ScriptSource::Script(_) => None,
             ScriptSource::Descriptor(descriptor) => Some(descriptor),
         }
     }
@@ -82,6 +74,15 @@ impl From<(DefiniteDescriptor, Amount)> for Output {
     }
 }
 
+impl From<(ScriptSource, Amount)> for Output {
+    fn from((src, value): (ScriptSource, Amount)) -> Self {
+        match src {
+            ScriptSource::Descriptor(desc) => Self::with_descriptor(*desc, value),
+            ScriptSource::Script(s) => Self::with_script(s, value),
+        }
+    }
+}
+
 impl Output {
     /// From script
     pub fn with_script(script: ScriptBuf, value: Amount) -> Self {

src/selector.rs

@@ -1,7 +1,7 @@
 use bdk_coin_select::{
     ChangePolicy, DrainWeights, InsufficientFunds, Replace, Target, TargetFee, TargetOutputs,
 };
-use bitcoin::{Amount, FeeRate, Transaction, TxOut, Weight};
+use bitcoin::{Amount, FeeRate, Transaction, Weight};
 use miniscript::bitcoin;
 
 use crate::{cs_feerate, InputCandidates, InputGroup, Output, ScriptSource, Selection};
@@ -15,7 +15,7 @@ pub struct Selector<'c> {
     target_outputs: Vec<Output>,
     target: Target,
     change_policy: bdk_coin_select::ChangePolicy,
-    change_source: ScriptSource,
+    change_script: ScriptSource,
     inner: bdk_coin_select::CoinSelector<'c>,
 }
 
@@ -42,11 +42,14 @@ pub struct SelectorParams {
     /// To derive change output.
     ///
     /// Will error if this is unsatisfiable descriptor.
-    pub change_source: ScriptSource,
+    pub change_script: ScriptSource,
 
     /// The policy to determine whether we create a change output.
     pub change_policy: ChangePolicyType,
 
+    /// Weight of the change output plus the future weight to spend the change
+    pub change_weight: DrainWeights,
+
     /// Params for replacing tx(s).
     pub replace: Option<RbfParams>,
 }
@@ -140,14 +143,16 @@ impl SelectorParams {
     pub fn new(
         target_feerate: bitcoin::FeeRate,
         target_outputs: Vec<Output>,
-        change_source: ScriptSource,
+        change_script: ScriptSource,
         change_policy: ChangePolicyType,
+        change_weight: DrainWeights,
     ) -> Self {
         Self {
-            change_source,
-            change_policy,
             target_feerate,
             target_outputs,
+            change_script,
+            change_policy,
+            change_weight,
             replace: None,
         }
     }
@@ -171,53 +176,14 @@ impl SelectorParams {
         }
     }
 
-    /// To change output weights.
-    ///
-    /// # Error
-    ///
-    /// Fails if `change_source` cannot be satisfied.
-    pub fn to_cs_change_weights(&self) -> Result<bdk_coin_select::DrainWeights, SelectorError> {
-        let (script_pubkey, spend_weight) = match &self.change_source {
-            ScriptSource::Script {
-                script_pubkey,
-                max_weight_to_satisfy,
-            } => {
-                if let Some(weight) = max_weight_to_satisfy {
-                    (script_pubkey.clone(), weight.to_wu())
-                } else {
-                    return Err(SelectorError::MissingChangeSatisfactionWeight);
-                }
-            }
-            ScriptSource::Descriptor(definite_descriptor) => {
-                let script_pubkey = definite_descriptor.script_pubkey();
-                let weight = definite_descriptor
-                    .max_weight_to_satisfy()
-                    .map(|weight| weight.to_wu())
-                    .map_err(SelectorError::Miniscript)?;
-                (script_pubkey, weight)
-            }
-        };
-        let drain_weight = DrainWeights {
-            output_weight: (TxOut {
-                script_pubkey,
-                value: Amount::ZERO,
-            })
-            .weight()
-            .to_wu(),
-            spend_weight,
-            n_outputs: 1,
-        };
-        Ok(drain_weight)
-    }
-
     /// To change policy.
     ///
     /// # Error
     ///
-    /// Fails if `change_source` cannot be satisfied.
-    pub fn to_cs_change_policy(&self) -> Result<bdk_coin_select::ChangePolicy, SelectorError> {
-        let change_weights = self.to_cs_change_weights()?;
-        let dust_value = self.change_source.script().minimal_non_dust().to_sat();
+    /// Fails if `change_descriptor` cannot be satisfied.
+    pub fn to_cs_change_policy(&self) -> Result<bdk_coin_select::ChangePolicy, miniscript::Error> {
+        let change_weights = self.change_weight;
+        let dust_value = self.change_script.script().minimal_non_dust().to_sat();
         Ok(match self.change_policy {
             ChangePolicyType::NoDust => ChangePolicy::min_value(change_weights, dust_value),
             ChangePolicyType::NoDustAndLeastWaste { longterm_feerate } => {
@@ -255,19 +221,13 @@ pub enum SelectorError {
     Miniscript(miniscript::Error),
     /// meeting the target is not possible
     CannotMeetTarget(CannotMeetTarget),
-    /// missing weight to satisfy change output
-    MissingChangeSatisfactionWeight,
 }
 
 impl fmt::Display for SelectorError {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         match self {
             Self::Miniscript(err) => write!(f, "{err}"),
             Self::CannotMeetTarget(err) => write!(f, "{err}"),
-            Self::MissingChangeSatisfactionWeight => write!(
-                f,
-                "Cannot determinate change policy without satisfaction weight"
-            ),
         }
     }
 }
@@ -287,9 +247,11 @@ impl<'c> Selector<'c> {
         params: SelectorParams,
     ) -> Result<Self, SelectorError> {
         let target = params.to_cs_target();
-        let change_policy = params.to_cs_change_policy()?;
+        let change_policy = params
+            .to_cs_change_policy()
+            .map_err(SelectorError::Miniscript)?;
         let target_outputs = params.target_outputs;
-        let change_source = params.change_source;
+        let change_script = params.change_script;
         if target.value() > candidates.groups().map(|grp| grp.value().to_sat()).sum() {
             return Err(SelectorError::CannotMeetTarget(CannotMeetTarget));
         }
@@ -302,7 +264,7 @@ impl<'c> Selector<'c> {
             target,
             target_outputs,
             change_policy,
-            change_source,
+            change_script,
             inner,
         })
     }
@@ -379,16 +341,10 @@ impl<'c> Selector<'c> {
             outputs: {
                 let mut outputs = self.target_outputs.clone();
                 if maybe_change.is_some() {
-                    let change_amount = Amount::from_sat(maybe_change.value);
-                    let change_output = match &self.change_source {
-                        ScriptSource::Descriptor(definite_descriptor) => {
-                            Output::with_descriptor(*definite_descriptor.clone(), change_amount)
-                        }
-                        ScriptSource::Script { script_pubkey, .. } => {
-                            Output::with_script(script_pubkey.clone(), change_amount)
-                        }
-                    };
-                    outputs.push(change_output);
+                    outputs.push(Output::from((
+                        self.change_script.clone(),
+                        Amount::from_sat(maybe_change.value),
+                    )));
                 }
                 outputs
             },