bark::vtxo

Module selection

Source
Expand description

VTXO selection and filtering utilities.

This module provides reusable filters to select subsets of wallet VTXOs for various workflows. The primary interface to facilitate this is the FilterVtxos trait, which is accepted by methods such as Wallet::vtxos_with and [Wallet::inround_vtxos_with] to filter VTXOs based on custom logic or ready-made builders.

Provided filters:

  • VtxoFilter: A builder to match VTXOs by criteria such as expiry height, counterparty risk, and explicit include/exclude lists.
  • RefreshStrategy: Selects VTXOs that must or should be refreshed preemptively based on depth, expiry proximity, and economic viability.

Usage examples

Custom predicate via FilterVtxos:

use anyhow::Result;
use bitcoin::Amount;
use bark::WalletVtxo;
use bark::vtxo::selection::FilterVtxos;

fn is_large(v: &WalletVtxo) -> Result<bool> {
    Ok(v.amount() >= Amount::from_sat(50_000))
}

FilterVtxos::filter_vtxos(&is_large, &mut vtxos)?;

Builder style with VtxoFilter:

use bitcoin_ext::BlockHeight;
use bark::vtxo::selection::{FilterVtxos, VtxoFilter};

let tip: BlockHeight = 1_000;
let filter = VtxoFilter::new(wallet)
    .expires_before(tip + 144) // expiring within ~1 day
    .counterparty();           // and/or with counterparty risk
filter.filter_vtxos(&mut vtxos)?;

Notes on semantics

  • Include/exclude precedence: an ID in include always matches; an ID in exclude never matches. These take precedence over other criteria.
  • Criteria are OR’ed together: a WalletVtxo matches if any enabled criterion matches (after applying include/exclude).
  • “Counterparty risk” is wallet-defined and indicates a WalletVtxo may be invalidated by another party; see VtxoFilter::counterparty.

See also:

The intent is to allow users to filter VTXOs based on different parameters.

Structs§

RefreshStrategy
Strategy to select VTXOs that need proactive refreshing.
VtxoFilter
Filter vtxos based on criteria.

Traits§

FilterVtxos
Trait needed to be implemented to filter wallet VTXOs.