Add consolidation input selection strategy

Add a new input selection strategy that optimizes for consolidation
when fees are low. This strategy allows receivers to combine multiple
UTXOs in a payjoin, subject to configurable constraints:

- Maximum fee rate threshold for consolidation
- Maximum number of inputs to add
- Optional target value to reach
- Minimum input value (dust limit)

The strategy sorts candidate inputs by value and adds them until
reaching either the max inputs limit or target value, but only when
the current fee rate is below the specified threshold.

Author: IgnacioPorte

payjoin/src/receive/error.rs

@@ -313,14 +313,16 @@ impl std::error::Error for OutputSubstitutionError {
 #[derive(Debug)]
 pub struct SelectionError(InternalSelectionError);
 
-#[derive(Debug)]
+#[derive(Debug)] 
 pub(crate) enum InternalSelectionError {
     /// No candidates available for selection
     Empty,
     /// Current privacy selection implementation only supports 2-output transactions
     UnsupportedOutputLength,
     /// No selection candidates improve privacy
     NotFound,
+    /// Fee rate too high for consolidation
+    FeeRateTooHighForConsolidation,
 }
 
 impl fmt::Display for SelectionError {
@@ -331,8 +333,12 @@ impl fmt::Display for SelectionError {
                 f,
                 "Current privacy selection implementation only supports 2-output transactions"
             ),
-            InternalSelectionError::NotFound =>
-                write!(f, "No selection candidates improve privacy"),
+            InternalSelectionError::NotFound => {
+                write!(f, "No selection candidates improve privacy")
+            }
+            InternalSelectionError::FeeRateTooHighForConsolidation => {
+                write!(f, "Fee rate too high for consolidation strategy")
+            }
         }
     }
 }
@@ -345,6 +351,7 @@ impl error::Error for SelectionError {
             Empty => None,
             UnsupportedOutputLength => None,
             NotFound => None,
+            FeeRateTooHighForConsolidation => None,
         }
     }
 }

payjoin/src/receive/v1/mod.rs

@@ -553,6 +553,64 @@ impl WantsInputs {
             change_vout: self.change_vout,
         }
     }
+
+    /// Select inputs optimizing for consolidation when fees are low
+    pub(crate) fn try_consolidate(
+        &self,
+        candidate_inputs: impl IntoIterator<Item = InputPair>,
+        dust_limit: Option<Amount>,
+        max_inputs: Option<usize>,
+        target_value: Option<Amount>,
+        fee_rate_threshold: Option<FeeRate>,
+    ) -> Result<Vec<InputPair>, SelectionError> {
+        // Check current fee rate
+        let current_fee = self.payjoin_psbt.fee().expect("fee exists");
+        let current_fee_rate = FeeRate::from_sat_per_vb(
+            current_fee.to_sat() / self.payjoin_psbt.unsigned_tx.weight().to_vbytes_ceil(),
+        );
+
+        // If fee rate is above threshold, return error
+        if let (Some(current), Some(threshold)) = (current_fee_rate, fee_rate_threshold) {
+            if current > threshold {
+                return Err(InternalSelectionError::FeeRateTooHighForConsolidation.into());
+            }
+        }
+
+        // Filter and collect valid inputs above dust limit
+        let dust = dust_limit.unwrap_or(DEFAULT_DUST_LIMIT);
+        let mut valid_inputs: Vec<InputPair> = candidate_inputs
+            .into_iter()
+            .filter(|input| input.previous_txout().value >= dust)
+            .collect();
+
+        if valid_inputs.is_empty() {
+            return Err(InternalSelectionError::Empty.into());
+        }
+
+        // Sort inputs by value ascending
+        valid_inputs.sort_by_key(|input| input.previous_txout().value);
+        
+        // Select inputs until reaching max_inputs or target_value
+        let max = max_inputs.unwrap_or(DEFAULT_MAX_INPUTS);
+        let mut selected = Vec::new();
+        let mut total = Amount::from_sat(0);
+
+        for input in valid_inputs {
+            if selected.len() >= max {
+                break;
+            }                
+            total += input.previous_txout().value;
+            selected.push(input);
+
+            if let Some(target) = target_value {
+                if total >= target {
+                    break;
+                }
+            }
+        }
+
+        Ok(selected)
+    }
 }
 
 /// A checked proposal that the receiver may sign and finalize to make a proposal PSBT that the
