Merge pull request #97 from dcorral/upstream-list-transfers-filter

list_transfers to take an AssetFilter and an optional txid

Author: zoedberg

bindings/c-ffi/src/lib.rs

@@ -16,8 +16,8 @@ use rgb_lib::{
     keys::WitnessVersion,
     utils::BitcoinNetwork,
     wallet::{
-        Online, OnlineOptions, Recipient, RefreshFilter, RgbWalletOpsOffline, RgbWalletOpsOnline,
-        SinglesigKeys, SyncOptions, Wallet, WalletData,
+        AssetFilter, Online, OnlineOptions, Recipient, RefreshFilter, RgbWalletOpsOffline,
+        RgbWalletOpsOnline, SinglesigKeys, SyncOptions, Wallet, WalletData,
     },
 };
 
@@ -381,9 +381,10 @@ pub extern "C" fn rgblib_list_transactions(
 #[unsafe(no_mangle)]
 pub extern "C" fn rgblib_list_transfers(
     wallet: &COpaqueStruct,
-    asset_id_opt: *const c_char,
+    asset_filter: *const c_char,
+    txid_opt: *const c_char,
 ) -> CResultString {
-    list_transfers(wallet, asset_id_opt).into()
+    list_transfers(wallet, asset_filter, txid_opt).into()
 }
 
 #[unsafe(no_mangle)]

bindings/c-ffi/src/utils.rs

@@ -562,11 +562,13 @@ pub(crate) fn list_transactions(
 
 pub(crate) fn list_transfers(
     wallet: &COpaqueStruct,
-    asset_id_opt: *const c_char,
+    asset_filter: *const c_char,
+    txid_opt: *const c_char,
 ) -> Result<String, Error> {
     let wallet = Wallet::from_opaque(wallet)?;
-    let asset_id = convert_optional_string(asset_id_opt);
-    let res = wallet.list_transfers(asset_id)?;
+    let asset_filter: AssetFilter = serde_json::from_str(&ptr_to_string(asset_filter))?;
+    let txid = convert_optional_string(txid_opt);
+    let res = wallet.list_transfers(asset_filter, txid)?;
     Ok(serde_json::to_string(&res)?)
 }
 

bindings/uniffi/src/lib.rs

@@ -12,10 +12,10 @@ use rgb_lib::{
     keys::{Keys, WitnessVersion},
     utils::BitcoinNetwork,
     wallet::{
-        Address as RgbLibAddress, AssetCFA, AssetIFA, AssetNIA, AssetUDA, Assets,
-        AssignmentsCollection, Balance, BlockTime, BtcBalance, BurnBeginResult, BurnDetails,
-        Cosigner as CosignerData, DatabaseType, EmbeddedMedia, HubInfo, InflateBeginResult,
-        InflateDetails, InitOperationResult, Invoice as RgbLibInvoice,
+        Address as RgbLibAddress, AssetCFA, AssetFilter as RgbLibAssetFilter, AssetIFA, AssetNIA,
+        AssetUDA, Assets, AssignmentsCollection, Balance, BlockTime, BtcBalance, BurnBeginResult,
+        BurnDetails, Cosigner as CosignerData, DatabaseType, EmbeddedMedia, HubInfo,
+        InflateBeginResult, InflateDetails, InitOperationResult, Invoice as RgbLibInvoice,
         InvoiceData as RgbLibInvoiceData, Media, Metadata, MultisigKeys, MultisigOnlineOptions,
         MultisigVotingStatus as RgbLibMultisigVotingStatus, MultisigWallet as RgbLibMultisigWallet,
         Online, OnlineOptions, Operation as RgbLibOperation, OperationInfo as RgbLibOperationInfo,
@@ -71,6 +71,21 @@ impl From<SyncOptions> for RgbLibSyncOptions {
     }
 }
 
+pub enum AssetFilter {
+    AnyOrNone,
+    None,
+    Id { asset_id: String },
+}
+impl From<AssetFilter> for RgbLibAssetFilter {
+    fn from(orig: AssetFilter) -> Self {
+        match orig {
+            AssetFilter::AnyOrNone => RgbLibAssetFilter::AnyOrNone,
+            AssetFilter::None => RgbLibAssetFilter::None,
+            AssetFilter::Id { asset_id } => RgbLibAssetFilter::Id(asset_id),
+        }
+    }
+}
+
 // temporary solution needed because the Enum attribute doesn't support the Remote one
 pub enum Assignment {
     Fungible { amount: u64 },
@@ -1296,10 +1311,14 @@ impl Wallet {
         self._get_wallet().list_transactions(online, skip_sync)
     }
 
-    fn list_transfers(&self, asset_id: Option<String>) -> Result<Vec<Transfer>, RgbLibError> {
+    fn list_transfers(
+        &self,
+        asset_filter: AssetFilter,
+        txid: Option<String>,
+    ) -> Result<Vec<Transfer>, RgbLibError> {
         Ok(self
             ._get_wallet()
-            .list_transfers(asset_id)?
+            .list_transfers(asset_filter.into(), txid)?
             .into_iter()
             .map(|t| t.into())
             .collect())
@@ -1741,10 +1760,14 @@ impl MultisigWallet {
         self._get_wallet().list_transactions(online, skip_sync)
     }
 
-    fn list_transfers(&self, asset_id: Option<String>) -> Result<Vec<Transfer>, RgbLibError> {
+    fn list_transfers(
+        &self,
+        asset_filter: AssetFilter,
+        txid: Option<String>,
+    ) -> Result<Vec<Transfer>, RgbLibError> {
         Ok(self
             ._get_wallet()
-            .list_transfers(asset_id)?
+            .list_transfers(asset_filter.into(), txid)?
             .into_iter()
             .map(|t| t.into())
             .collect())

bindings/uniffi/src/rgb-lib.udl

@@ -331,6 +331,13 @@ interface Invoice {
   string invoice_string();
 };
 
+[Enum]
+interface AssetFilter {
+  AnyOrNone();
+  None();
+  Id(string asset_id);
+};
+
 [Enum]
 interface Assignment {
   Fungible(u64 amount);
@@ -954,7 +961,7 @@ interface Wallet {
   sequence<Transaction> list_transactions(Online? online, boolean skip_sync);
 
   [Throws=RgbLibError]
-  sequence<Transfer> list_transfers(string? asset_id);
+  sequence<Transfer> list_transfers(AssetFilter asset_filter, string? txid);
 
   [Throws=RgbLibError]
   sequence<Unspent> list_unspents(
@@ -1120,7 +1127,7 @@ interface MultisigWallet {
   sequence<Transaction> list_transactions(Online? online, boolean skip_sync);
 
   [Throws=RgbLibError]
-  sequence<Transfer> list_transfers(string? asset_id);
+  sequence<Transfer> list_transfers(AssetFilter asset_filter, string? txid);
 
   [Throws=RgbLibError]
   sequence<Unspent> list_unspents(

src/wallet/mod.rs

@@ -25,9 +25,9 @@ pub use multisig::{
     OperationInfo, RespondToOperation, UserRole,
 };
 pub use objects::{
-    Address, AssetCFA, AssetIFA, AssetNIA, AssetUDA, Assets, AssignmentsCollection, Balance,
-    BlockTime, BtcBalance, DatabaseType, EmbeddedMedia, Invoice, InvoiceData, Media, Metadata,
-    Online, Outpoint, PendingVanillaTx, ProofOfReserves, PsbtInputInfo, PsbtInspection,
+    Address, AssetCFA, AssetFilter, AssetIFA, AssetNIA, AssetUDA, Assets, AssignmentsCollection,
+    Balance, BlockTime, BtcBalance, DatabaseType, EmbeddedMedia, Invoice, InvoiceData, Media,
+    Metadata, Online, Outpoint, PendingVanillaTx, ProofOfReserves, PsbtInputInfo, PsbtInspection,
     PsbtOutputInfo, ReceiveData, Recipient, RecipientInfo, RecipientType, RgbAllocation,
     RgbInputInfo, RgbInspection, RgbOperationInfo, RgbOutputInfo, RgbTransitionInfo, Token,
     TokenLight, Transaction, TransactionType, Transfer, TransferKind, TransferTransportEndpoint,

src/wallet/multisig.rs

@@ -389,7 +389,6 @@ struct ReceiveMetadata {
 /// Operations for multisig wallets.
 #[derive(Debug, Clone, PartialEq, Eq, Deserialize, Serialize)]
 #[cfg(any(feature = "electrum", feature = "esplora"))]
-#[cfg_attr(feature = "camel_case", serde(rename_all = "camelCase"))]
 pub enum Operation {
     // CreateUtxos variants
     /// Create UTXOs operation waiting for user's response (ACK/NACK)
@@ -930,7 +929,6 @@ pub struct OperationInfo {
 /// Response to an operation.
 #[derive(Debug, Clone, PartialEq, Eq, Deserialize, Serialize)]
 #[cfg(any(feature = "electrum", feature = "esplora"))]
-#[cfg_attr(feature = "camel_case", serde(rename_all = "camelCase"))]
 pub enum RespondToOperation {
     /// ACK the operation with a signed PSBT
     Ack(String),
@@ -952,7 +950,6 @@ pub struct InitOperationResult {
 /// The role of the user on the hub.
 #[derive(Debug, Clone, PartialEq, Eq, Deserialize, Serialize)]
 #[cfg(any(feature = "electrum", feature = "esplora"))]
-#[cfg_attr(feature = "camel_case", serde(rename_all = "camelCase"))]
 pub enum UserRole {
     /// A cosigner
     Cosigner,

src/wallet/objects.rs

@@ -181,6 +181,17 @@ pub struct BlockTime {
 // Assets, tokens & media
 // ────────────────────────────────────────────────────────────
 
+/// An asset filter.
+#[derive(Debug, Clone, PartialEq, Eq, Deserialize, Serialize)]
+pub enum AssetFilter {
+    /// Match any or no asset
+    AnyOrNone,
+    /// Match no asset
+    None,
+    /// Match the asset with the given ID
+    Id(String),
+}
+
 /// An asset media file.
 #[derive(Debug, Clone, PartialEq, Eq, Hash, Deserialize, Serialize)]
 #[cfg_attr(feature = "camel_case", serde(rename_all = "camelCase"))]

src/wallet/offline.rs

@@ -2087,13 +2087,31 @@ pub trait WalletOffline: WalletBackup {
     fn list_transfers_impl(
         &self,
         txn: &DbTxn,
-        asset_id: Option<String>,
+        asset_filter: AssetFilter,
+        txid: Option<String>,
     ) -> Result<Vec<Transfer>, Error> {
         let db_data = txn.get_db_data(false)?;
+        let batch_transfer_idxs: Option<HashSet<i32>> = txid.map(|txid| {
+            db_data
+                .batch_transfers
+                .iter()
+                .filter(|b| b.txid.as_deref() == Some(txid.as_str()))
+                .map(|b| b.idx)
+                .collect()
+        });
         let asset_transfer_ids: Vec<i32> = db_data
             .asset_transfers
             .iter()
-            .filter(|t| t.asset_id == asset_id)
+            .filter(|t| match &asset_filter {
+                AssetFilter::AnyOrNone => true,
+                AssetFilter::None => t.asset_id.is_none(),
+                AssetFilter::Id(asset_id) => t.asset_id.as_ref() == Some(asset_id),
+            })
+            .filter(|t| {
+                batch_transfer_idxs
+                    .as_ref()
+                    .is_none_or(|idxs| idxs.contains(&t.batch_transfer_idx))
+            })
             .filter(|t| t.user_driven)
             .map(|t| t.idx)
             .collect();
@@ -2719,18 +2737,23 @@ pub trait RgbWalletOpsOffline: WalletOffline + WalletBackup {
 
     /// List the RGB [`Transfer`]s known to the wallet.
     ///
-    /// When an `asset_id` is not provided, return transfers that are not connected to a specific
-    /// asset.
-    fn list_transfers(&self, asset_id: Option<String>) -> Result<Vec<Transfer>, Error> {
+    /// `asset_filter` selects transfers by asset. When a `txid` is provided, restrict the result to the
+    /// transfers committed by the on-chain transaction with that ID; an unknown `txid` yields an
+    /// empty list.
+    fn list_transfers(
+        &self,
+        asset_filter: AssetFilter,
+        txid: Option<String>,
+    ) -> Result<Vec<Transfer>, Error> {
         info!(
             self.logger(),
-            "Listing transfers for asset '{:?}'...", asset_id
+            "Listing transfers for filter '{:?}' and txid '{:?}'...", asset_filter, txid
         );
         let txn = self.database().begin_transaction()?;
-        if let Some(asset_id) = &asset_id {
+        if let AssetFilter::Id(asset_id) = &asset_filter {
             txn.check_asset_exists(asset_id.clone())?;
         }
-        let transfers = self.list_transfers_impl(&txn, asset_id)?;
+        let transfers = self.list_transfers_impl(&txn, asset_filter, txid)?;
         txn.commit()?;
         info!(self.logger(), "List transfers completed");
         Ok(transfers)

src/wallet/test/list_transfers.rs

@@ -166,6 +166,116 @@ fn success() {
     );
 }
 
+#[cfg(feature = "electrum")]
+#[test]
+#[parallel]
+fn filters() {
+    initialize();
+
+    let amount: u64 = 66;
+
+    let mut party = get_funded_party!();
+    let mut rcv_party = get_funded_party!();
+
+    let asset_nia = party.issue_asset_nia(None);
+    let asset_cfa = party.issue_asset_cfa(None, None);
+
+    // one batch tx carrying transfers of both assets
+    let receive_nia = rcv_party.blind_receive();
+    let receive_cfa = rcv_party.blind_receive();
+    let recipient_map = HashMap::from([
+        (
+            asset_nia.asset_id.clone(),
+            vec![Recipient {
+                assignment: Assignment::Fungible(amount),
+                recipient_id: receive_nia.recipient_id.clone(),
+                witness_data: None,
+                transport_endpoints: TRANSPORT_ENDPOINTS.clone(),
+            }],
+        ),
+        (
+            asset_cfa.asset_id.clone(),
+            vec![Recipient {
+                assignment: Assignment::Fungible(amount),
+                recipient_id: receive_cfa.recipient_id.clone(),
+                witness_data: None,
+                transport_endpoints: TRANSPORT_ENDPOINTS.clone(),
+            }],
+        ),
+    ]);
+    let txid = party.send_retry(&recipient_map);
+    assert!(!txid.is_empty());
+
+    // AnyOrNone + txid: the tx's transfers across all assets
+    let by_txid = party.list_transfers_filtered(AssetFilter::AnyOrNone, Some(&txid));
+    assert_eq!(by_txid.len(), 2);
+    assert!(by_txid.iter().all(|t| t.txid == Some(txid.clone())));
+
+    // Id + txid: intersection, restricted to the given asset
+    let nia_by_txid =
+        party.list_transfers_filtered(AssetFilter::Id(asset_nia.asset_id.clone()), Some(&txid));
+    assert_eq!(nia_by_txid.len(), 1);
+    let expected: Vec<i32> = party
+        .list_transfers(Some(&asset_nia.asset_id))
+        .into_iter()
+        .filter(|t| t.txid == Some(txid.clone()))
+        .map(|t| t.idx)
+        .collect();
+    assert_eq!(vec![nia_by_txid[0].idx], expected);
+
+    // AnyOrNone + no txid: the whole history (2 issuances + 2 sends)
+    let all = party.list_transfers_filtered(AssetFilter::AnyOrNone, None);
+    assert_eq!(all.len(), 4);
+
+    // None: receiver's pending blind receives not yet tied to an asset
+    let pending = rcv_party.list_transfers_filtered(AssetFilter::None, None);
+    assert_eq!(pending.len(), 2);
+
+    // extra receive that nothing is sent to, stays asset-less
+    let receive_extra = rcv_party.blind_receive();
+
+    // settle the batch so the change is spendable again
+    rcv_party.wait_for_refresh(None);
+    // the refresh tied the 2 receives to their assets, only the extra one stays asset-less
+    let all_rcv = rcv_party.list_transfers_filtered(AssetFilter::AnyOrNone, None);
+    assert_eq!(all_rcv.len(), 3);
+    let pending = rcv_party.list_transfers_filtered(AssetFilter::None, None);
+    assert_eq!(pending.len(), 1);
+    assert_eq!(pending[0].recipient_id, Some(receive_extra.recipient_id));
+    // receiver side: the tx's transfers span 2 batch transfers sharing the same txid
+    let rcv_by_txid = rcv_party.list_transfers_filtered(AssetFilter::AnyOrNone, Some(&txid));
+    assert_eq!(rcv_by_txid.len(), 2);
+    party.wait_for_refresh(None);
+    mine(false);
+    rcv_party.wait_for_refresh(None);
+    party.wait_for_refresh(None);
+
+    // Id + txid of a tx not carrying that asset: empty
+    let receive_nia_2 = rcv_party.blind_receive();
+    let recipient_map = HashMap::from([(
+        asset_nia.asset_id.clone(),
+        vec![Recipient {
+            assignment: Assignment::Fungible(amount),
+            recipient_id: receive_nia_2.recipient_id.clone(),
+            witness_data: None,
+            transport_endpoints: TRANSPORT_ENDPOINTS.clone(),
+        }],
+    )]);
+    let txid_2 = party.send_retry(&recipient_map);
+    assert!(
+        party
+            .list_transfers_filtered(AssetFilter::Id(asset_cfa.asset_id.clone()), Some(&txid_2))
+            .is_empty()
+    );
+
+    // unknown txid: empty
+    assert!(
+        party
+            .list_transfers_filtered(AssetFilter::AnyOrNone, Some(FAKE_TXID))
+            .is_empty()
+    );
+}
+
 #[test]
 #[parallel]
 fn fail() {
@@ -174,4 +284,9 @@ fn fail() {
     // asset not found
     let result = party.list_transfers_result(Some("rgb1inexistent"));
     assert!(matches!(result, Err(Error::AssetNotFound { asset_id: _ })));
+
+    // asset not found also when a txid is given
+    let result = party
+        .list_transfers_filtered_result(AssetFilter::Id(s!("rgb1inexistent")), Some(FAKE_TXID));
+    assert!(matches!(result, Err(Error::AssetNotFound { asset_id: _ })));
 }

src/wallet/test/mod.rs

@@ -126,7 +126,6 @@ const IDENT_NOT_ASCII_MSG: &str = "string '{0}' contains invalid character '{1}'
 const IDENT_NOT_START_MSG: &str = "string '{0}' must not start with character '{1}'.";
 #[cfg(any(feature = "electrum", feature = "esplora"))]
 const MIN_CONFIRMATIONS: u8 = 1;
-#[cfg(feature = "electrum")]
 const FAKE_TXID: &str = "e5a3e577309df31bd606f48049049d2e1e02b048206ba232944fcc053a176ccb";
 #[cfg(feature = "electrum")]
 const FAKE_OUTPOINT: &str = "e5a3e577309df31bd606f48049049d2e1e02b048206ba232944fcc053a176ccb:0";