Struct RefreshStrategy

pub struct RefreshStrategy<'a> { /* private fields */ }

Strategy to select VTXOs that need proactive refreshing.

Refreshing is recommended when a VTXO is nearing its expiry, has reached a soft/hard out-of-round depth threshold, or is uneconomical to exit onchain at the current fee rate.

Variants:

• RefreshStrategy::must_refresh: strict selection intended for mandatory refresh actions (e.g., at or beyond maximum depth or near-hard expiry threshold).
• RefreshStrategy::should_refresh: softer selection for opportunistic refreshes (e.g., approaching soft thresholds or uneconomical unilateral exit).

This type implements FilterVtxos, so it can be passed directly to Wallet::vtxos_with or [Wallet::inround_vtxos_with].

Implementations

impl<'a> RefreshStrategy<'a>

pub fn must_refresh( wallet: &'a Wallet, tip: BlockHeight, fee_rate: FeeRate, ) -> Self

Builds a strategy that matches VTXOs that must be refreshed immediately.

A WalletVtxo is selected when at least one of the following strict conditions holds:

• It reached or exceeded the maximum allowed out-of-round (OOR) depth (if configured by the Ark server info in the wallet).
• It is within vtxo_refresh_expiry_threshold blocks of expiry at tip.

Parameters:

• wallet: Wallet context used to read configuration and Ark parameters.
• tip: Current chain tip height used to evaluate expiry proximity.
• fee_rate: FeeRate to use for any economic checks (kept for parity with the “should” strategy; not all checks require it in the strict mode).

Returns:

• A RefreshStrategy implementing FilterVtxos. Pass it to Wallet::vtxos_with or call FilterVtxos::filter_vtxos directly.

Examples

use bark::vtxo::selection::{FilterVtxos, RefreshStrategy};
use bitcoin::FeeRate;
use bitcoin_ext::BlockHeight;

let tip: BlockHeight = 200_000;
let fr = FeeRate::from_sat_per_vb(5).unwrap();
let must = RefreshStrategy::must_refresh(wallet, tip, fr);
must.filter_vtxos(&mut vtxos)?;

pub fn should_refresh( wallet: &'a Wallet, tip: BlockHeight, fee_rate: FeeRate, ) -> Self

Builds a strategy that matches VTXOs that should be refreshed soon (opportunistic).

A WalletVtxo is selected when at least one of the following softer conditions holds:

• It is at or beyond a soft OOR depth threshold (typically one less than the maximum, if configured by the Ark server info in the wallet).
• It is within a softer expiry window (e.g., vtxo_refresh_expiry_threshold + 28 blocks) relative to tip.
• It is uneconomical to unilaterally exit at the provided fee_rate (e.g., its amount is lower than the estimated exit cost).

Parameters:

• wallet: Wallet context used to read configuration and Ark parameters.
• tip: Current chain tip height used to evaluate expiry proximity.
• fee_rate: FeeRate used for economic feasibility checks.

Returns:

• A RefreshStrategy implementing FilterVtxos. Pass it to Wallet::vtxos_with or call FilterVtxos::filter_vtxos directly.

Examples

use bark::vtxo::selection::{FilterVtxos, RefreshStrategy};
use bitcoin::FeeRate;
use bitcoin_ext::BlockHeight;

let tip: BlockHeight = 200_000;
let fr = FeeRate::from_sat_per_vb(8).unwrap();
let should = RefreshStrategy::should_refresh(wallet, tip, fr);
should.filter_vtxos(&mut vtxos)?;

Trait Implementations

impl FilterVtxos for RefreshStrategy<'_>

fn matches(&self, vtxo: &WalletVtxo) -> Result<bool>

Check whether the VTXO mathes this filter

fn filter_vtxos<V: Borrow<WalletVtxo>>(&self, vtxos: &mut Vec<V>) -> Result<()>

Eliminate from the vector all non-matching VTXOs