tapdb: generalise QueryAssetTransfers arg flag unconf_only

This commit renames and generalizes the `unconf_only` argument in the
`QueryAssetTransfers` SQL query to `pending_transfers_only`. The flag
now returns pending transfers with unconfirmed anchoring transactions or
undelivered transfer output proofs.

Additionally, this update includes the anchor transaction block hash in
the query's returned values. This allows users to determine if a
transfer's anchoring transaction has been confirmed on-chain, providing
context for why the transfer is pending.

As a result of this change, ExportLog.PendingParcels will now also
include transfers that are pending due to undelivered proofs, even if
their associated anchoring transactions have already been confirmed
on-chain.

Author: ffranr

tapdb/assets_store.go

@@ -3128,9 +3128,13 @@ func (a *AssetStore) reAnchorPassiveAssets(ctx context.Context,
 	return nil
 }
 
-// PendingParcels returns the set of parcels that haven't yet been finalized.
-// This can be used to query the set of unconfirmed
-// transactions for re-broadcast.
+// PendingParcels returns the set of parcels that have not yet been finalized.
+// A parcel is considered finalized once the on-chain anchor transaction is
+// included in a block, and all pending transfer output proofs have been
+// delivered to their target peers.
+//
+// NOTE: This can be used to query the set of unconfirmed transactions for
+// re-broadcast and for the set of undelivered proofs.
 func (a *AssetStore) PendingParcels(
 	ctx context.Context) ([]*tapfreighter.OutboundParcel, error) {
 
@@ -3140,7 +3144,7 @@ func (a *AssetStore) PendingParcels(
 // QueryParcels returns the set of confirmed or unconfirmed parcels.
 func (a *AssetStore) QueryParcels(ctx context.Context,
 	anchorTxHash *chainhash.Hash,
-	unconfirmedTxOnly bool) ([]*tapfreighter.OutboundParcel, error) {
+	pendingTransfersOnly bool) ([]*tapfreighter.OutboundParcel, error) {
 
 	var (
 		outboundParcels []*tapfreighter.OutboundParcel
@@ -3157,10 +3161,8 @@ func (a *AssetStore) QueryParcels(ctx context.Context,
 		}
 
 		transferQuery := TransferQuery{
-			// If we want unconfirmed transfers only, we set the
-			// UnconfOnly field to true.
-			UnconfOnly:   unconfirmedTxOnly,
-			AnchorTxHash: anchorTxHashBytes,
+			AnchorTxHash:         anchorTxHashBytes,
+			PendingTransfersOnly: sqlBool(pendingTransfersOnly),
 		}
 
 		// Query for asset transfers.
@@ -3210,9 +3212,22 @@ func (a *AssetStore) QueryParcels(ctx context.Context,
 					"anchor tx: %w", err)
 			}
 
+			// Marshal anchor tx block hash from the database to a
+			// Hash type.
+			var anchorTxBlockHash fn.Option[chainhash.Hash]
+			if len(dbT.AnchorTxBlockHash) > 0 {
+				var blockHash chainhash.Hash
+				copy(blockHash[:], dbT.AnchorTxBlockHash)
+
+				anchorTxBlockHash = fn.Some[chainhash.Hash](
+					blockHash,
+				)
+			}
+
 			parcel := &tapfreighter.OutboundParcel{
 				AnchorTx:           anchorTx,
 				AnchorTxHeightHint: uint32(dbT.HeightHint),
+				AnchorTxBlockHash:  anchorTxBlockHash,
 				TransferTime:       dbT.TransferTimeUnix.UTC(),
 				ChainFees:          dbAnchorTx.ChainFees,
 				Inputs:             inputs,

tapdb/assets_store_test.go

@@ -1451,10 +1451,16 @@ func TestAssetExportLog(t *testing.T) {
 
 	// At this point, we should be able to query for the log parcel, by
 	// looking for all unconfirmed transfers.
-	assetTransfers, err := db.QueryAssetTransfers(ctx, TransferQuery{})
+	assetTransfers, err := db.QueryAssetTransfers(ctx, TransferQuery{
+		PendingTransfersOnly: sqlBool(true),
+	})
 	require.NoError(t, err)
 	require.Len(t, assetTransfers, 1)
 
+	// This transfer's anchor transaction is unconfirmed. Therefore, the
+	// anchor transaction block hash field of the transfer should be unset.
+	require.Empty(t, assetTransfers[0].AnchorTxBlockHash)
+
 	// We should also be able to find it based on its outpoint.
 	firstOutput := spendDelta.Outputs[0]
 	firstOutputAnchor := firstOutput.Anchor
@@ -1494,7 +1500,7 @@ func TestAssetExportLog(t *testing.T) {
 	// Finally, if we look for the set of confirmed transfers, nothing
 	// should be returned.
 	assetTransfers, err = db.QueryAssetTransfers(ctx, TransferQuery{
-		UnconfOnly: true,
+		PendingTransfersOnly: sqlBool(true),
 	})
 	require.NoError(t, err)
 	require.Len(t, assetTransfers, 1)
@@ -2088,7 +2094,33 @@ func TestTransferOutputProofDeliveryStatus(t *testing.T) {
 
 	// At this point, we should be able to query for the log parcel, by
 	// looking for all unconfirmed transfers.
-	assetTransfers, err := db.QueryAssetTransfers(ctx, TransferQuery{})
+	assetTransfers, err := db.QueryAssetTransfers(ctx, TransferQuery{
+		PendingTransfersOnly: sqlBool(true),
+	})
+	require.NoError(t, err)
+	require.Len(t, assetTransfers, 1)
+
+	// This transfer's anchor transaction is unconfirmed. Therefore, the
+	// anchor transaction block hash field of the transfer should be unset.
+	require.Empty(t, assetTransfers[0].AnchorTxBlockHash)
+
+	// At this point we will confirm the anchor tx on-chain.
+	assetTransfer := assetTransfers[0]
+	randBlockHash := test.RandHash()
+
+	err = db.ConfirmChainAnchorTx(ctx, AnchorTxConf{
+		Txid:        assetTransfer.Txid,
+		BlockHash:   randBlockHash[:],
+		BlockHeight: sqlInt32(441),
+		TxIndex:     sqlInt32(1),
+	})
+	require.NoError(t, err)
+
+	// Ensure that parcel is still pending. It should be pending due to the
+	// incomplete proof delivery status of some transfer outputs.
+	assetTransfers, err = db.QueryAssetTransfers(ctx, TransferQuery{
+		PendingTransfersOnly: sqlBool(true),
+	})
 	require.NoError(t, err)
 	require.Len(t, assetTransfers, 1)
 
@@ -2140,4 +2172,35 @@ func TestTransferOutputProofDeliveryStatus(t *testing.T) {
 	require.Equal(
 		t, sql.NullBool{}, transferOutputs[1].ProofDeliveryComplete,
 	)
+
+	// At this point the anchoring transaction has been confirmed on-chain
+	// and the proof delivery status shows complete for all applicable
+	// transfer outputs. Therefore, we should not be able to find any
+	// pending transfers.
+	assetTransfers, err = db.QueryAssetTransfers(ctx, TransferQuery{
+		PendingTransfersOnly: sqlBool(true),
+	})
+	require.NoError(t, err)
+	require.Len(t, assetTransfers, 0)
+
+	// Given that the asset transfer is completely finalised, we should be
+	// able to find it among the confirmed transfers. We will test this by
+	// retrieving the transfer by not specifying the pending transfers only
+	// flag and, in another attempt, by setting the flag to false.
+	assetTransfers, err = db.QueryAssetTransfers(ctx, TransferQuery{})
+	require.NoError(t, err)
+	require.Len(t, assetTransfers, 1)
+
+	assetTransfers, err = db.QueryAssetTransfers(ctx, TransferQuery{
+		PendingTransfersOnly: sqlBool(false),
+	})
+	require.NoError(t, err)
+	require.Len(t, assetTransfers, 1)
+
+	// Ensure that the anchor transaction is confirmed on-chain by verifying
+	// that the anchor transaction block hash field on the transfer is
+	// correctly set.
+	require.Equal(
+		t, randBlockHash[:], assetTransfers[0].AnchorTxBlockHash,
+	)
 }

tapdb/sqlc/querier.go

@@ -43,19 +43,30 @@ WHERE output_id = (SELECT output_id FROM target);
 
 -- name: QueryAssetTransfers :many
 SELECT
-    id, height_hint, txns.txid, transfer_time_unix
+    id, height_hint, txns.txid, txns.block_hash AS anchor_tx_block_hash,
+    transfer_time_unix
 FROM asset_transfers transfers
 JOIN chain_txns txns
-    ON transfers.anchor_txn_id = txns.txn_id
--- We'll use this clause to filter out for only transfers that are
--- unconfirmed. But only if the unconf_only field is set.
-WHERE (@unconf_only = false OR @unconf_only IS NULL OR
-    (CASE WHEN txns.block_hash IS NULL THEN true ELSE false END) = @unconf_only)
+    ON txns.txn_id = transfers.anchor_txn_id
+WHERE
+    -- Optionally filter on a given anchor_tx_hash.
+    (txns.txid = sqlc.narg('anchor_tx_hash')
+        OR sqlc.narg('anchor_tx_hash') IS NULL)
 
--- Here we have another optional query clause to select a given transfer
--- based on the anchor_tx_hash, but only if it's specified.
-AND (txns.txid = sqlc.narg('anchor_tx_hash') OR
-    sqlc.narg('anchor_tx_hash') IS NULL)
+    -- Filter for pending transfers only if requested.
+    AND (
+        @pending_transfers_only = true AND
+        (
+            txns.block_hash IS NULL
+                OR EXISTS (
+                    SELECT 1
+                    FROM asset_transfer_outputs outputs
+                    WHERE outputs.transfer_id = transfers.id
+                      AND outputs.proof_delivery_complete = false
+                )
+        )
+        OR @pending_transfers_only = false OR @pending_transfers_only IS NULL
+    )
 ORDER BY transfer_time_unix;
 
 -- name: FetchTransferInputs :many

tapdb/sqlc/queries/transfers.sql

@@ -314,6 +314,11 @@ type OutboundParcel struct {
 	// confirmations.
 	AnchorTxHeightHint uint32
 
+	// AnchorTxBlockHash is the block hash of the block that contains the
+	// anchor transaction. This is set once the anchor transaction is
+	// confirmed.
+	AnchorTxBlockHash fn.Option[chainhash.Hash]
+
 	// TransferTime holds the timestamp of the outbound spend.
 	TransferTime time.Time