feat: implement zero-value UTXO sweeping mechanism

- Add database query to fetch managed UTXOs containing only zero-value assets (tombstones/burns)
- Implement ZeroValueInput interface for accessing UTXO details
- Modify PSBT creation to include zero-value inputs with proper BIP32 derivation
- Update integration test to verify sweeping functionality
- Add sweeping logic to automatically include tombstone inputs in new on-chain transactions

Note: LND limitation prevents imported Taproot keys from being signed, so sweeping
requires LND changes to fully work.

Author: darioAnongba

itest/test_list_on_test.go

@@ -101,6 +101,10 @@ var allTestCases = []*testCase{
 		name: "min relay fee bump",
 		test: testMinRelayFeeBump,
 	},
+	{
+		name: "zero value anchor sweep",
+		test: testZeroValueAnchorSweep,
+	},
 	{
 		name: "restart receiver check balance",
 		test: testRestartReceiverCheckBalance,

rpcserver.go

@@ -1419,14 +1419,6 @@ func (r *rpcServer) ListUtxos(ctx context.Context,
 		utxos[op] = utxo
 	}
 
-	// As a final pass, we'll prune out any UTXOs that don't have any
-	// assets, as these may be in the DB just for record keeping.
-	for _, utxo := range utxos {
-		if len(utxo.Assets) == 0 {
-			delete(utxos, utxo.OutPoint)
-		}
-	}
-
 	return &taprpc.ListUtxosResponse{
 		ManagedUtxos: utxos,
 	}, nil

tapdb/assets_store.go

@@ -491,6 +491,26 @@ type ManagedUTXO struct {
 	LeaseExpiry time.Time
 }
 
+// GetOutPoint returns the outpoint of the zero-value UTXO.
+func (m *ManagedUTXO) GetOutPoint() wire.OutPoint {
+	return m.OutPoint
+}
+
+// GetOutputValue returns the satoshi value of the zero-value UTXO.
+func (m *ManagedUTXO) GetOutputValue() btcutil.Amount {
+	return m.OutputValue
+}
+
+// GetInternalKey returns the internal key descriptor for the zero-value UTXO.
+func (m *ManagedUTXO) GetInternalKey() keychain.KeyDescriptor {
+	return m.InternalKey
+}
+
+// GetMerkleRoot returns the taproot merkle root for the zero-value UTXO.
+func (m *ManagedUTXO) GetMerkleRoot() []byte {
+	return m.MerkleRoot
+}
+
 // AssetHumanReadable is a subset of the base asset struct that only includes
 // human-readable asset fields.
 type AssetHumanReadable struct {
@@ -1320,6 +1340,68 @@ func (a *AssetStore) FetchManagedUTXOs(ctx context.Context) (
 	return managedUtxos, nil
 }
 
+// FetchZeroValueAnchorUTXOs fetches all managed UTXOs that contain only
+// zero-value assets (tombstones and burns).
+func (a *AssetStore) FetchZeroValueAnchorUTXOs(ctx context.Context) (
+	[]tapfreighter.ZeroValueInput, error) {
+
+	var (
+		utxos []sqlc.FetchZeroValueAnchorUTXOsRow
+		err   error
+	)
+
+	readOpts := NewAssetStoreReadTx()
+	dbErr := a.db.ExecTx(ctx, &readOpts, func(q ActiveAssetsStore) error {
+		// Cast to sqlc.Querier to access FetchZeroValueAnchorUTXOs
+		utxos, err = q.(sqlc.Querier).FetchZeroValueAnchorUTXOs(ctx)
+		return err
+	})
+	if dbErr != nil {
+		return nil, dbErr
+	}
+
+	managedUtxos := make([]tapfreighter.ZeroValueInput, len(utxos))
+	for i, u := range utxos {
+		var anchorPoint wire.OutPoint
+		err := readOutPoint(
+			bytes.NewReader(u.Outpoint), 0, 0, &anchorPoint,
+		)
+		if err != nil {
+			return nil, err
+		}
+
+		internalKey, err := btcec.ParsePubKey(u.RawKey)
+		if err != nil {
+			return nil, err
+		}
+
+		utxo := &ManagedUTXO{
+			OutPoint:    anchorPoint,
+			OutputValue: btcutil.Amount(u.AmtSats),
+			InternalKey: keychain.KeyDescriptor{
+				PubKey: internalKey,
+				KeyLocator: keychain.KeyLocator{
+					Index: uint32(u.KeyIndex),
+					Family: keychain.KeyFamily(
+						u.KeyFamily,
+					),
+				},
+			},
+			TaprootAssetRoot: u.TaprootAssetRoot,
+			MerkleRoot:       u.MerkleRoot,
+			TapscriptSibling: u.TapscriptSibling,
+			LeaseOwner:       u.LeaseOwner,
+		}
+		if u.LeaseExpiry.Valid {
+			utxo.LeaseExpiry = u.LeaseExpiry.Time
+		}
+
+		managedUtxos[i] = utxo
+	}
+
+	return managedUtxos, nil
+}
+
 // FetchAssetProofsSizes fetches the sizes of the proofs in the db.
 func (a *AssetStore) FetchAssetProofsSizes(
 	ctx context.Context) ([]AssetProofSize, error) {

tapdb/sqlc/assets.sql.go

@@ -633,6 +633,37 @@ FROM managed_utxos utxos
 JOIN internal_keys keys
     ON utxos.internal_key_id = keys.key_id;
 
+-- name: FetchZeroValueAnchorUTXOs :many
+WITH zero_value_assets AS (
+    SELECT DISTINCT anchor_utxo_id
+    FROM assets a
+    JOIN script_keys sk ON a.script_key_id = sk.script_key_id
+    JOIN internal_keys ik ON sk.internal_key_id = ik.key_id
+    LEFT JOIN asset_witnesses aw ON a.asset_id = aw.asset_id
+    WHERE (
+        -- Tombstones: zero amount with NUMS key
+        (a.amount = 0 AND ik.raw_key = '\x02\x7c\x79\xb9\xb2\x6e\x46\x38\x95\xee\xf5\x67\x9d\x85\x58\x94\x2c\x86\xc4\xad\x22\x33\xad\xef\x01\xbc\x3e\x6d\x54\x0b\x36\x53\xfe') OR
+        -- Burns: assets with burn witnesses
+        (aw.witness_id IS NOT NULL AND aw.witness_stack IS NOT NULL)
+    )
+    AND a.spent = FALSE
+),
+anchor_asset_counts AS (
+    SELECT
+        anchor_utxo_id,
+        COUNT(*) as total_assets,
+        COUNT(CASE WHEN anchor_utxo_id IN (SELECT anchor_utxo_id FROM zero_value_assets) THEN 1 END) as zero_value_assets
+    FROM assets
+    WHERE spent = FALSE
+    GROUP BY anchor_utxo_id
+)
+SELECT utxos.*, keys.*
+FROM managed_utxos utxos
+JOIN internal_keys keys ON utxos.internal_key_id = keys.key_id
+JOIN anchor_asset_counts aac ON utxos.utxo_id = aac.anchor_utxo_id
+WHERE aac.total_assets = aac.zero_value_assets
+AND utxos.lease_owner IS NULL;
+
 -- name: AnchorPendingAssets :exec
 WITH assets_to_update AS (
     SELECT script_key_id

tapdb/sqlc/querier.go

@@ -1446,6 +1446,7 @@ func (p *ChainPorter) stateStep(currentPkg sendPackage) (*sendPackage, error) {
 
 		currentPkg.VirtualPackets = fundSendRes.VPackets
 		currentPkg.InputCommitments = fundSendRes.InputCommitments
+		currentPkg.ZeroValueInputs = fundSendRes.ZeroValueInputs
 
 		currentPkg.SendState = SendStateVirtualSign
 
@@ -1591,9 +1592,10 @@ func (p *ChainPorter) stateStep(currentPkg sendPackage) (*sendPackage, error) {
 
 		anchorTx, err := wallet.AnchorVirtualTransactions(
 			ctx, &AnchorVTxnsParams{
-				FeeRate:        feeRate,
-				ActivePackets:  currentPkg.VirtualPackets,
-				PassivePackets: currentPkg.PassiveAssets,
+				FeeRate:         feeRate,
+				ActivePackets:   currentPkg.VirtualPackets,
+				PassivePackets:  currentPkg.PassiveAssets,
+				ZeroValueInputs: currentPkg.ZeroValueInputs,
 			},
 		)
 		if err != nil {

tapdb/sqlc/queries/assets.sql

@@ -199,4 +199,15 @@ func (s *CoinSelect) selectForAmount(minTotalAmount uint64,
 	return selectedCommitments, nil
 }
 
+// FetchZeroValueAnchorUTXOs fetches all managed UTXOs that contain only
+// zero-value assets (tombstones and burns).
+func (s *CoinSelect) FetchZeroValueAnchorUTXOs(ctx context.Context) (
+	[]ZeroValueInput, error) {
+
+	s.coinLock.Lock()
+	defer s.coinLock.Unlock()
+
+	return s.coinLister.FetchZeroValueAnchorUTXOs(ctx)
+}
+
 var _ CoinSelector = (*CoinSelect)(nil)

tapfreighter/chain_porter.go

@@ -168,6 +168,10 @@ type CoinLister interface {
 
 	// DeleteExpiredLeases deletes all expired leases from the database.
 	DeleteExpiredLeases(ctx context.Context) error
+
+	// FetchZeroValueAnchorUTXOs fetches all managed UTXOs that contain only
+	// zero-value assets (tombstones and burns).
+	FetchZeroValueAnchorUTXOs(ctx context.Context) ([]ZeroValueInput, error)
 }
 
 // MultiCommitmentSelectStrategy is an enum that describes the strategy that
@@ -195,6 +199,25 @@ type CoinSelector interface {
 	// ReleaseCoins releases/unlocks coins that were previously leased and
 	// makes them available for coin selection again.
 	ReleaseCoins(ctx context.Context, utxoOutpoints ...wire.OutPoint) error
+
+	// FetchZeroValueAnchorUTXOs fetches all managed UTXOs that contain only
+	// zero-value assets (tombstones and burns).
+	FetchZeroValueAnchorUTXOs(ctx context.Context) ([]ZeroValueInput, error)
+}
+
+// ZeroValueInput represents a zero-value UTXO that should be swept.
+type ZeroValueInput interface {
+	// GetOutPoint returns the outpoint of the zero-value UTXO.
+	GetOutPoint() wire.OutPoint
+
+	// GetOutputValue returns the satoshi value of the zero-value UTXO.
+	GetOutputValue() btcutil.Amount
+
+	// GetInternalKey returns the internal key descriptor for the zero-value UTXO.
+	GetInternalKey() keychain.KeyDescriptor
+
+	// GetMerkleRoot returns the taproot merkle root for the zero-value UTXO.
+	GetMerkleRoot() []byte
 }
 
 // TransferInput represents the database level input to an asset transfer.

tapfreighter/coin_select.go

@@ -486,6 +486,10 @@ type sendPackage struct {
 	// associated Taproot Asset commitment.
 	InputCommitments tappsbt.InputCommitments
 
+	// ZeroValueInputs is a list of zero-value UTXOs that should be swept
+	// as additional inputs to the transaction.
+	ZeroValueInputs []ZeroValueInput
+
 	// SendManifests is a map of send manifests that need to be sent to the
 	// auth mailbox server to complete an address V2 transfer. It is keyed
 	// by the anchor output index.