Skip to content

docs(wallet): expand docs for apply_evicted_txs #270

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open

docs(wallet): expand docs for apply_evicted_txs #270

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
9284767
docs(wallet): expand docs for `apply_evicted_txs`
ValuedMammal Jul 7, 2025
c1e7fcc
docs(wallet): update `apply_evicted_txs` documentation
ValuedMammal Jul 14, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 33 additions & 5 deletions wallet/src/wallet/mod.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2456,13 +2456,41 @@ impl Wallet {
self.stage.merge(indexed_graph_changeset.into());
}

/// Apply evictions of the given txids with their associated timestamps.
/// Apply evictions of the given transaction IDs with their associated timestamps.
///
/// This means that any pending unconfirmed tx in this set will no longer be canonical by
/// default. Note that an evicted tx can become canonical if it is later seen again or
/// observed on-chain.
/// This function is used to mark specific unconfirmed transactions as evicted from the mempool.
/// Eviction means that these transactions are not considered canonical by default, and will
/// no longer be part of the wallet's [`transactions`] set. This can happen for example when
/// a transaction is dropped from the mempool due to low fees or conflicts with another
/// transaction.
///
/// This stages the changes which need to be persisted.
/// Only transactions that are currently unconfirmed and canonical are considered for eviction.
/// Transactions that are not relevant to the wallet are ignored. Note that an evicted
/// transaction can become canonical again if it is later observed on-chain or seen in the
/// mempool with a higher priority (e.g., due to a fee bump).
///
/// ## Parameters
///
/// `evicted_txs`: An iterator of `(Txid, u64)` tuples, where:
/// - `Txid`: The transaction ID of the transaction to be evicted.
/// - `u64`: The timestamp indicating when the transaction was evicted from the mempool. This
/// will usually correspond to the time of the latest chain sync. See docs for
/// [`start_sync_with_revealed_spks`].
///
/// ## Notes
///
/// - This function is particularly useful when syncing with a blockchain backend that provides
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's not clear to me if or when a user needs to use this function. Don't the bdk_* chain clients already evict tx when they notice it missing from the mempool?

/// mempool eviction notifications.
/// - The changes are staged in the wallet's internal state and must be persisted to ensure they
/// are retained across wallet restarts. Use [`Wallet::take_staged`] to retrieve the staged
/// changes and persist them to your database of choice.
/// - Evicted transactions are removed from the wallet's canonical transaction set, but the data
/// remains in the wallet's internal transaction graph for historical purposes.
/// - Ensure that the timestamps provided are accurate and monotonically increasing, as they
/// influence the wallet's canonicalization logic.
///
/// [`transactions`]: Wallet::transactions
/// [`start_sync_with_revealed_spks`]: Wallet::start_sync_with_revealed_spks
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it would be great to also include an example here:

Suggested change
/// [`start_sync_with_revealed_spks`]: Wallet::start_sync_with_revealed_spks
/// [`start_sync_with_revealed_spks`]: Wallet::start_sync_with_revealed_spks
/// ## Example
///
/// ```rust
/// use bdk_wallet::{Wallet, bitcoin::Txid};
/// use std::collections::HashSet;
///
/// let unconfirmed_txids: HashSet<Txid> = wallet
/// .transactions()
/// .filter(|tx| tx.chain_position.is_unconfirmed())
/// .map(|tx| tx.tx_node.txid)
/// .collect();
///
/// let mut evicted_txs = Vec::new();
/// for txid in unconfirmed_txids {
/// let tx_node = wallet.tx_graph().full_txs().find(|tx| tx.txid == txid);
/// let wallet_tx = wallet.get_tx(txid);
/// let is_evicted = wallet_tx.map_or(true, |tx| {
/// !tx.chain_position.is_unconfirmed() && !tx.chain_position.is_confirmed()
/// });
/// if is_evicted {
/// let last_seen = tx_node.map_or(0, |tx| tx.last_seen.unwrap_or(0));
/// evicted_txs.push((txid, last_seen));
/// }
/// }
///
/// if !evicted_txs.is_empty() {
/// wallet.apply_evicted_txs(evicted_txs)?;
/// wallet.persist(&mut db)?;
/// }

pub fn apply_evicted_txs(&mut self, evicted_txs: impl IntoIterator<Item = (Txid, u64)>) {
let chain = &self.chain;
let canon_txids: Vec<Txid> = self
Expand Down
Loading