fix(cbf): widen stop-gap to 200 on fresh-wallet recovery

Without a wider initial window, a fresh-wallet recovery only scans scripts
at indices 0..20 and silently misses any funds past the lookahead. A
follow-up sync can't rescue them either, because BDK's checkpoint advances
past the funding block after the first pass and `skip_height` excludes it
from every subsequent scan.

Author: febyeji

src/chain/cbf.rs

@@ -55,6 +55,13 @@ const MAX_RESTART_RETRIES: u32 = 5;
 /// Initial backoff delay for restart retries (doubles each attempt).
 const INITIAL_BACKOFF_MS: u64 = 500;
 
+/// Stop-gap window size used when syncing a *fresh* on-chain wallet (one whose
+/// reveal cursor is still `None` on both keychains). Bigger than the steady-state
+/// `BDK_CLIENT_STOP_GAP` because the reveal cursor can't advance across a gap
+/// wider than the initial scan window in a single sync, so fresh recoveries need
+/// a wider cushion up-front. Subsequent syncs fall back to `BDK_CLIENT_STOP_GAP`.
+const FRESH_RECOVERY_STOP_GAP: usize = 200;
+
 /// The fee estimation back-end used by the CBF chain source.
 enum FeeSource {
 	/// Derive fee rates from the coinbase reward of recent blocks.
@@ -587,8 +594,17 @@ impl CbfChainSource {
 		let res = async {
 			let requester = self.requester()?;
 
-			let (scripts, spk_to_keychain_idx) =
-				onchain_wallet.get_spks_for_cbf_sync(BDK_CLIENT_STOP_GAP);
+			// On a fresh wallet (reveal cursor still `None` on every keychain) we
+			// widen the scan window to `FRESH_RECOVERY_STOP_GAP` so a single sync
+			// can recover funds across deeper derivation gaps. Once the wallet has
+			// any revealed activity we drop back to the steady-state stop-gap.
+			let stop_gap = if onchain_wallet.is_fresh_for_cbf_sync() {
+				FRESH_RECOVERY_STOP_GAP
+			} else {
+				BDK_CLIENT_STOP_GAP
+			};
+
+			let (scripts, spk_to_keychain_idx) = onchain_wallet.get_spks_for_cbf_sync(stop_gap);
 			if scripts.is_empty() {
 				log_debug!(self.logger, "No wallet scripts to sync via CBF.");
 			} else {

src/wallet/mod.rs

@@ -131,7 +131,10 @@ impl Wallet {
 	/// last revealed index. This mirrors BDK's internal `KeychainTxOutIndex` lookahead so
 	/// CBF also scans for funds that land at indices just past the current reveal cursor
 	/// (fresh recovery, gap deposits, etc.). On a completely fresh wallet `last_revealed` is
-	/// `None`, so the window is simply `0..stop_gap`.
+	/// `None`, so the window is simply `0..stop_gap`. Callers should pass a wider
+	/// `stop_gap` (see [`Self::is_fresh_for_cbf_sync`]) when they need a single sync to
+	/// recover funds that may sit past the steady-state lookahead, since BDK's reveal
+	/// cursor cannot advance further than the scan window in a single pass.
 	///
 	/// The accompanying map lets callers translate a matched output script back to
 	/// `(keychain, index)` so they can populate `Update.last_active_indices` and advance
@@ -155,6 +158,15 @@ impl Wallet {
 		(scripts, spk_to_keychain_idx)
 	}
 
+	/// Returns `true` when the on-chain wallet has not yet revealed any address on
+	/// either keychain, i.e. when a CBF sync should treat this as a fresh recovery
+	/// and use a wider initial scan window.
+	pub(crate) fn is_fresh_for_cbf_sync(&self) -> bool {
+		let wallet = self.inner.lock().unwrap();
+		wallet.spk_index().last_revealed_index(KeychainKind::External).is_none()
+			&& wallet.spk_index().last_revealed_index(KeychainKind::Internal).is_none()
+	}
+
 	pub(crate) fn latest_checkpoint(&self) -> bdk_chain::CheckPoint {
 		self.inner.lock().unwrap().latest_checkpoint()
 	}

tests/integration_tests_rust.rs

@@ -3197,6 +3197,66 @@ async fn onchain_wallet_recovery_cbf_advances_reveal_cursor() {
 	recovered_node.stop().unwrap();
 }
 
+/// Regression test: a fresh CBF recovery must discover funds at derivation
+/// indices past the steady-state `BDK_CLIENT_STOP_GAP` (20). Without a wider
+/// initial window on fresh wallets, the first sync only covers `0..20` and
+/// `last_revealed` stays `None`, so the window never expands and the deeper
+/// funds are silently lost.
+#[tokio::test(flavor = "multi_thread", worker_threads = 1)]
+async fn onchain_wallet_recovery_cbf_deep_stop_gap() {
+	let (bitcoind, electrsd) = setup_bitcoind_and_electrsd();
+	let chain_source = TestChainSource::Cbf(&bitcoind);
+
+	let original_config = random_config(true);
+	let original_node_entropy = original_config.node_entropy.clone();
+	let original_node = setup_node(&chain_source, original_config);
+
+	// Reveal 30 addresses and fund only the one at idx 25. Index 25 sits past
+	// the steady-state stop-gap (20) but well within the fresh-recovery window
+	// (200), so a fresh recovery only finds it when the fix is in place.
+	let mut addrs = Vec::with_capacity(30);
+	for _ in 0..30 {
+		addrs.push(original_node.onchain_payment().new_address().unwrap());
+	}
+	let funded = addrs[25].clone();
+
+	let premine_amount_sat = 100_000;
+	premine_and_distribute_funds(
+		&bitcoind.client,
+		&electrsd.client,
+		vec![funded],
+		Amount::from_sat(premine_amount_sat),
+	)
+	.await;
+
+	wait_for_cbf_sync(&original_node, || {
+		original_node.list_balances().spendable_onchain_balance_sats == premine_amount_sat
+	})
+	.await;
+	assert_eq!(original_node.list_balances().spendable_onchain_balance_sats, premine_amount_sat);
+
+	original_node.stop().unwrap();
+	drop(original_node);
+
+	// Recover from a completely fresh wallet state, same seed.
+	let mut recovered_config = random_config(true);
+	recovered_config.node_entropy = original_node_entropy;
+	recovered_config.recovery_mode = true;
+	let recovered_node = setup_node(&chain_source, recovered_config);
+
+	wait_for_cbf_sync(&recovered_node, || {
+		recovered_node.list_balances().spendable_onchain_balance_sats == premine_amount_sat
+	})
+	.await;
+	assert_eq!(
+		recovered_node.list_balances().spendable_onchain_balance_sats,
+		premine_amount_sat,
+		"recovery did not find funds beyond the initial CBF stop-gap window"
+	);
+
+	recovered_node.stop().unwrap();
+}
+
 #[tokio::test(flavor = "multi_thread", worker_threads = 1)]
 async fn onchain_send_receive_cbf() {
 	let (bitcoind, electrsd) = setup_bitcoind_and_electrsd();