Add forced wallet full scans

Let Esplora and Electrum sync configs request BDK full scans
until one succeeds. This keeps recovery scans retryable after
transient sync failures while preserving normal incremental syncs
once recovery has completed.

Co-Authored-By: HAL 9000

Author: tnull

CHANGELOG.md

@@ -13,6 +13,9 @@
   wallet on a pruned node where the full history is unavailable but the wallet birthday height is
   known. Existing wallets are not rewound, and future heights fail the build. Passing `Some(0)`
   rescans from genesis; passing `None` keeps the default current-tip checkpoint behavior. (#884)
+- `EsploraSyncConfig` and `ElectrumSyncConfig` now support `force_wallet_full_scan`. When set,
+  the on-chain wallet keeps using BDK `full_scan` instead of incremental sync until a full scan
+  succeeds, allowing restored wallets to rediscover funds sent to previously-unknown addresses.
 
 ## Bug Fixes and Improvements
 - Building a fresh node against a Bitcoin Core RPC or REST chain source that fails to return the

src/chain/electrum.rs

@@ -6,6 +6,7 @@
 // accordance with one or both of these licenses.
 
 use std::collections::HashMap;
+use std::sync::atomic::{AtomicBool, Ordering};
 use std::sync::{Arc, Mutex, RwLock};
 use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
 
@@ -50,6 +51,7 @@ pub(super) struct ElectrumChainSource {
 	config: Arc<Config>,
 	logger: Arc<Logger>,
 	node_metrics: Arc<PersistedNodeMetrics>,
+	force_wallet_full_scan: AtomicBool,
 }
 
 impl ElectrumChainSource {
@@ -61,6 +63,7 @@ impl ElectrumChainSource {
 		let electrum_runtime_status = RwLock::new(ElectrumRuntimeStatus::new());
 		let onchain_wallet_sync_status = Mutex::new(WalletSyncStatus::Completed);
 		let lightning_wallet_sync_status = Mutex::new(WalletSyncStatus::Completed);
+		let force_wallet_full_scan = AtomicBool::new(sync_config.force_wallet_full_scan);
 		Self {
 			server_url,
 			sync_config,
@@ -72,6 +75,7 @@ impl ElectrumChainSource {
 			config,
 			logger: Arc::clone(&logger),
 			node_metrics,
+			force_wallet_full_scan,
 		}
 	}
 
@@ -125,9 +129,11 @@ impl ElectrumChainSource {
 			return Err(Error::FeerateEstimationUpdateFailed);
 		};
 		// If this is our first sync, do a full scan with the configured gap limit.
-		// Otherwise just do an incremental sync.
-		let incremental_sync =
+		// Otherwise just do an incremental sync, unless a forced full scan is still pending.
+		let has_prior_sync =
 			self.node_metrics.read().expect("lock").latest_onchain_wallet_sync_timestamp.is_some();
+		let forced_full_scan = self.force_wallet_full_scan.load(Ordering::Acquire);
+		let incremental_sync = has_prior_sync && !forced_full_scan;
 
 		let cached_txs = onchain_wallet.get_cached_txs();
 
@@ -160,6 +166,9 @@ impl ElectrumChainSource {
 			.await
 		};
 
+		if forced_full_scan && res.is_ok() {
+			self.force_wallet_full_scan.store(false, Ordering::Release);
+		}
 		res
 	}
 

src/chain/esplora.rs

@@ -6,6 +6,7 @@
 // accordance with one or both of these licenses.
 
 use std::collections::HashMap;
+use std::sync::atomic::{AtomicBool, Ordering};
 use std::sync::{Arc, Mutex};
 use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
 
@@ -38,6 +39,7 @@ pub(super) struct EsploraChainSource {
 	config: Arc<Config>,
 	logger: Arc<Logger>,
 	node_metrics: Arc<PersistedNodeMetrics>,
+	force_wallet_full_scan: AtomicBool,
 }
 
 impl EsploraChainSource {
@@ -62,6 +64,7 @@ impl EsploraChainSource {
 
 		let onchain_wallet_sync_status = Mutex::new(WalletSyncStatus::Completed);
 		let lightning_wallet_sync_status = Mutex::new(WalletSyncStatus::Completed);
+		let force_wallet_full_scan = AtomicBool::new(sync_config.force_wallet_full_scan);
 		Ok(Self {
 			sync_config,
 			esplora_client,
@@ -73,6 +76,7 @@ impl EsploraChainSource {
 			config,
 			logger,
 			node_metrics,
+			force_wallet_full_scan,
 		})
 	}
 
@@ -101,9 +105,11 @@ impl EsploraChainSource {
 
 	async fn sync_onchain_wallet_inner(&self, onchain_wallet: Arc<Wallet>) -> Result<(), Error> {
 		// If this is our first sync, do a full scan with the configured gap limit.
-		// Otherwise just do an incremental sync.
-		let incremental_sync =
+		// Otherwise just do an incremental sync, unless a forced full scan is still pending.
+		let has_prior_sync =
 			self.node_metrics.read().expect("lock").latest_onchain_wallet_sync_timestamp.is_some();
+		let forced_full_scan = self.force_wallet_full_scan.load(Ordering::Acquire);
+		let incremental_sync = has_prior_sync && !forced_full_scan;
 
 		macro_rules! get_and_apply_wallet_update {
 			($sync_future: expr) => {{
@@ -177,7 +183,7 @@ impl EsploraChainSource {
 			}}
 		}
 
-		if incremental_sync {
+		let res = if incremental_sync {
 			let sync_request = onchain_wallet.get_incremental_sync_request();
 			let wallet_sync_timeout_fut = tokio::time::timeout(
 				Duration::from_secs(
@@ -199,7 +205,11 @@ impl EsploraChainSource {
 				),
 			);
 			get_and_apply_wallet_update!(wallet_sync_timeout_fut)
+		};
+		if forced_full_scan && res.is_ok() {
+			self.force_wallet_full_scan.store(false, Ordering::Release);
 		}
+		res
 	}
 
 	pub(super) async fn sync_lightning_wallet(

src/config.rs

@@ -506,13 +506,19 @@ pub struct EsploraSyncConfig {
 	pub background_sync_config: Option<BackgroundSyncConfig>,
 	/// Sync timeouts configuration.
 	pub timeouts_config: SyncTimeoutsConfig,
+	/// Whether to force BDK full scans until one succeeds.
+	///
+	/// This can be useful when restoring a wallet from seed on a node that has already synced
+	/// before, but may be missing funds sent to previously-unknown addresses.
+	pub force_wallet_full_scan: bool,
 }
 
 impl Default for EsploraSyncConfig {
 	fn default() -> Self {
 		Self {
 			background_sync_config: Some(BackgroundSyncConfig::default()),
 			timeouts_config: SyncTimeoutsConfig::default(),
+			force_wallet_full_scan: false,
 		}
 	}
 }
@@ -533,13 +539,19 @@ pub struct ElectrumSyncConfig {
 	pub background_sync_config: Option<BackgroundSyncConfig>,
 	/// Sync timeouts configuration.
 	pub timeouts_config: SyncTimeoutsConfig,
+	/// Whether to force BDK full scans until one succeeds.
+	///
+	/// This can be useful when restoring a wallet from seed on a node that has already synced
+	/// before, but may be missing funds sent to previously-unknown addresses.
+	pub force_wallet_full_scan: bool,
 }
 
 impl Default for ElectrumSyncConfig {
 	fn default() -> Self {
 		Self {
 			background_sync_config: Some(BackgroundSyncConfig::default()),
 			timeouts_config: SyncTimeoutsConfig::default(),
+			force_wallet_full_scan: false,
 		}
 	}
 }

tests/common/mod.rs

@@ -436,6 +436,7 @@ pub(crate) struct TestConfig {
 	pub node_entropy: NodeEntropy,
 	pub async_payments_role: Option<AsyncPaymentsRole>,
 	pub wallet_rescan_from_height: Option<u32>,
+	pub force_wallet_full_scan: bool,
 }
 
 impl Default for TestConfig {
@@ -448,13 +449,15 @@ impl Default for TestConfig {
 		let node_entropy = NodeEntropy::from_bip39_mnemonic(mnemonic, None);
 		let async_payments_role = None;
 		let wallet_rescan_from_height = None;
+		let force_wallet_full_scan = false;
 		TestConfig {
 			node_config,
 			log_writer,
 			store_type,
 			node_entropy,
 			async_payments_role,
 			wallet_rescan_from_height,
+			force_wallet_full_scan,
 		}
 	}
 }
@@ -537,12 +540,14 @@ pub(crate) fn setup_node(chain_source: &TestChainSource, config: TestConfig) ->
 			let esplora_url = format!("http://{}", electrsd.esplora_url.as_ref().unwrap());
 			let mut sync_config = EsploraSyncConfig::default();
 			sync_config.background_sync_config = None;
+			sync_config.force_wallet_full_scan = config.force_wallet_full_scan;
 			builder.set_chain_source_esplora(esplora_url.clone(), Some(sync_config));
 		},
 		TestChainSource::Electrum(electrsd) => {
 			let electrum_url = format!("tcp://{}", electrsd.electrum_url);
 			let mut sync_config = ElectrumSyncConfig::default();
 			sync_config.background_sync_config = None;
+			sync_config.force_wallet_full_scan = config.force_wallet_full_scan;
 			builder.set_chain_source_electrum(electrum_url.clone(), Some(sync_config));
 		},
 		TestChainSource::BitcoindRpcSync(bitcoind) => {

tests/integration_tests_rust.rs

@@ -936,6 +936,69 @@ async fn onchain_wallet_recovery() {
 	);
 }
 
+#[tokio::test(flavor = "multi_thread", worker_threads = 1)]
+async fn onchain_wallet_force_full_scan_rediscovers_esplora_funds() {
+	let (bitcoind, electrsd) = setup_bitcoind_and_electrsd();
+	let chain_source = TestChainSource::Esplora(&electrsd);
+
+	premine_blocks(&bitcoind.client, &electrsd.client).await;
+
+	let address_source_config = random_config(true);
+	let node_entropy = address_source_config.node_entropy;
+	let address_source_node = setup_node(&chain_source, address_source_config);
+	let addr_1 = address_source_node.onchain_payment().new_address().unwrap();
+	let addr_2 = address_source_node.onchain_payment().new_address().unwrap();
+	address_source_node.stop().unwrap();
+	drop(address_source_node);
+
+	let premine_amount_sat = 100_000;
+	let mut stale_config = random_config(true);
+	stale_config.node_entropy = node_entropy;
+	stale_config.store_type = TestStoreType::Sqlite;
+	let stale_node = setup_node(&chain_source, stale_config.clone());
+	stale_node.sync_wallets().unwrap();
+	assert_eq!(stale_node.list_balances().spendable_onchain_balance_sats, 0);
+	stale_node.stop().unwrap();
+	drop(stale_node);
+
+	let txid_1 = bitcoind
+		.client
+		.send_to_address(&addr_1, Amount::from_sat(premine_amount_sat))
+		.unwrap()
+		.0
+		.parse()
+		.unwrap();
+	wait_for_tx(&electrsd.client, txid_1).await;
+	let txid_2 = bitcoind
+		.client
+		.send_to_address(&addr_2, Amount::from_sat(premine_amount_sat))
+		.unwrap()
+		.0
+		.parse()
+		.unwrap();
+	wait_for_tx(&electrsd.client, txid_2).await;
+	generate_blocks_and_wait(&bitcoind.client, &electrsd.client, 1).await;
+
+	let normal_node = setup_node(&chain_source, stale_config.clone());
+	normal_node.sync_wallets().unwrap();
+	assert_eq!(
+		normal_node.list_balances().spendable_onchain_balance_sats,
+		0,
+		"normal incremental sync should not rediscover previously-unknown addresses"
+	);
+	normal_node.stop().unwrap();
+	drop(normal_node);
+
+	stale_config.force_wallet_full_scan = true;
+	let recovered_node = setup_node(&chain_source, stale_config);
+	recovered_node.sync_wallets().unwrap();
+	assert_eq!(
+		recovered_node.list_balances().spendable_onchain_balance_sats,
+		premine_amount_sat * 2,
+		"forced full scan should rediscover funds sent to previously-unknown addresses"
+	);
+}
+
 #[tokio::test(flavor = "multi_thread", worker_threads = 1)]
 async fn onchain_wallet_recovery_rescans_from_birthday_height() {
 	// End-to-end test for `wallet_rescan_from_height` against a bitcoind chain source. The