rust_coinselect/
types.rs

1/// Represents an input candidate for Coinselection, either as a single UTXO or a group of UTXOs.
2///
3/// A [`OutputGroup`] can be a single UTXO or a group that should be spent together.
4/// Grouping UTXOs belonging to a single address is privacy preserving than grouping UTXOs belonging to different addresses.
5/// In the UTXO model the output of a transaction is used as the input for the new transaction and hence the name [`OutputGroup`]
6/// The library user must craft this structure correctly, as incorrect representation can lead to incorrect selection results.
7#[derive(Debug, Clone)]
8pub struct OutputGroup {
9    /// Total value of the UTXO(s) that this `WeightedValue` represents.
10    pub value: u64,
11    /// Total weight of including these UTXO(s) in the transaction.
12    ///
13    /// The `txin` fields: `prevout`, `nSequence`, `scriptSigLen`, `scriptSig`, `scriptWitnessLen`,
14    /// and `scriptWitness` should all be included.
15    pub weight: u64,
16    /// The total number of inputs
17    pub input_count: usize,
18    /// Specifies the relative creation sequence for this group, used only for FIFO selection.
19    ///
20    /// Set to `None` if FIFO selection is not required. Sequence numbers are arbitrary indices that denote the relative age of a UTXO group among a set of groups.
21    /// To denote the oldest UTXO group, assign it a sequence number of `Some(0)`.
22    pub creation_sequence: Option<u32>,
23}
24
25/// Options required to compute fees and waste metric.
26#[derive(Debug, Clone)]
27pub struct CoinSelectionOpt {
28    /// The value we need to select.
29    pub target_value: u64,
30
31    /// The target feerate we should try and achieve in sats per weight unit.
32    pub target_feerate: f32,
33
34    /// The long term fee-rate is an estimate of the future transaction fee rate that a wallet might need to pay to spend its UTXOs.
35    /// If the current fee rates are less than the long term fee rate, it is optimal to consolidate UTXOs to make the spend.
36    /// It affects how the [`WasteMetric`] is computed.
37    pub long_term_feerate: Option<f32>,
38
39    /// Lowest possible transaction fee required to get a transaction included in a block
40    pub min_absolute_fee: u64,
41
42    /// Weights of data in transaction other than the list of inputs that would be selected.
43    ///
44    /// This includes weight of the header, total weight out outputs, weight of fields used
45    /// to represent number number of inputs and number outputs, witness etc.,
46    pub base_weight: u64,
47
48    /// Additional weigh added to a transaction when a change output is created.
49    /// Used in weight metric computation.
50    pub change_weight: u64,
51
52    /// Total cost associated with creating and later spending a change output in a transaction.
53    /// This includes the transaction fees for both the current transaction (where the change is created) and the future transaction (where the change is spent)
54    pub change_cost: u64,
55
56    /// Estimate of average weight of an input.
57    pub avg_input_weight: u64,
58
59    /// Estimate of average weight of an output.
60    pub avg_output_weight: u64,
61
62    /// The smallest amount of change that is considered acceptable in a transaction given the dust limit
63    pub min_change_value: u64,
64
65    /// Strategy to use the excess value other than fee and target
66    pub excess_strategy: ExcessStrategy,
67}
68
69/// Strategy to decide what to do with the excess amount.
70#[derive(Clone, Debug, PartialEq, Eq)]
71pub enum ExcessStrategy {
72    /// Adds the excess amount to the transaction fee. This increases the fee rate
73    /// and may lead to faster confirmation, but wastes the excess amount.
74    ToFee,
75
76    /// Adds the excess amount to the recipient's output. This avoids creating a change
77    /// output and reduces transaction size, but may reveal information about the
78    /// wallet's available UTXOs.
79    ToRecipient,
80
81    /// Creates a change output with the excess amount. This preserves privacy and
82    /// allows reuse of the excess amount in future transactions, but increases
83    /// transaction size and creates dust UTXOs if the amount is too small.
84    ToChange,
85}
86
87/// Error Describing failure of a selection attempt, on any subset of inputs.
88#[derive(Debug, Eq, PartialEq, Ord, PartialOrd, Clone, Copy)]
89pub enum SelectionError {
90    InsufficientFunds,
91    NoSolutionFound,
92    NonPositiveTarget,
93    NonPositiveFeeRate,
94    AbnormallyHighFeeRate,
95}
96
97/// Measures the efficiency of input selection in satoshis, helping evaluate algorithms based on current and long-term fee rates
98///
99/// WasteMetric strikes a balance between minimizing current transaction fees and overall fees during the wallet's lifetime.
100/// In high fee rate environments, selecting fewer inputs reduces transaction fees.
101/// In low fee rate environments, selecting more inputs reduces overall fees.
102/// It compares various selection algorithms to find the most optimized solution, represented by the lowest [WasteMetric] value.
103#[derive(Debug)]
104pub struct WasteMetric(pub f32);
105
106/// The result of selection algorithm.
107#[derive(Debug)]
108pub struct SelectionOutput {
109    /// The selected input indices, refers to the indices of the inputs Slice Reference.
110    pub selected_inputs: Vec<usize>,
111    /// The waste amount, for the above inputs.
112    pub waste: WasteMetric,
113}
114
115/// EffectiveValue type alias
116pub type EffectiveValue = u64;
117
118/// Weight type alias
119pub type Weight = u64;
rust_coinselect/types.rs

rust_coinselect/
types.rs
