Merge #1477: feat(wallet): add transactions_sort_by function

83a0247 feat(wallet): add transactions_sort_by function (Steve Myers)

Pull request description:

  ### Description

  Added new type alias `WalletTx` which represents a `CanonicalTx<'a, Arc<Transaction>, ConfirmationTimeHeightAnchor>` and new `Wallet::transactions_sort_by` that returns a `Vec<WalletTx>` sorted by the given compare function.

  ### Notes to the reviewers

  fixes #794

  ### Changelog notice

  * Add new type alias `WalletTx` which represents a `CanonicalTx<'a, Arc<Transaction>, ConfirmationTimeHeightAnchor>`.
  * Add `Wallet::transactions_sort_by()` that returns a `Vec<WalletTx>` sorted by a given compare function.

  ### Checklists

  #### All Submissions:

  * [x] I've signed all my commits
  * [x] I followed the [contribution guidelines](https://github.com/bitcoindevkit/bdk/blob/master/CONTRIBUTING.md)
  * [x] I ran `cargo fmt` and `cargo clippy` before committing

  #### New Features:

  * [x] I've added tests for the new feature
  * [x] I've added docs for the new feature

Top commit has no ACKs.

Tree-SHA512: 5758b5edf8200b5534b7a7f538de640e85083bed3da2585109190f0efda3e238f5483d4a2dc073dc4b907644f58b7158a922ebe09d03a47201030162d4b0f4d3

crates/wallet/src/wallet/mod.rs

@@ -45,6 +45,7 @@ use bitcoin::{
 use bitcoin::{consensus::encode::serialize, transaction, BlockHash, Psbt};
 use bitcoin::{constants::genesis_block, Amount};
 use bitcoin::{secp256k1::Secp256k1, Weight};
+use core::cmp::Ordering;
 use core::fmt;
 use core::mem;
 use core::ops::Deref;
@@ -291,6 +292,9 @@ impl fmt::Display for ApplyBlockError {
 #[cfg(feature = "std")]
 impl std::error::Error for ApplyBlockError {}
 
+/// A `CanonicalTx` managed by a `Wallet`.
+pub type WalletTx<'a> = CanonicalTx<'a, Arc<Transaction>, ConfirmationBlockTime>;
+
 impl Wallet {
  /// Build a new single descriptor [`Wallet`].
  ///
@@ -1002,9 +1006,9 @@ impl Wallet {
  self.indexed_graph.index.sent_and_received(tx, ..)
  }
 
- /// Get a single transaction from the wallet as a [`CanonicalTx`] (if the transaction exists).
+ /// Get a single transaction from the wallet as a [`WalletTx`] (if the transaction exists).
  ///
- /// `CanonicalTx` contains the full transaction alongside meta-data such as:
+ /// `WalletTx` contains the full transaction alongside meta-data such as:
  /// * Blocks that the transaction is [`Anchor`]ed in. These may or may not be blocks that exist
  /// in the best chain.
  /// * The [`ChainPosition`] of the transaction in the best chain - whether the transaction is
@@ -1018,21 +1022,21 @@ impl Wallet {
  /// # let wallet: Wallet = todo!();
  /// # let my_txid: bitcoin::Txid = todo!();
  ///
- /// let canonical_tx = wallet.get_tx(my_txid).expect("panic if tx does not exist");
+ /// let wallet_tx = wallet.get_tx(my_txid).expect("panic if tx does not exist");
  ///
  /// // get reference to full transaction
- /// println!("my tx: {:#?}", canonical_tx.tx_node.tx);
+ /// println!("my tx: {:#?}", wallet_tx.tx_node.tx);
  ///
  /// // list all transaction anchors
- /// for anchor in canonical_tx.tx_node.anchors {
+ /// for anchor in wallet_tx.tx_node.anchors {
  /// println!(
  /// "tx is anchored by block of hash {}",
  /// anchor.anchor_block().hash
  /// );
  /// }
  ///
  /// // get confirmation status of transaction
- /// match canonical_tx.chain_position {
+ /// match wallet_tx.chain_position {
  /// ChainPosition::Confirmed(anchor) => println!(
  /// "tx is confirmed at height {}, we know this since {}:{} is in the best chain",
  /// anchor.block_id.height, anchor.block_id.height, anchor.block_id.hash,
@@ -1045,13 +1049,10 @@ impl Wallet {
  /// ```
  ///
  /// [`Anchor`]: bdk_chain::Anchor
- pub fn get_tx(
- &self,
- txid: Txid,
- ) -> Option<CanonicalTx<'_, Arc<Transaction>, ConfirmationBlockTime>> {
+ pub fn get_tx(&self, txid: Txid) -> Option<WalletTx> {
  let graph = self.indexed_graph.graph();
 
- Some(CanonicalTx {
+ Some(WalletTx {
  chain_position: graph.get_chain_position(
  &self.chain,
  self.chain.tip().block_id(),
@@ -1102,14 +1103,33 @@ impl Wallet {
  }
 
  /// Iterate over the transactions in the wallet.
- pub fn transactions(
- &self,
- ) -> impl Iterator<Item = CanonicalTx<'_, Arc<Transaction>, ConfirmationBlockTime>> + '_ {
+ pub fn transactions(&self) -> impl Iterator<Item = WalletTx> + '_ {
  self.indexed_graph
  .graph()
  .list_canonical_txs(&self.chain, self.chain.tip().block_id())
  }
 
+ /// Array of transactions in the wallet sorted with a comparator function.
+ ///
+ /// # Example
+ ///
+ /// ```rust,no_run
+ /// # use bdk_wallet::{LoadParams, Wallet, WalletTx};
+ /// # let mut wallet:Wallet = todo!();
+ /// // Transactions by chain position: first unconfirmed then descending by confirmed height.
+ /// let sorted_txs: Vec<WalletTx> =
+ /// wallet.transactions_sort_by(|tx1, tx2| tx2.chain_position.cmp(&tx1.chain_position));
+ /// # Ok::<(), anyhow::Error>(())
+ /// ```
+ pub fn transactions_sort_by<F>(&self, compare: F) -> Vec<WalletTx>
+ where
+ F: FnMut(&WalletTx, &WalletTx) -> Ordering,
+ {
+ let mut txs: Vec<WalletTx> = self.transactions().collect();
+ txs.sort_unstable_by(compare);
+ txs
+ }
+
  /// Return the balance, separated into available, trusted-pending, untrusted-pending and immature
  /// values.
  pub fn balance(&self) -> Balance {

crates/wallet/tests/wallet.rs

@@ -13,7 +13,7 @@ use bdk_wallet::error::CreateTxError;
 use bdk_wallet::psbt::PsbtUtils;
 use bdk_wallet::signer::{SignOptions, SignerError};
 use bdk_wallet::tx_builder::AddForeignUtxoError;
-use bdk_wallet::{AddressInfo, Balance, ChangeSet, Wallet, WalletPersister};
+use bdk_wallet::{AddressInfo, Balance, ChangeSet, Wallet, WalletPersister, WalletTx};
 use bdk_wallet::{KeychainKind, LoadError, LoadMismatch, LoadWithPersistError};
 use bitcoin::constants::ChainHash;
 use bitcoin::hashes::Hash;
@@ -4203,3 +4203,18 @@ fn single_descriptor_wallet_can_create_tx_and_receive_change() {
  "tx change should go to external keychain"
  );
 }
+
+#[test]
+fn test_transactions_sort_by() {
+ let (mut wallet, _txid) = get_funded_wallet_wpkh();
+ receive_output(&mut wallet, 25_000, ConfirmationTime::unconfirmed(0));
+
+ // sort by chain position, unconfirmed then confirmed by descending block height
+ let sorted_txs: Vec<WalletTx> =
+ wallet.transactions_sort_by(|t1, t2| t2.chain_position.cmp(&t1.chain_position));
+ let conf_heights: Vec<Option<u32>> = sorted_txs
+ .iter()
+ .map(|tx| tx.chain_position.confirmation_height_upper_bound())
+ .collect();
+ assert_eq!([None, Some(2000), Some(1000)], conf_heights.as_slice());
+}