fix: Add spend verification fallback to rescan

Author: m0wer

CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Fixed
+
+- **Spent UTXO detection in bulk endpoint**: `POST /v1/utxos` could return already-spent UTXOs because the batch `MatchAny` filter scan missed spending blocks in certain cases. Added a per-UTXO spend verification pass after the main scan that uses single-script `filter.Match` (the same approach used by the reliable `GET /v1/utxo/{txid}/{vout}` endpoint) to catch any spends missed by the batch scan.
+
 ## [0.9.0] - 2026-03-19
 
 ### Added

neutrino_server/internal/neutrino/rescan.go

@@ -16,6 +16,7 @@ import (
 	"github.com/btcsuite/btcd/btcutil"
 	"github.com/btcsuite/btcd/btcutil/gcs/builder"
 	"github.com/btcsuite/btcd/chaincfg"
+	"github.com/btcsuite/btcd/chaincfg/chainhash"
 	"github.com/btcsuite/btcd/txscript"
 	"github.com/btcsuite/btcd/wire"
 	"github.com/btcsuite/btclog"
@@ -501,11 +502,10 @@ func (r *RescanManager) scanBlocks(startHeight, endHeight int32, addrs []btcutil
 
 	elapsed := time.Since(scanStart)
 
-	// Update UTXO set
+	// Update UTXO set (preliminary — before spend verification).
 	r.mu.Lock()
-	defer r.mu.Unlock()
 
-	// Add new UTXOs (if not spent)
+	// Add new UTXOs (if not spent in this scan batch).
 	added := 0
 	for utxoKey, utxo := range foundUTXOs {
 		if !spentOutputs[utxoKey] {
@@ -514,7 +514,7 @@ func (r *RescanManager) scanBlocks(startHeight, endHeight int32, addrs []btcutil
 		}
 	}
 
-	// Remove spent UTXOs
+	// Remove spent UTXOs detected by the batch filter scan.
 	removed := 0
 	for utxoKey := range spentOutputs {
 		if _, existed := r.utxoSet[utxoKey]; existed {
@@ -523,16 +523,145 @@ func (r *RescanManager) scanBlocks(startHeight, endHeight int32, addrs []btcutil
 		}
 	}
 
+	// Snapshot the current UTXO set for the spend verification pass.
+	// We need to release the lock before doing network I/O.
+	utxoSnapshot := make(map[string]UTXO, len(r.utxoSet))
+	for k, v := range r.utxoSet {
+		utxoSnapshot[k] = v
+	}
+	r.mu.Unlock()
+
 	blocksPerSec := float64(0)
 	if elapsed.Seconds() > 0 {
 		blocksPerSec = float64(blocksScanned) / elapsed.Seconds()
 	}
 	r.logger.Infof("Scan complete: %d blocks in %s (%.1f blocks/sec) | %d filter matches | %d UTXOs found, %d added, %d spent removed | total UTXO set: %d",
 		blocksScanned, elapsed.Round(time.Millisecond), blocksPerSec,
 		filterMatches, len(foundUTXOs), added, removed, len(r.utxoSet))
+
+	// Phase 3: Spend verification pass.
+	// The batch MatchAny filter scan can miss spends in certain cases (e.g.
+	// subtle differences in multi-script vs single-script filter matching).
+	// Verify each UTXO individually using per-script filter.Match, the same
+	// approach used by GetUTXO which is known to be reliable.
+	verifiedSpent := r.verifyUTXOsUnspent(utxoSnapshot, startHeight, endHeight)
+	if verifiedSpent > 0 {
+		r.logger.Infof("Spend verification removed %d additional spent UTXOs", verifiedSpent)
+	}
+
 	return nil
 }
 
+// verifyUTXOsUnspent performs a per-UTXO spend check for all UTXOs in the
+// snapshot. For each UTXO, it scans block filters from the UTXO's creation
+// height to endHeight using single-script filter.Match (not MatchAny). Any
+// block that matches is downloaded and checked for transactions spending the
+// UTXO. Confirmed spends are removed from r.utxoSet.
+//
+// This is a defense-in-depth measure: the main batch scan (MatchAny) should
+// catch most spends, but this pass ensures none are missed.
+func (r *RescanManager) verifyUTXOsUnspent(
+	snapshot map[string]UTXO, scanStart, scanEnd int32,
+) int {
+	if len(snapshot) == 0 {
+		return 0
+	}
+
+	r.logger.Infof("Spend verification: checking %d UTXOs for spends in range %d..%d",
+		len(snapshot), scanStart, scanEnd)
+	verifyStart := time.Now()
+	removed := 0
+
+	for utxoKey, utxo := range snapshot {
+		// Only verify UTXOs that could have been spent in the scanned range.
+		// A UTXO created after scanEnd cannot be spent in this range.
+		// Start checking from the block AFTER the UTXO was created.
+		checkFrom := utxo.Height + 1
+		if checkFrom < scanStart {
+			checkFrom = scanStart
+		}
+		if checkFrom > scanEnd {
+			continue
+		}
+
+		// Build the pkScript for this UTXO's address.
+		addr, err := btcutil.DecodeAddress(utxo.Address, r.chainParams)
+		if err != nil {
+			r.logger.Debugf("Spend verify: skip %s, bad address %s: %v",
+				utxoKey, utxo.Address, err)
+			continue
+		}
+		pkScript, err := txscript.PayToAddrScript(addr)
+		if err != nil {
+			r.logger.Debugf("Spend verify: skip %s, script error: %v",
+				utxoKey, err)
+			continue
+		}
+
+		// Parse the UTXO txid for outpoint comparison.
+		targetHash, err := chainhash.NewHashFromStr(utxo.TxID)
+		if err != nil {
+			r.logger.Debugf("Spend verify: skip %s, bad txid: %v",
+				utxoKey, err)
+			continue
+		}
+
+		spent := false
+		for height := checkFrom; height <= scanEnd && !spent; height++ {
+			blockHash, err := r.chainService.GetBlockHash(int64(height))
+			if err != nil {
+				continue
+			}
+
+			filter, err := r.chainService.GetCFilter(*blockHash, wire.GCSFilterRegular)
+			if err != nil || filter == nil {
+				continue
+			}
+
+			key := builder.DeriveKey(blockHash)
+			matched, err := filter.Match(key, pkScript)
+			if err != nil || !matched {
+				continue
+			}
+
+			// Filter matched for this single script — fetch full block.
+			block, err := r.chainService.GetBlock(*blockHash)
+			if err != nil {
+				r.logger.Debugf("Spend verify: failed to get block %d: %v", height, err)
+				continue
+			}
+
+			for _, tx := range block.Transactions() {
+				for _, txIn := range tx.MsgTx().TxIn {
+					prevOut := txIn.PreviousOutPoint
+					if prevOut.Hash.IsEqual(targetHash) && prevOut.Index == utxo.Vout {
+						spent = true
+						r.logger.Infof("Spend verify: %s spent at height %d in tx %s",
+							utxoKey, height, tx.Hash().String())
+						break
+					}
+				}
+				if spent {
+					break
+				}
+			}
+		}
+
+		if spent {
+			r.mu.Lock()
+			if _, exists := r.utxoSet[utxoKey]; exists {
+				delete(r.utxoSet, utxoKey)
+				removed++
+			}
+			r.mu.Unlock()
+		}
+	}
+
+	r.logger.Infof("Spend verification complete: checked %d UTXOs in %s, removed %d spent",
+		len(snapshot), time.Since(verifyStart).Round(time.Millisecond), removed)
+	return removed
+}
+
 // AddUTXO adds a UTXO to the set (for use by notification handlers).
 func (r *RescanManager) AddUTXO(txHash string, vout uint32, value int64, addrStr string, scriptPubKey []byte, height int32) {
 	r.mu.Lock()

neutrino_server/internal/neutrino/rescan_test.go

@@ -576,3 +576,58 @@ func TestRescanIncrementalSkip(t *testing.T) {
 		t.Errorf("expected LastStartHeight=243542, got %d", mgr.status.LastStartHeight)
 	}
 }
+
+// TestVerifyUTXOsUnspentEmptySnapshot tests that verifyUTXOsUnspent returns 0
+// when the snapshot is empty.
+func TestVerifyUTXOsUnspentEmptySnapshot(t *testing.T) {
+	backend := btclog.NewBackend(os.Stdout)
+	logger := backend.Logger("TEST")
+
+	mgr := &RescanManager{
+		chainParams:  &chaincfg.MainNetParams,
+		logger:       logger,
+		watchedAddrs: make(map[string]btcutil.Address),
+		utxoSet:      make(map[string]UTXO),
+	}
+
+	removed := mgr.verifyUTXOsUnspent(nil, 0, 100)
+	if removed != 0 {
+		t.Errorf("expected 0 removed for nil snapshot, got %d", removed)
+	}
+
+	removed = mgr.verifyUTXOsUnspent(map[string]UTXO{}, 0, 100)
+	if removed != 0 {
+		t.Errorf("expected 0 removed for empty snapshot, got %d", removed)
+	}
+}
+
+// TestVerifyUTXOsUnspentSkipsOutOfRange tests that UTXOs created after the scan
+// range are skipped (no chain service calls needed).
+func TestVerifyUTXOsUnspentSkipsOutOfRange(t *testing.T) {
+	backend := btclog.NewBackend(os.Stdout)
+	logger := backend.Logger("TEST")
+
+	mgr := &RescanManager{
+		// nil chainService — if it tries to call it, we'll get a panic,
+		// proving the UTXO was NOT checked.
+		chainParams:  &chaincfg.MainNetParams,
+		logger:       logger,
+		watchedAddrs: make(map[string]btcutil.Address),
+		utxoSet:      make(map[string]UTXO),
+	}
+
+	snapshot := map[string]UTXO{
+		"abc:0": {
+			TxID:    "abc",
+			Vout:    0,
+			Address: "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
+			Height:  200, // created at 200, scanEnd=100 => out of range
+		},
+	}
+
+	// scanEnd < UTXO.Height, so the UTXO can't have been spent in this range.
+	removed := mgr.verifyUTXOsUnspent(snapshot, 0, 100)
+	if removed != 0 {
+		t.Errorf("expected 0 removed for out-of-range UTXO, got %d", removed)
+	}
+}