diff --git a/wallet/src/wallet/mod.rs b/wallet/src/wallet/mod.rs index ed6cb3f9..eb314219 100644 --- a/wallet/src/wallet/mod.rs +++ b/wallet/src/wallet/mod.rs @@ -2456,13 +2456,44 @@ 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 + /// + /// - 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. + /// - 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 + /// [`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; let canon_txids: Vec = self