feat!: enforce max_weight in Target

Author: aagbotemi

README.md

@@ -24,7 +24,8 @@ let outputs = vec![TxOut {
 
 let target = Target {
     outputs: TargetOutputs::fund_outputs(outputs.iter().map(|output| (output.weight().to_wu(), output.value.to_sat()))),
-    fee: TargetFee::from_feerate(FeeRate::from_sat_per_vb(42.0))
+    fee: TargetFee::from_feerate(FeeRate::from_sat_per_vb(42.0)),
+    max_weight: None
 };
 
 let candidates = vec![
@@ -130,6 +131,7 @@ let mut coin_selector = CoinSelector::new(&candidates);
 let target = Target {
     fee: TargetFee::from_feerate(FeeRate::from_sat_per_vb(15.0)),
     outputs: TargetOutputs::fund_outputs(outputs.iter().map(|output| (output.weight().to_wu(), output.value.to_sat()))),
+    max_weight: None
 };
 
 // The change output must be at least this size to be relayed.

src/coin_selector.rs

@@ -121,7 +121,7 @@ impl<'a> CoinSelector<'a> {
     pub fn is_selection_possible(&self, target: Target) -> bool {
         let mut test = self.clone();
         test.select_all_effective(target.fee.rate);
-        test.is_target_met(target)
+        test.excess(target, Drain::NONE) >= 0
     }
 
     /// Returns true if no candidates have been selected.
@@ -308,7 +308,7 @@ impl<'a> CoinSelector<'a> {
         self.selected_value() as i64 - (self.input_weight() as f32 * feerate.spwu()).ceil() as i64
     }
 
-    // /// Waste sum of all selected inputs.
+    /// Waste sum of all selected inputs.
     fn input_waste(&self, feerate: FeeRate, long_term_feerate: FeeRate) -> f32 {
         self.input_weight() as f32 * (feerate.spwu() - long_term_feerate.spwu())
     }
@@ -429,15 +429,20 @@ impl<'a> CoinSelector<'a> {
         self.unselected_indices().next().is_none()
     }
 
+    /// Whether the tx implied by the current selection and `drain` is within `target.max_weight`.
+    fn is_within_max_weight(&self, target: Target, drain: Drain) -> bool {
+        match target.max_weight {
+            Some(max_weight) => self.weight(target.outputs, drain.weights) <= max_weight,
+            None => true,
+        }
+    }
+
     /// Whether the constraints of `Target` have been met if we include a specific `drain` ouput.
     ///
-    /// Note if [`is_target_met`] is true and the `drain` is produced from the [`drain`] method then
-    /// this method will also always be true.
-    ///
-    /// [`is_target_met`]: Self::is_target_met
-    /// [`drain`]: Self::drain
+    /// Note: even if [`Self::is_target_met`] is true, this can be false when adding the `drain` pushes
+    /// the transaction weight over [`Target::max_weight`].
     pub fn is_target_met_with_drain(&self, target: Target, drain: Drain) -> bool {
-        self.excess(target, drain) >= 0
+        self.excess(target, drain) >= 0 && self.is_within_max_weight(target, drain)
     }
 
     /// Whether the constraints of `Target` have been met.
@@ -467,16 +472,15 @@ impl<'a> CoinSelector<'a> {
             },
         );
         if excess > change_policy.min_value as i64 {
-            debug_assert_eq!(
-                self.is_target_met(target),
-                self.is_target_met_with_drain(
+            debug_assert!(
+                self.excess(
                     target,
                     Drain {
                         weights: change_policy.drain_weights,
-                        value: excess as u64
-                    }
-                ),
-                "if the target is met without a drain it must be met after adding the drain"
+                        value: excess as u64,
+                    },
+                ) >= 0,
+                "if the target value is met without a drain it must be met after adding the drain"
             );
             Some(excess as u64)
         } else {
@@ -520,13 +524,26 @@ impl<'a> CoinSelector<'a> {
         }
     }
 
-    /// Select candidates until `target` has been met assuming the `drain` output is attached.
+    /// Select candidates until `target` has been met.
+    ///
+    /// # Errors
     ///
-    /// Returns an error if the target was unable to be met.
-    pub fn select_until_target_met(&mut self, target: Target) -> Result<(), InsufficientFunds> {
+    /// - [`SelectError::InsufficientFunds`] if the candidates can't cover the target value.
+    /// - [`SelectError::MaxWeightExceeded`] if the value is met but the selection exceeds
+    ///   [`Target::max_weight`].
+    pub fn select_until_target_met(&mut self, target: Target) -> Result<(), SelectError> {
         self.select_until(|cs| cs.is_target_met(target))
-            .ok_or_else(|| InsufficientFunds {
-                missing: self.excess(target, Drain::NONE).unsigned_abs(),
+            .ok_or_else(|| {
+                let excess = self.excess(target, Drain::NONE);
+                // excess < 0 means unfundable (InsufficientFunds),
+                // else value is met so the weight cap failed (MaxWeightExceeded).
+                if excess >= 0 {
+                    SelectError::MaxWeightExceeded
+                } else {
+                    SelectError::InsufficientFunds(InsufficientFunds {
+                        missing: excess.unsigned_abs(),
+                    })
+                }
             })
     }
 
@@ -641,6 +658,38 @@ impl DoubleEndedIterator for SelectIter<'_> {
     }
 }
 
+/// Error returned when a selection cannot satisfy the [`Target`].
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum SelectError {
+    /// The selected inputs don't cover the target value (plus fees).
+    InsufficientFunds(InsufficientFunds),
+    /// The target value is met, but the resulting transaction exceeds [`Target::max_weight`].
+    MaxWeightExceeded,
+}
+
+impl core::fmt::Display for SelectError {
+    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
+        match self {
+            Self::InsufficientFunds(e) => write!(f, "{}", e),
+            Self::MaxWeightExceeded => {
+                write!(
+                    f,
+                    "selection exceeds the maximum allowed transaction weight"
+                )
+            }
+        }
+    }
+}
+
+#[cfg(feature = "std")]
+impl std::error::Error for SelectError {}
+
+impl From<InsufficientFunds> for SelectError {
+    fn from(e: InsufficientFunds) -> Self {
+        Self::InsufficientFunds(e)
+    }
+}
+
 /// Error type that occurs when the target amount cannot be met.
 #[derive(Clone, Debug, Copy, PartialEq, Eq)]
 pub struct InsufficientFunds {

src/metrics.rs

@@ -5,8 +5,6 @@ mod lowest_fee;
 pub use lowest_fee::*;
 mod changeless;
 pub use changeless::*;
-mod max_weight;
-pub use max_weight::*;
 
 // Returns a drain if the current selection and every possible future selection would have a change
 // output (otherwise Drain::none()) by using the heurisitic that if it has change with the current

src/metrics/max_weight.rs

@@ -7,6 +7,9 @@ pub struct Target {
     pub fee: TargetFee,
     /// The aggregate properties of outputs you're trying to fund
     pub outputs: TargetOutputs,
+    /// Maximum allowed weight of the resulting transaction (WU).
+    /// `None` = unconstrained.
+    pub max_weight: Option<u64>,
 }
 
 impl Target {

src/target.rs

@@ -118,6 +118,7 @@ fn bnb_finds_an_exact_solution_in_n_iter() {
         },
         // we're trying to find an exact selection value so set fees to 0
         fee: TargetFee::ZERO,
+        max_weight: None,
     };
 
     let solutions = cs.bnb_solutions(MinExcessThenWeight { target });
@@ -152,6 +153,7 @@ fn bnb_finds_solution_if_possible_in_n_iter() {
             n_outputs: 1,
         },
         fee: TargetFee::default(),
+        max_weight: None,
     };
 
     let solutions = cs.bnb_solutions(MinExcessThenWeight { target });
@@ -195,10 +197,7 @@ proptest! {
         let candidates = wv.take(num_inputs).collect::<Vec<_>>();
         let cs = CoinSelector::new(&candidates);
 
-        let target = Target {
-            outputs: TargetOutputs { value_sum: target_value, weight_sum: 0, n_outputs: 1 },
-            fee: TargetFee::ZERO,
-        };
+        let target = Target {outputs:TargetOutputs{value_sum:target_value,weight_sum:0,n_outputs:1},fee:TargetFee::ZERO, max_weight: None };
 
         let solutions = cs.bnb_solutions(MinExcessThenWeight { target });
 
@@ -244,6 +243,7 @@ proptest! {
             outputs: TargetOutputs { value_sum: target_value, weight_sum: 0, n_outputs: 1 },
             // we're trying to find an exact selection value so set fees to 0
             fee: TargetFee::ZERO,
+            max_weight: None
         };
 
         let solutions = cs.bnb_solutions(MinExcessThenWeight { target });

tests/bnb.rs

@@ -67,7 +67,8 @@ proptest! {
                 rate: feerate,
                 replace,
                 ..TargetFee::ZERO
-            }
+            },
+            max_weight: None
         };
 
         let solutions = cs.bnb_solutions(metrics::Changeless {

tests/changeless.rs

@@ -221,6 +221,7 @@ impl StrategyParams {
                 weight_sum: self.target_weight as u64,
                 n_outputs: self.n_target_outputs,
             },
+            max_weight: None,
         }
     }
 

tests/common.rs

@@ -192,6 +192,7 @@ fn adding_another_input_to_remove_change() {
             weight_sum: 200 - TX_FIXED_FIELD_WEIGHT - 1,
             n_outputs: 1,
         },
+        max_weight: None,
     };
 
     let candidates = vec![
@@ -284,6 +285,7 @@ fn zero_fee_tx() {
             weight_sum: 200 - TX_FIXED_FIELD_WEIGHT - 1,
             n_outputs: 1,
         },
+        max_weight: None,
     };
 
     let candidates = vec![