rust-coinselect 0.1.6

A blockchain-agnostic coin selection library built in Rust.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119

/// Represents an input candidate for Coinselection, either as a single UTXO or a group of UTXOs.
///
/// A [`OutputGroup`] can be a single UTXO or a group that should be spent together.
/// Grouping UTXOs belonging to a single address is privacy preserving than grouping UTXOs belonging to different addresses.
/// In the UTXO model the output of a transaction is used as the input for the new transaction and hence the name [`OutputGroup`]
/// The library user must craft this structure correctly, as incorrect representation can lead to incorrect selection results.
#[derive(Debug, Clone)]
pub struct OutputGroup {
    /// Total value of the UTXO(s) that this `WeightedValue` represents.
    pub value: u64,
    /// Total weight of including these UTXO(s) in the transaction.
    ///
    /// The `txin` fields: `prevout`, `nSequence`, `scriptSigLen`, `scriptSig`, `scriptWitnessLen`,
    /// and `scriptWitness` should all be included.
    pub weight: u64,
    /// The total number of inputs
    pub input_count: usize,
    /// Specifies the relative creation sequence for this group, used only for FIFO selection.
    ///
    /// 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.
    /// To denote the oldest UTXO group, assign it a sequence number of `Some(0)`.
    pub creation_sequence: Option<u32>,
}

/// Options required to compute fees and waste metric.
#[derive(Debug, Clone)]
pub struct CoinSelectionOpt {
    /// The value we need to select.
    pub target_value: u64,

    /// The target feerate we should try and achieve in sats per weight unit.
    pub target_feerate: f32,

    /// 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.
    /// If the current fee rates are less than the long term fee rate, it is optimal to consolidate UTXOs to make the spend.
    /// It affects how the [`WasteMetric`] is computed.
    pub long_term_feerate: Option<f32>,

    /// Lowest possible transaction fee required to get a transaction included in a block
    pub min_absolute_fee: u64,

    /// Weights of data in transaction other than the list of inputs that would be selected.
    ///
    /// This includes weight of the header, total weight out outputs, weight of fields used
    /// to represent number number of inputs and number outputs, witness etc.,
    pub base_weight: u64,

    /// Additional weigh added to a transaction when a change output is created.
    /// Used in weight metric computation.
    pub change_weight: u64,

    /// Total cost associated with creating and later spending a change output in a transaction.
    /// This includes the transaction fees for both the current transaction (where the change is created) and the future transaction (where the change is spent)
    pub change_cost: u64,

    /// Estimate of average weight of an input.
    pub avg_input_weight: u64,

    /// Estimate of average weight of an output.
    pub avg_output_weight: u64,

    /// The smallest amount of change that is considered acceptable in a transaction given the dust limit
    pub min_change_value: u64,

    /// Strategy to use the excess value other than fee and target
    pub excess_strategy: ExcessStrategy,
}

/// Strategy to decide what to do with the excess amount.
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum ExcessStrategy {
    /// Adds the excess amount to the transaction fee. This increases the fee rate
    /// and may lead to faster confirmation, but wastes the excess amount.
    ToFee,

    /// Adds the excess amount to the recipient's output. This avoids creating a change
    /// output and reduces transaction size, but may reveal information about the
    /// wallet's available UTXOs.
    ToRecipient,

    /// Creates a change output with the excess amount. This preserves privacy and
    /// allows reuse of the excess amount in future transactions, but increases
    /// transaction size and creates dust UTXOs if the amount is too small.
    ToChange,
}

/// Error Describing failure of a selection attempt, on any subset of inputs.
#[derive(Debug, Eq, PartialEq, Ord, PartialOrd, Clone, Copy)]
pub enum SelectionError {
    InsufficientFunds,
    NoSolutionFound,
    NonPositiveTarget,
    NonPositiveFeeRate,
    AbnormallyHighFeeRate,
}

/// Measures the efficiency of input selection in satoshis, helping evaluate algorithms based on current and long-term fee rates
///
/// WasteMetric strikes a balance between minimizing current transaction fees and overall fees during the wallet's lifetime.
/// In high fee rate environments, selecting fewer inputs reduces transaction fees.
/// In low fee rate environments, selecting more inputs reduces overall fees.
/// It compares various selection algorithms to find the most optimized solution, represented by the lowest [WasteMetric] value.
#[derive(Debug)]
pub struct WasteMetric(pub f32);

/// The result of selection algorithm.
#[derive(Debug)]
pub struct SelectionOutput {
    /// The selected input indices, refers to the indices of the inputs Slice Reference.
    pub selected_inputs: Vec<usize>,
    /// The waste amount, for the above inputs.
    pub waste: WasteMetric,
}

/// EffectiveValue type alias
pub type EffectiveValue = u64;

/// Weight type alias
pub type Weight = u64;