@@ -783,6 +841,9 @@ impl PayjoinProposal {
     pub fn psbt(&self) -> &Psbt { &self.payjoin_psbt }
 }
 
+const DEFAULT_DUST_LIMIT: Amount = Amount::from_sat(546);
+const DEFAULT_MAX_INPUTS: usize = 3;
+
 #[cfg(test)]
 pub(crate) mod test {
     use std::str::FromStr;

payjoin/src/receive/v2/mod.rs

@@ -4,7 +4,7 @@ use std::time::{Duration, SystemTime};
 
 use bitcoin::hashes::{sha256, Hash};
 use bitcoin::psbt::Psbt;
-use bitcoin::{Address, FeeRate, OutPoint, Script, TxOut};
+use bitcoin::{Address, Amount, FeeRate, OutPoint, Script, TxOut};
 pub(crate) use error::InternalSessionError;
 pub use error::SessionError;
 use serde::de::Deserializer;
@@ -28,6 +28,12 @@ const SUPPORTED_VERSIONS: &[usize] = &[1, 2];
 
 static TWENTY_FOUR_HOURS_DEFAULT_EXPIRY: Duration = Duration::from_secs(60 * 60 * 24);
 
+#[derive(Debug, Clone)]
+pub enum SelectionStrategy {
+    PreservePrivacy,
+    Consolidate,
+}
+
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 struct SessionContext {
     #[serde(deserialize_with = "deserialize_address_assume_checked")]
@@ -409,6 +415,29 @@ pub struct WantsInputs {
 }
 
 impl WantsInputs {
+    /// Select receiver inputs using the specified selection strategy
+    pub fn select_inputs(
+        &self,
+        candidate_inputs: impl IntoIterator<Item = InputPair>,
+        strategy: SelectionStrategy,
+        dust_limit: Option<Amount>,
+        max_inputs: Option<usize>,
+        target_value: Option<Amount>,
+        max_consolidation_fee_rate: Option<FeeRate>,
+    ) -> Result<Vec<InputPair>, SelectionError> {
+        match strategy {
+            SelectionStrategy::PreservePrivacy => {
+                self.try_preserving_privacy(candidate_inputs).map(|input| vec![input])
+            }
+            SelectionStrategy::Consolidate => self.try_consolidate(
+                    candidate_inputs, 
+                    dust_limit,
+                    max_inputs,
+                    target_value,
+                max_consolidation_fee_rate,
+            ),
+        }
+    }
     /// Select receiver input such that the payjoin avoids surveillance.
     /// Return the input chosen that has been applied to the Proposal.
     ///
@@ -427,6 +456,23 @@ impl WantsInputs {
         self.v1.try_preserving_privacy(candidate_inputs)
     }
 
+    pub fn try_consolidate(
+        &self,
+        candidate_inputs: impl IntoIterator<Item = InputPair>,
+        dust_limit: Option<Amount>,
+        max_inputs: Option<usize>,
+        target_value: Option<Amount>,
+        max_fee_rate: Option<FeeRate>,
+    ) -> Result<Vec<InputPair>, SelectionError> {
+        self.v1.try_consolidate(
+            candidate_inputs,
+            dust_limit,
+            max_inputs,
+            target_value,
+            max_fee_rate,
+        )
+    }
+
     /// Add the provided list of inputs to the transaction.
     /// Any excess input amount is added to the change_vout output indicated previously.
     pub fn contribute_inputs(