wallet: Do not download cfilters before birthday.

JoeGruffins · JoeGruffins · commit 092584c7e68c · 2025-08-22T17:28:20.000+09:00
Especially for spv wallets with a birthday, cfilters for blocks before
the birthday are not used for anything as there can be no transactions
before the wallet existed. Do not download them but check if we need
them whenever doing a rescan from height.
diff --git a/chain/sync.go b/chain/sync.go
@@ -24,6 +24,7 @@ import (
 	"github.com/decred/dcrd/blockchain/stake/v5"
 	"github.com/decred/dcrd/chaincfg/chainhash"
 	"github.com/decred/dcrd/crypto/blake256"
+	"github.com/decred/dcrd/gcs/v4"
 	"github.com/decred/dcrd/mixing/mixpool"
 	"github.com/decred/dcrd/wire"
 	"github.com/jrick/wsrpc/v2"
@@ -228,6 +229,30 @@ func (s *Syncer) getHeaders(ctx context.Context) error {
 		return err
 	}
 
+	birthday, err := s.wallet.BirthState(ctx)
+	if err != nil {
+		return err
+	}
+	// If a birthday is set, it will likely not be found yet. Watch for it
+	// and do not download cfilters before it.
+	var afterBirthday func(h *wire.BlockHeader) bool
+	switch {
+	case birthday == nil:
+		afterBirthday = func(*wire.BlockHeader) bool {
+			return true
+		}
+	case birthday.SetFromTime:
+		afterBirthday = func(h *wire.BlockHeader) bool {
+			return h.Timestamp.After(birthday.Time)
+		}
+	default:
+		// Birthday was set and already found. Can happen if sync was
+		// stopped and started again after the birthday was found.
+		afterBirthday = func(h *wire.BlockHeader) bool {
+			return h.Height >= birthday.Height
+		}
+	}
+
 	startedSynced := s.atomicWalletSynced.Load() == 1
 
 	cnet := s.wallet.ChainParams().Net
@@ -261,15 +286,22 @@ func (s *Syncer) getHeaders(ctx context.Context) error {
 			g.Go(func() error {
 				header := headers[i]
 				hash := header.BlockHash()
-				filter, proofIndex, proof, err := s.rpc.CFilterV2(ctx, &hash)
-				if err != nil {
-					return err
-				}
-
-				err = validate.CFilterV2HeaderCommitment(cnet, header,
-					filter, proofIndex, proof)
-				if err != nil {
-					return err
+				var filter *gcs.FilterV2
+				if afterBirthday(header) {
+					var (
+						proofIndex uint32
+						proof      []chainhash.Hash
+					)
+					filter, proofIndex, proof, err = s.rpc.CFilterV2(ctx, &hash)
+					if err != nil {
+						return err
+					}
+
+					err = validate.CFilterV2HeaderCommitment(cnet, header,
+						filter, proofIndex, proof)
+					if err != nil {
+						return err
+					}
 				}
 
 				nodes[i] = wallet.NewBlockNode(header, &hash, filter)
diff --git a/rpc/documentation/api.md b/rpc/documentation/api.md
@@ -1109,6 +1109,8 @@ ___
 The `ImportPrivateKey` method imports a private key in Wallet Import Format
 (WIF) encoding to a wallet account.  A rescan may optionally be started to
 search for transactions involving the private key's associated payment address.
+If the private key deals with transactions before the wallet birthday, if set,
+a rescan must be performed to download missing cfilters.
 
 **Request:** `ImportPrivateKeyRequest`
 
@@ -1144,7 +1146,9 @@ ___
 
 The `ImportScript` method imports a script into the wallet.  A rescan may
 optionally be started to search for transactions involving the script, either
-as an output or in a P2SH input.
+as an output or in a P2SH input. If the script deals with transactions before
+the wallet birthday, if set, a rescan must be performed to download missing
+cfilters.
 
 **Request:** `ImportScriptRequest`
 
@@ -1190,7 +1194,9 @@ seed for a hierarchical deterministic private key that is imported into the
 wallet with the supplied name and locked with the supplied password. Addresses
 derived from this account MUST NOT be sent any funds. They are solely for the
 use of creating stake submission scripts. A rescan may optionally be started to
-search for tickets using submission scripts derived from this account.
+search for tickets using submission scripts derived from this account. If tickets
+would exist before the wallet birthday, if set, a rescan must be performed to
+download missing cfilters.
 
 **Request:** `ImportVotingAccountFromSeedRequest`
 
@@ -2689,7 +2695,10 @@ or account must be unlocked.
 #### `BirthBlock`
 
 The `BirthBlock` method returns the wallets birthday block if set. Rescans
-should generally be started from after this block.
+should generally be started from after this block. If a birthday is set cfilters
+from before the birthday may not be downloaded. A rescan from height will move
+the birthday to the rescan height and download all missing cfilters from that
+height.
 
 **Request:** `BirthBlockRequest`
 
diff --git a/spv/sync.go b/spv/sync.go
@@ -1660,6 +1660,30 @@ func (s *Syncer) initialSyncHeaders(ctx context.Context) error {
 		return res
 	}
 
+	birthday, err := s.wallet.BirthState(ctx)
+	if err != nil {
+		return err
+	}
+	// If a birthday is set, it will likely not be found yet. Watch for it
+	// and do not download cfilters before it.
+	var afterBirthday func(h *wire.BlockHeader) bool
+	switch {
+	case birthday == nil:
+		afterBirthday = func(*wire.BlockHeader) bool {
+			return true
+		}
+	case birthday.SetFromTime:
+		afterBirthday = func(h *wire.BlockHeader) bool {
+			return h.Timestamp.After(birthday.Time)
+		}
+	default:
+		// Birthday was set and already found. Can happen if sync was
+		// stopped and started again after the birthday was found.
+		afterBirthday = func(h *wire.BlockHeader) bool {
+			return h.Height >= birthday.Height
+		}
+	}
+
 	// Stage 1: fetch headers.
 	headersChan := make(chan *headersBatch)
 	g.Go(func() error {
@@ -1735,6 +1759,9 @@ func (s *Syncer) initialSyncHeaders(ctx context.Context) error {
 			s.sidechainMu.Lock()
 			var missingCfilter []*wallet.BlockNode
 			for i := range batch.bestChain {
+				if !afterBirthday(batch.bestChain[i].Header) {
+					continue
+				}
 				if batch.bestChain[i].FilterV2 == nil {
 					missingCfilter = batch.bestChain[i:]
 					break
diff --git a/wallet/rescan.go b/wallet/rescan.go
@@ -386,8 +386,36 @@ func (w *Wallet) Rescan(ctx context.Context, n NetworkBackend, startHash *chainh
 func (w *Wallet) RescanFromHeight(ctx context.Context, n NetworkBackend, startHeight int32) error {
 	const op errors.Op = "wallet.RescanFromHeight"
 
+	bs, err := w.BirthState(ctx)
+	if err != nil {
+		return errors.E(op, err)
+	}
+	if bs != nil {
+		// If our birthday is before the rescan height, we may
+		// not have the cfilters needed. Set birthday to the rescan
+		// height and download the filters. This may take some time
+		// depending on network conditions and amount of filters missing.
+		if int32(bs.Height) > startHeight {
+			bs := &udb.BirthdayState{
+				SetFromHeight: true,
+				Height:        uint32(startHeight),
+			}
+			if err := w.SetBirthStateAndScan(ctx, bs); err != nil {
+				return errors.E(op, err)
+			}
+			if err := walletdb.Update(ctx, w.db, func(dbtx walletdb.ReadWriteTx) error {
+				return w.txStore.SetMissingMainChainCFilters(dbtx, true)
+			}); err != nil {
+				return errors.E(op, err)
+			}
+			if err := w.FetchMissingCFilters(ctx, n); err != nil {
+				return errors.E(op, err)
+			}
+		}
+	}
+
 	var startHash chainhash.Hash
-	err := walletdb.View(ctx, w.db, func(tx walletdb.ReadTx) error {
+	err = walletdb.View(ctx, w.db, func(tx walletdb.ReadTx) error {
 		txmgrNs := tx.ReadBucket(wtxmgrNamespaceKey)
 		var err error
 		startHash, err = w.txStore.GetMainChainBlockHashForHeight(
diff --git a/wallet/udb/txmined.go b/wallet/udb/txmined.go
@@ -266,9 +266,12 @@ func (s *Store) ExtendMainChain(ns walletdb.ReadWriteBucket, header *wire.BlockH
 		return err
 	}
 
-	// Save the compact filter.
-	bcf2Key := blockcf2.Key(&header.MerkleRoot)
-	return putRawCFilter(ns, blockHash[:], valueRawCFilter2(bcf2Key, f.Bytes()))
+	if f != nil {
+		// Save the compact filter.
+		bcf2Key := blockcf2.Key(&header.MerkleRoot)
+		return putRawCFilter(ns, blockHash[:], valueRawCFilter2(bcf2Key, f.Bytes()))
+	}
+	return nil
 }
 
 // ProcessedTxsBlockMarker returns the hash of the block which records the last
@@ -402,14 +405,29 @@ func (s *Store) IsMissingMainChainCFilters(dbtx walletdb.ReadTx) bool {
 	return len(v) != 1 || v[0] == 0
 }
 
+// SetMissingMainChainCFilters sets whether we have all of the main chain
+// cfilters. Should be used to set missing to false if the wallet birthday is
+// moved back in time.
+func (s *Store) SetMissingMainChainCFilters(dbtx walletdb.ReadWriteTx, have bool) error {
+	haveB := []byte{0}
+	if have {
+		haveB = []byte{1}
+	}
+	err := dbtx.ReadWriteBucket(wtxmgrBucketKey).Put(rootHaveCFilters, haveB)
+	if err != nil {
+		return errors.E(errors.IO, err)
+	}
+	return nil
+}
+
 // MissingCFiltersHeight returns the first main chain block height
 // with a missing cfilter.  Errors with NotExist when all main chain
 // blocks record cfilters.
-func (s *Store) MissingCFiltersHeight(dbtx walletdb.ReadTx) (int32, error) {
+func MissingCFiltersHeight(dbtx walletdb.ReadTx, fromHeight int32) (int32, error) {
 	ns := dbtx.ReadBucket(wtxmgrBucketKey)
 	c := ns.NestedReadBucket(bucketBlocks).ReadCursor()
 	defer c.Close()
-	for k, v := c.First(); k != nil; k, v = c.Next() {
+	for k, v := c.Seek(keyBlockRecord(fromHeight)); k != nil; k, v = c.Next() {
 		hash := extractRawBlockRecordHash(v)
 		_, _, err := fetchRawCFilter2(ns, hash)
 		if errors.Is(err, errors.NotExist) {
diff --git a/wallet/udb/txmined_test.go b/wallet/udb/txmined_test.go
@@ -12,6 +12,8 @@ import (
 	"decred.org/dcrwallet/v5/wallet/walletdb"
 	"github.com/decred/dcrd/chaincfg/chainhash"
 	"github.com/decred/dcrd/crypto/rand"
+	"github.com/decred/dcrd/dcrutil/v4"
+	gcs2 "github.com/decred/dcrd/gcs/v4"
 )
 
 func randomBytes(len int) []byte {
@@ -79,3 +81,108 @@ func TestSetBirthState(t *testing.T) {
 		})
 	}
 }
+
+func TestMissingCFiltersHeight(t *testing.T) {
+	ctx := context.Background()
+	db, _, s, teardown, err := cloneDB(ctx, "mgr_watching_only.kv")
+	defer teardown()
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	g := makeBlockGenerator()
+	b1H := g.generate(dcrutil.BlockValid)
+	b2H := g.generate(dcrutil.BlockValid)
+	b3H := g.generate(dcrutil.BlockValid)
+	b4H := g.generate(dcrutil.BlockValid)
+	b5H := g.generate(dcrutil.BlockValid)
+	headerData := makeHeaderDataSlice(b1H, b2H, b3H, b4H, b5H)
+	// 3 with filters including genesis then two without and last one with.
+	filters := emptyFilters(2)
+	filters = append(filters, make([]*gcs2.FilterV2, 2)...)
+	filters = append(filters, emptyFilters(1)...)
+
+	err = walletdb.Update(ctx, db, func(dbtx walletdb.ReadWriteTx) error {
+		err = insertMainChainHeaders(s, dbtx, headerData, filters)
+		if err != nil {
+			return err
+		}
+		return nil
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	tests := []struct {
+		name            string
+		missingNo, from int32
+		wantErr         bool
+		do              func()
+	}{{
+		name:      "ok from 0",
+		missingNo: 3,
+	}, {
+		name:      "ok from mid",
+		from:      4,
+		missingNo: 4,
+	}, {
+		name: "ok from 1 after adding",
+		from: 1,
+		do: func() {
+			if err := walletdb.Update(ctx, db, func(dbtx walletdb.ReadWriteTx) error {
+				ns := dbtx.ReadWriteBucket(wtxmgrBucketKey)
+				b3Hash := b3H.BlockHash()
+				err := putRawCFilter(ns, b3Hash[:], nil)
+				if err != nil {
+					return err
+				}
+				return nil
+			}); err != nil {
+				t.Fatal(err)
+			}
+		},
+		missingNo: 4,
+	}, {
+		name: "error once all filters full",
+		do: func() {
+			if err := walletdb.Update(ctx, db, func(dbtx walletdb.ReadWriteTx) error {
+				ns := dbtx.ReadWriteBucket(wtxmgrBucketKey)
+				b4Hash := b4H.BlockHash()
+				err := putRawCFilter(ns, b4Hash[:], nil)
+				if err != nil {
+					return err
+				}
+				return nil
+			}); err != nil {
+				t.Fatal(err)
+			}
+		},
+		wantErr: true,
+	}}
+
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			var missingNo int32
+			if test.do != nil {
+				test.do()
+			}
+			err = walletdb.Update(ctx, db, func(dbtx walletdb.ReadWriteTx) error {
+				var err error
+				missingNo, err = MissingCFiltersHeight(dbtx, test.from)
+				return err
+			})
+			if test.wantErr {
+				if err == nil {
+					t.Fatal("wanted error but got none")
+				}
+				return
+			}
+			if err != nil {
+				t.Fatal(err)
+			}
+			if missingNo != test.missingNo {
+				t.Fatalf("wanted missing number %v but got %v", test.missingNo, missingNo)
+			}
+		})
+	}
+}
diff --git a/wallet/wallet.go b/wallet/wallet.go
@@ -1300,9 +1300,14 @@ func (w *Wallet) fetchMissingCFilters(ctx context.Context, n NetworkBackend, pro
 
 	err := walletdb.View(ctx, w.db, func(dbtx walletdb.ReadTx) error {
 		var err error
+		var fromHeight int32
+		birthday := udb.BirthState(dbtx)
+		if birthday != nil {
+			fromHeight = int32(birthday.Height)
+		}
 		missing = w.txStore.IsMissingMainChainCFilters(dbtx)
 		if missing {
-			height, err = w.txStore.MissingCFiltersHeight(dbtx)
+			height, err = udb.MissingCFiltersHeight(dbtx, fromHeight)
 		}
 		return err
 	})
@@ -1339,8 +1344,16 @@ func (w *Wallet) fetchMissingCFilters(ctx context.Context, n NetworkBackend, pro
 			}
 			_, _, err = w.txStore.CFilterV2(dbtx, &hash)
 			if err == nil {
-				height += span
-				cont = true
+				// If there is a gap for some reason, continue from the end of the gap.
+				height += 1
+				missingHeight, err := udb.MissingCFiltersHeight(dbtx, height)
+				if err != nil {
+					return err
+				}
+				if height != missingHeight {
+					height = missingHeight
+					cont = true
+				}
 				return nil
 			}
 			storage = storage[:cap(storage)]
diff --git a/wallet/wallet_test.go b/wallet/wallet_test.go
