Merge pull request #761 from lightninglabs/rpc-listtransfers-filtering

taprpc+tapdb: `ListTransfers` RPC optionally filters on anchor tx hash

Author: guggero

itest/assertions.go

@@ -1568,10 +1568,10 @@ func assertGroups(t *testing.T, client taprpc.TaprootAssetsClient,
 	require.NoError(t, err)
 
 	groupKeys := maps.Keys(assetGroups.Groups)
-	require.Equal(t, 2, len(groupKeys))
+	require.Len(t, groupKeys, 2)
 
 	groupedAssets := assetGroups.Groups[groupKeys[0]].Assets
-	require.Equal(t, 1, len(groupedAssets))
+	require.Len(t, groupedAssets, 1)
 	require.Equal(t, 1, len(assetGroups.Groups[groupKeys[1]].Assets))
 
 	groupedAssets = append(

rpcserver.go

@@ -973,10 +973,24 @@ func (r *rpcServer) ListBalances(ctx context.Context,
 
 // ListTransfers lists all asset transfers managed by this daemon.
 func (r *rpcServer) ListTransfers(ctx context.Context,
-	_ *taprpc.ListTransfersRequest) (*taprpc.ListTransfersResponse,
+	req *taprpc.ListTransfersRequest) (*taprpc.ListTransfersResponse,
 	error) {
 
-	parcels, err := r.cfg.AssetStore.QueryParcels(ctx, false)
+	// Unmarshal the anchor tx hash if one was provided.
+	var (
+		anchorTxHash *chainhash.Hash
+		err          error
+	)
+
+	if len(req.AnchorTxid) != 0 {
+		anchorTxHash, err = chainhash.NewHashFromStr(req.AnchorTxid)
+		if err != nil {
+			return nil, fmt.Errorf("invalid anchor tx hash: %w",
+				err)
+		}
+	}
+
+	parcels, err := r.cfg.AssetStore.QueryParcels(ctx, anchorTxHash, false)
 	if err != nil {
 		return nil, fmt.Errorf("failed to query parcels: %w", err)
 	}

tapdb/assets_store.go

@@ -2757,22 +2757,31 @@ func (a *AssetStore) reAnchorPassiveAssets(ctx context.Context,
 func (a *AssetStore) PendingParcels(
 	ctx context.Context) ([]*tapfreighter.OutboundParcel, error) {
 
-	return a.QueryParcels(ctx, true)
+	return a.QueryParcels(ctx, nil, true)
 }
 
 // QueryParcels returns the set of confirmed or unconfirmed parcels.
 func (a *AssetStore) QueryParcels(ctx context.Context,
+	anchorTxHash *chainhash.Hash,
 	pending bool) ([]*tapfreighter.OutboundParcel, error) {
 
 	var transfers []*tapfreighter.OutboundParcel
 
 	readOpts := NewAssetStoreReadTx()
 	dbErr := a.db.ExecTx(ctx, &readOpts, func(q ActiveAssetsStore) error {
+		// Construct transfer query.
+		transferQuery := TransferQuery{
+			UnconfOnly: pending,
+		}
+
+		// Include anchor tx hash if specified.
+		if anchorTxHash != nil {
+			transferQuery.AnchorTxHash = anchorTxHash[:]
+		}
+
 		// If we want every unconfirmed transfer, then we only pass in
 		// the UnconfOnly field.
-		dbTransfers, err := q.QueryAssetTransfers(ctx, TransferQuery{
-			UnconfOnly: pending,
-		})
+		dbTransfers, err := q.QueryAssetTransfers(ctx, transferQuery)
 		if err != nil {
 			return err
 		}

tapdb/assets_store_test.go

@@ -1261,7 +1261,7 @@ func TestAssetExportLog(t *testing.T) {
 	// looking for all unconfirmed transfers.
 	assetTransfers, err := db.QueryAssetTransfers(ctx, TransferQuery{})
 	require.NoError(t, err)
-	require.Equal(t, 1, len(assetTransfers))
+	require.Len(t, assetTransfers, 1)
 
 	// We should also be able to find it based on its outpoint.
 	firstOutput := spendDelta.Outputs[0]
@@ -1270,7 +1270,7 @@ func TestAssetExportLog(t *testing.T) {
 		AnchorTxHash: firstOutputAnchor.OutPoint.Hash[:],
 	})
 	require.NoError(t, err)
-	require.Equal(t, 1, len(assetTransfers))
+	require.Len(t, assetTransfers, 1)
 
 	// Check that the new UTXO is found among our managed UTXOs.
 	utxos, err = assetsStore.FetchManagedUTXOs(ctx)
@@ -1302,13 +1302,20 @@ func TestAssetExportLog(t *testing.T) {
 		UnconfOnly: true,
 	})
 	require.NoError(t, err)
-	require.Equal(t, 1, len(assetTransfers))
+	require.Len(t, assetTransfers, 1)
 
 	// This should also show up in the set of pending parcels. It should
 	// also match exactly the inbound parcel we used to make the delta.
 	parcels, err := assetsStore.PendingParcels(ctx)
 	require.NoError(t, err)
-	require.Equal(t, 1, len(parcels))
+	require.Len(t, parcels, 1)
+	require.Equal(t, spendDelta, parcels[0])
+
+	// We should also be able to query for the parcel when filtering on its
+	// anchor transaction hash.
+	parcels, err = assetsStore.QueryParcels(ctx, &anchorTxHash, true)
+	require.NoError(t, err)
+	require.Len(t, parcels, 1)
 	require.Equal(t, spendDelta, parcels[0])
 
 	// With the asset delta committed and verified, we'll now mark the
@@ -1421,7 +1428,7 @@ func TestAssetExportLog(t *testing.T) {
 	// At this point, there should be no more pending parcels.
 	parcels, err = assetsStore.PendingParcels(ctx)
 	require.NoError(t, err)
-	require.Equal(t, 0, len(parcels))
+	require.Len(t, parcels, 0)
 }
 
 // TestAssetGroupWitnessUpsert tests that if you try to insert another asset

taprpc/taprootassets.pb.go

@@ -460,6 +460,10 @@ message ListBalancesResponse {
 }
 
 message ListTransfersRequest {
+    // anchor_txid specifies the hexadecimal encoded txid string of the anchor
+    // transaction for which to retrieve transfers. An empty value indicates
+    // that this parameter should be disregarded in transfer selection.
+    string anchor_txid = 1;
 }
 
 message ListTransfersResponse {

taprpc/taprootassets.pb.gw.go

@@ -419,6 +419,47 @@
             }
           }
         },
+        "parameters": [
+          {
+            "name": "anchor_txid",
+            "description": "anchor_txid specifies the hexadecimal encoded txid string of the anchor\ntransaction for which to retrieve transfers. An empty value indicates\nthat this parameter should be disregarded in transfer selection.",
+            "in": "query",
+            "required": false,
+            "type": "string"
+          }
+        ],
+        "tags": [
+          "TaprootAssets"
+        ]
+      }
+    },
+    "/v1/taproot-assets/assets/transfers/{anchor_txid}": {
+      "get": {
+        "summary": "tapcli: `assets transfers`\nListTransfers lists outbound asset transfers tracked by the target daemon.",
+        "operationId": "TaprootAssets_ListTransfers2",
+        "responses": {
+          "200": {
+            "description": "A successful response.",
+            "schema": {
+              "$ref": "#/definitions/taprpcListTransfersResponse"
+            }
+          },
+          "default": {
+            "description": "An unexpected error response.",
+            "schema": {
+              "$ref": "#/definitions/rpcStatus"
+            }
+          }
+        },
+        "parameters": [
+          {
+            "name": "anchor_txid",
+            "description": "anchor_txid specifies the hexadecimal encoded txid string of the anchor\ntransaction for which to retrieve transfers. An empty value indicates\nthat this parameter should be disregarded in transfer selection.",
+            "in": "path",
+            "required": true,
+            "type": "string"
+          }
+        ],
         "tags": [
           "TaprootAssets"
         ]

taprpc/taprootassets.proto

@@ -71,6 +71,8 @@ http:
 
     - selector: taprpc.TaprootAssets.ListTransfers
       get: "/v1/taproot-assets/assets/transfers"
+      additional_bindings:
+        - get: "/v1/taproot-assets/assets/transfers/{anchor_txid}"
 
     - selector: taprpc.TaprootAssets.FetchAssetMeta
       get: "/v1/taproot-assets/assets/meta/asset-id/{asset_id_str}"