Struct InputSelection 

pub struct InputSelection<F = ()> {
    pub max_inputs: Option<usize>,
    pub exclude: HashSet<VtxoId>,
    /* private fields */
}

Parameters controlling which VTXOs may be selected as inputs for a payment.

Builder pattern is used. By default there is no limit on the number of inputs and no VTXOs are excluded.

use bitcoin::Amount;
use bark::vtxo::selection::InputSelection;

let selected = InputSelection::new()
    .max_inputs(10)       // use at most 10 VTXOs
    .exclude(poisoned)    // never select this one
    .select(vtxos, Amount::from_sat(100_000))?;

Adding a fee scheme with InputSelection::fee_scheme makes InputSelection::select also cover the fee charged on top of the amount and return it alongside the VTXOs.

Fields

max_inputs: Option<usize>

Cap on the total number of inputs that may be selected.

exclude: HashSet<VtxoId>

Never select these vtxos.

Implementations

impl<F> InputSelection<F>

pub fn max_inputs(self, max_inputs: usize) -> Self

Cap the total number of inputs that may be selected.

pub fn exclude(self, exclude: VtxoId) -> Self

Exclude the given vtxo from selection.

pub fn exclude_many(self, exclude: impl IntoIterator<Item = VtxoId>) -> Self

Exclude the given vtxos from selection.

impl InputSelection

pub fn new() -> InputSelection

Create a new InputSelection with no input limit, no exclusions, and no fee scheme.

pub fn fee_scheme<F>( self, tip: BlockHeight, calc_fee: F, ) -> InputSelection<FeeScheme<F>>

where F: for<'a> Fn(Amount, SelectedFeeInfos<'a>) -> Result<Amount>,

Make the selection also cover the fee charged on top of the amount, where the fee itself depends on the selected VTXOs. E.g., a lightning payment, a send-onchain payment.

calc_fee receives the target amount and the VtxoFeeInfo of each selected VTXO (derived from the tip block height). InputSelection::select then returns the calculated fee alongside the selected VTXOs.

pub fn select( &self, vtxos: Vec<WalletVtxo>, amount: Amount, ) -> Result<Vec<WalletVtxo>>

Select VTXOs from the given candidates to cover the provided amount.

Candidates are selected soonest-expiring-first; see [InputScanner::cover_amount] for how the input limit affects this. The selection is returned soonest-expiring-first.

Returns an error if the amount cannot be reached.

impl<F> InputSelection<FeeScheme<F>>

where F: for<'a> Fn(Amount, SelectedFeeInfos<'a>) -> Result<Amount>,

pub fn select( &self, vtxos: Vec<WalletVtxo>, amount: Amount, ) -> Result<(Vec<WalletVtxo>, Amount)>

Select VTXOs from the given candidates to cover the provided amount plus the fee computed by the configured InputSelection::fee_scheme.

Candidates are selected soonest-expiring-first; see [InputScanner::cover_amount] for how the input limit affects this. The selection is returned soonest-expiring-first.

Returns a collection of VTXOs capable of covering the desired amount as well as the calculated fee.

Trait Implementations

impl<F: Clone> Clone for InputSelection<F>

fn clone(&self) -> InputSelection<F>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<F: Debug> Debug for InputSelection<F>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<F: Default> Default for InputSelection<F>

fn default() -> InputSelection<F>

Returns the “default value” for a type.