bdk/src/wallet/coin_selection.rs

387 lines
13 KiB
Rust
Raw Normal View History

2020-08-31 11:26:36 +02:00
// Magical Bitcoin Library
// Written in 2020 by
// Alekos Filini <alekos.filini@gmail.com>
//
// Copyright (c) 2020 Magical Bitcoin
//
// Permission is hereby granted, free of charge, to any person obtaining a copy
// of this software and associated documentation files (the "Software"), to deal
// in the Software without restriction, including without limitation the rights
// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
// copies of the Software, and to permit persons to whom the Software is
// furnished to do so, subject to the following conditions:
//
// The above copyright notice and this permission notice shall be included in all
// copies or substantial portions of the Software.
//
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
// SOFTWARE.
2020-09-04 11:44:49 +02:00
//! Coin selection
//!
//! This module provides the trait [`CoinSelectionAlgorithm`] that can be implemented to
//! define custom coin selection algorithms.
//!
//! The coin selection algorithm is not globally part of a [`Wallet`](super::Wallet), instead it
//! is selected whenever a [`Wallet::create_tx`](super::Wallet::create_tx) call is made, through
//! the use of the [`TxBuilder`] structure, specifically with
//! [`TxBuilder::coin_selection`](super::tx_builder::TxBuilder::coin_selection) method.
//!
//! The [`DefaultCoinSelectionAlgorithm`] selects the default coin selection algorithm that
//! [`TxBuilder`] uses, if it's not explicitly overridden.
//!
//! [`TxBuilder`]: super::tx_builder::TxBuilder
//!
//! ## Example
//!
//! ```no_run
//! # use std::str::FromStr;
//! # use bitcoin::*;
2020-09-14 14:25:38 +02:00
//! # use bdk::wallet::coin_selection::*;
//! # use bdk::database::Database;
2020-09-14 14:25:38 +02:00
//! # use bdk::*;
2020-09-04 11:44:49 +02:00
//! #[derive(Debug)]
//! struct AlwaysSpendEverything;
//!
//! impl<D: Database> CoinSelectionAlgorithm<D> for AlwaysSpendEverything {
2020-09-04 11:44:49 +02:00
//! fn coin_select(
//! &self,
//! database: &D,
//! required_utxos: Vec<(UTXO, usize)>,
2020-10-26 14:12:46 -04:00
//! optional_utxos: Vec<(UTXO, usize)>,
2020-09-04 11:44:49 +02:00
//! fee_rate: FeeRate,
//! amount_needed: u64,
//! fee_amount: f32,
2020-09-14 14:25:38 +02:00
//! ) -> Result<CoinSelectionResult, bdk::Error> {
//! let mut selected_amount = 0;
//! let mut additional_weight = 0;
//! let all_utxos_selected = required_utxos
2020-10-26 14:12:46 -04:00
//! .into_iter().chain(optional_utxos)
//! .scan((&mut selected_amount, &mut additional_weight), |(selected_amount, additional_weight), (utxo, weight)| {
//! let txin = TxIn {
//! previous_output: utxo.outpoint,
//! ..Default::default()
//! };
//!
//! **selected_amount += utxo.txout.value;
//! **additional_weight += TXIN_BASE_WEIGHT + weight;
//!
//! Some((
//! txin,
2020-09-04 11:44:49 +02:00
//! utxo.txout.script_pubkey,
//! ))
2020-09-04 11:44:49 +02:00
//! })
//! .collect::<Vec<_>>();
//! let additional_fees = additional_weight as f32 * fee_rate.as_sat_vb() / 4.0;
//!
//! if (fee_amount + additional_fees).ceil() as u64 + amount_needed > selected_amount {
2020-09-14 14:25:38 +02:00
//! return Err(bdk::Error::InsufficientFunds);
2020-09-04 11:44:49 +02:00
//! }
//!
//! Ok(CoinSelectionResult {
//! txin: all_utxos_selected,
//! selected_amount,
//! fee_amount: fee_amount + additional_fees,
//! })
//! }
//! }
//!
2020-09-14 14:25:38 +02:00
//! # let wallet: OfflineWallet<_> = Wallet::new_offline("", None, Network::Testnet, bdk::database::MemoryDatabase::default())?;
2020-09-04 11:44:49 +02:00
//! // create wallet, sync, ...
//!
//! let to_address = Address::from_str("2N4eQYCbKUHCCTUjBJeHcJp9ok6J2GZsTDt").unwrap();
//! let (psbt, details) = wallet.create_tx(
//! TxBuilder::with_recipients(vec![(to_address.script_pubkey(), 50_000)])
2020-09-04 11:44:49 +02:00
//! .coin_selection(AlwaysSpendEverything),
//! )?;
//!
//! // inspect, sign, broadcast, ...
//!
2020-09-14 14:25:38 +02:00
//! # Ok::<(), bdk::Error>(())
2020-09-04 11:44:49 +02:00
//! ```
use bitcoin::{Script, TxIn};
use crate::database::Database;
use crate::error::Error;
2020-08-31 10:49:44 +02:00
use crate::types::{FeeRate, UTXO};
2020-09-04 11:44:49 +02:00
/// Default coin selection algorithm used by [`TxBuilder`](super::tx_builder::TxBuilder) if not
/// overridden
pub type DefaultCoinSelectionAlgorithm = LargestFirstCoinSelection;
2020-09-04 11:44:49 +02:00
/// Result of a successful coin selection
#[derive(Debug)]
pub struct CoinSelectionResult {
2020-09-04 11:44:49 +02:00
/// List of inputs to use, with the respective previous script_pubkey
pub txin: Vec<(TxIn, Script)>,
2020-09-04 11:44:49 +02:00
/// Sum of the selected inputs' value
2020-08-31 10:49:44 +02:00
pub selected_amount: u64,
2020-09-04 11:44:49 +02:00
/// Total fee amount in satoshi
pub fee_amount: f32,
}
2020-09-04 11:44:49 +02:00
/// Trait for generalized coin selection algorithms
///
/// This trait can be implemented to make the [`Wallet`](super::Wallet) use a customized coin
/// selection algorithm when it creates transactions.
///
/// For an example see [this module](crate::wallet::coin_selection)'s documentation.
pub trait CoinSelectionAlgorithm<D: Database>: std::fmt::Debug {
2020-09-04 11:44:49 +02:00
/// Perform the coin selection
///
/// - `database`: a reference to the wallet's database that can be used to lookup additional
/// details for a specific UTXO
/// - `required_utxos`: the utxos that must be spent regardless of `amount_needed` with their
/// weight cost
2020-10-26 14:12:46 -04:00
/// - `optional_utxos`: the remaining available utxos to satisfy `amount_needed` with their
/// weight cost
2020-09-04 11:44:49 +02:00
/// - `fee_rate`: fee rate to use
/// - `amount_needed`: the amount in satoshi to select
/// - `fee_amount`: the amount of fees in satoshi already accumulated from adding outputs and
/// the transaction's header
fn coin_select(
&self,
database: &D,
required_utxos: Vec<(UTXO, usize)>,
2020-10-26 14:12:46 -04:00
optional_utxos: Vec<(UTXO, usize)>,
2020-08-31 10:49:44 +02:00
fee_rate: FeeRate,
amount_needed: u64,
fee_amount: f32,
) -> Result<CoinSelectionResult, Error>;
}
2020-09-04 11:44:49 +02:00
/// Simple and dumb coin selection
///
/// This coin selection algorithm sorts the available UTXOs by value and then picks them starting
/// from the largest ones until the required amount is reached.
#[derive(Debug, Default)]
pub struct LargestFirstCoinSelection;
impl<D: Database> CoinSelectionAlgorithm<D> for LargestFirstCoinSelection {
fn coin_select(
&self,
_database: &D,
required_utxos: Vec<(UTXO, usize)>,
2020-10-26 14:12:46 -04:00
mut optional_utxos: Vec<(UTXO, usize)>,
2020-08-31 10:49:44 +02:00
fee_rate: FeeRate,
amount_needed: u64,
mut fee_amount: f32,
) -> Result<CoinSelectionResult, Error> {
2020-08-31 10:49:44 +02:00
let calc_fee_bytes = |wu| (wu as f32) * fee_rate.as_sat_vb() / 4.0;
log::debug!(
"amount_needed = `{}`, fee_amount = `{}`, fee_rate = `{:?}`",
amount_needed,
fee_amount,
fee_rate
);
2020-10-26 14:12:46 -04:00
// We put the "required UTXOs" first and make sure the optional UTXOs are sorted,
// initially smallest to largest, before being reversed with `.rev()`.
let utxos = {
2020-10-26 14:12:46 -04:00
optional_utxos.sort_unstable_by_key(|(utxo, _)| utxo.txout.value);
required_utxos
.into_iter()
.map(|utxo| (true, utxo))
2020-10-26 14:12:46 -04:00
.chain(optional_utxos.into_iter().rev().map(|utxo| (false, utxo)))
};
// Keep including inputs until we've got enough.
// Store the total input value in selected_amount and the total fee being paid in fee_amount
let mut selected_amount = 0;
let txin = utxos
.scan(
(&mut selected_amount, &mut fee_amount),
|(selected_amount, fee_amount), (must_use, (utxo, weight))| {
if must_use || **selected_amount < amount_needed + (fee_amount.ceil() as u64) {
let new_in = TxIn {
previous_output: utxo.outpoint,
script_sig: Script::default(),
sequence: 0, // Let the caller choose the right nSequence
witness: vec![],
};
**fee_amount += calc_fee_bytes(TXIN_BASE_WEIGHT + weight);
**selected_amount += utxo.txout.value;
log::debug!(
"Selected {}, updated fee_amount = `{}`",
new_in.previous_output,
fee_amount
);
Some((new_in, utxo.txout.script_pubkey))
} else {
None
}
},
)
.collect::<Vec<_>>();
if selected_amount < amount_needed + (fee_amount.ceil() as u64) {
return Err(Error::InsufficientFunds);
}
Ok(CoinSelectionResult {
txin,
fee_amount,
2020-08-31 10:49:44 +02:00
selected_amount,
})
}
}
// Base weight of a Txin, not counting the weight needed for satisfaying it.
// prev_txid (32 bytes) + prev_vout (4 bytes) + sequence (4 bytes) + script_len (1 bytes)
pub const TXIN_BASE_WEIGHT: usize = (32 + 4 + 4 + 1) * 4;
#[cfg(test)]
mod test {
use std::str::FromStr;
use bitcoin::{OutPoint, Script, TxOut};
use super::*;
use crate::database::MemoryDatabase;
use crate::types::*;
const P2WPKH_WITNESS_SIZE: usize = 73 + 33 + 2;
fn get_test_utxos() -> Vec<(UTXO, usize)> {
vec![
(
UTXO {
outpoint: OutPoint::from_str(
"ebd9813ecebc57ff8f30797de7c205e3c7498ca950ea4341ee51a685ff2fa30a:0",
)
.unwrap(),
txout: TxOut {
value: 100_000,
script_pubkey: Script::new(),
},
is_internal: false,
},
P2WPKH_WITNESS_SIZE,
),
(
UTXO {
outpoint: OutPoint::from_str(
"65d92ddff6b6dc72c89624a6491997714b90f6004f928d875bc0fd53f264fa85:0",
)
.unwrap(),
txout: TxOut {
value: 200_000,
script_pubkey: Script::new(),
},
is_internal: true,
},
P2WPKH_WITNESS_SIZE,
),
]
}
#[test]
fn test_largest_first_coin_selection_success() {
let utxos = get_test_utxos();
let database = MemoryDatabase::default();
let result = LargestFirstCoinSelection::default()
2020-08-31 10:49:44 +02:00
.coin_select(
&database,
2020-08-31 10:49:44 +02:00
utxos,
vec![],
2020-08-31 10:49:44 +02:00
FeeRate::from_sat_per_vb(1.0),
250_000,
50.0,
)
.unwrap();
assert_eq!(result.txin.len(), 2);
2020-08-31 10:49:44 +02:00
assert_eq!(result.selected_amount, 300_000);
assert_eq!(result.fee_amount, 186.0);
}
#[test]
fn test_largest_first_coin_selection_use_all() {
let utxos = get_test_utxos();
let database = MemoryDatabase::default();
let result = LargestFirstCoinSelection::default()
2020-08-31 10:49:44 +02:00
.coin_select(
&database,
2020-08-31 10:49:44 +02:00
utxos,
vec![],
2020-08-31 10:49:44 +02:00
FeeRate::from_sat_per_vb(1.0),
20_000,
50.0,
)
.unwrap();
assert_eq!(result.txin.len(), 2);
2020-08-31 10:49:44 +02:00
assert_eq!(result.selected_amount, 300_000);
assert_eq!(result.fee_amount, 186.0);
}
#[test]
fn test_largest_first_coin_selection_use_only_necessary() {
let utxos = get_test_utxos();
let database = MemoryDatabase::default();
let result = LargestFirstCoinSelection::default()
2020-08-31 10:49:44 +02:00
.coin_select(
&database,
vec![],
2020-08-31 10:49:44 +02:00
utxos,
FeeRate::from_sat_per_vb(1.0),
20_000,
50.0,
)
.unwrap();
assert_eq!(result.txin.len(), 1);
2020-08-31 10:49:44 +02:00
assert_eq!(result.selected_amount, 200_000);
assert_eq!(result.fee_amount, 118.0);
}
#[test]
#[should_panic(expected = "InsufficientFunds")]
fn test_largest_first_coin_selection_insufficient_funds() {
let utxos = get_test_utxos();
let database = MemoryDatabase::default();
LargestFirstCoinSelection::default()
2020-08-31 10:49:44 +02:00
.coin_select(
&database,
vec![],
2020-08-31 10:49:44 +02:00
utxos,
FeeRate::from_sat_per_vb(1.0),
500_000,
50.0,
)
.unwrap();
}
#[test]
#[should_panic(expected = "InsufficientFunds")]
fn test_largest_first_coin_selection_insufficient_funds_high_fees() {
let utxos = get_test_utxos();
let database = MemoryDatabase::default();
LargestFirstCoinSelection::default()
2020-08-31 10:49:44 +02:00
.coin_select(
&database,
vec![],
2020-08-31 10:49:44 +02:00
utxos,
FeeRate::from_sat_per_vb(1000.0),
250_000,
50.0,
)
.unwrap();
}
}