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 near expiry threshold).
• RefreshStrategy::should_refresh: softer selection for opportunistic refreshes (e.g., approaching expiry thresholds or uneconomical unilateral exit).
• RefreshStrategy::should_refresh_exclusive: same as RefreshStrategy::should_refresh, but excludes VTXOs that meet the RefreshStrategy::must_refresh criteria.
• RefreshStrategy::should_refresh_if_must: same as RefreshStrategy::should_refresh, but only keeps the SHOULD VTXOs if at least one VTXO meets the MUST criteria.

Notes:

• This type implements FilterVtxos, so it can be passed directly to Wallet::vtxos_with.
• Calling FilterVtxos::matches on [RefreshStategy::should_result_if_must] is invalid.

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 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::{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).await?;

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 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::{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).await?;

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

Same as RefreshStrategy::should_refresh but it filters out VTXOs which meet the RefreshStrategy::must_refresh criteria.

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

Similar to calling RefreshStrategy::must_refresh and then RefreshStrategy::should_refresh_exclusive, but it only keeps the SHOULD VTXOs if at least one VTXO meets the MUST criteria.

Trait Implementations

impl FilterVtxos for RefreshStrategy<'_>

fn matches<'life0, 'life1, 'async_trait>( &'life0 self, vtxo: &'life1 WalletVtxo, ) -> Pin<Box<dyn Future<Output = Result<bool>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Check whether the VTXO mathes this filter

fn filter_vtxos<'life0, 'life1, 'async_trait, V>( &'life0 self, vtxos: &'life1 mut Vec<V>, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

where V: 'async_trait + Borrow<WalletVtxo> + Send, Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Eliminate from the vector all non-matching VTXOs