From 928476704bc90bdc651b03dd96c32a2002f5405e Mon Sep 17 00:00:00 2001 From: valued mammal Date: Mon, 7 Jul 2025 16:29:14 -0400 Subject: [PATCH 1/2] docs(wallet): expand docs for `apply_evicted_txs` --- wallet/src/wallet/mod.rs | 38 +++++++++++++++++++++++++++++++++----- 1 file changed, 33 insertions(+), 5 deletions(-) diff --git a/wallet/src/wallet/mod.rs b/wallet/src/wallet/mod.rs index ed6cb3f9..8b0e6683 100644 --- a/wallet/src/wallet/mod.rs +++ b/wallet/src/wallet/mod.rs @@ -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 + /// 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 pub fn apply_evicted_txs(&mut self, evicted_txs: impl IntoIterator) { let chain = &self.chain; let canon_txids: Vec = self From c1e7fcc65dd96775cf63322b2be29313f0432403 Mon Sep 17 00:00:00 2001 From: valued mammal Date: Mon, 14 Jul 2025 14:04:16 -0400 Subject: [PATCH 2/2] docs(wallet): update `apply_evicted_txs` documentation --- wallet/src/wallet/mod.rs | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/wallet/src/wallet/mod.rs b/wallet/src/wallet/mod.rs index 8b0e6683..eb314219 100644 --- a/wallet/src/wallet/mod.rs +++ b/wallet/src/wallet/mod.rs @@ -2479,8 +2479,10 @@ impl Wallet { /// /// ## Notes /// - /// - This function is particularly useful when syncing with a blockchain backend that provides - /// mempool eviction notifications. + /// - Not all blockchain backends support automatic mempool eviction handling - this method may + /// be used in such cases. It can also be used to negate the effect of + /// [`apply_unconfirmed_txs`] for a particular transaction without the need for an additional + /// sync. /// - 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. @@ -2490,6 +2492,7 @@ impl Wallet { /// influence the wallet's canonicalization logic. /// /// [`transactions`]: Wallet::transactions + /// [`apply_unconfirmed_txs`]: Wallet::apply_unconfirmed_txs /// [`start_sync_with_revealed_spks`]: Wallet::start_sync_with_revealed_spks pub fn apply_evicted_txs(&mut self, evicted_txs: impl IntoIterator) { let chain = &self.chain;