Configure Electrum full-scan stop gap

Expose the bounded BDK full-scan stop gap for Electrum so
restore behavior can be tuned consistently across remote backends.

Document that the setting applies only to BDK full_scan calls and
keeps incremental sync unaffected.

Co-Authored-By: HAL 9000

Author: tnull

src/chain/electrum.rs

@@ -25,14 +25,17 @@ use lightning::util::ser::Writeable;
 use lightning_transaction_sync::ElectrumSyncClient;
 
 use super::WalletSyncStatus;
-use crate::config::{Config, ElectrumSyncConfig, BDK_CLIENT_STOP_GAP};
+use crate::config::{
+	clamp_full_scan_stop_gap, Config, ElectrumSyncConfig, MAX_FULL_SCAN_STOP_GAP,
+	MIN_FULL_SCAN_STOP_GAP,
+};
 use crate::error::Error;
 use crate::fee_estimator::{
 	apply_post_estimation_adjustments, get_all_conf_targets, get_num_block_defaults_for_target,
 	ConfirmationTarget, OnchainFeeEstimator,
 };
 use crate::io::utils::update_and_persist_node_metrics;
-use crate::logger::{log_bytes, log_debug, log_error, log_trace, LdkLogger, Logger};
+use crate::logger::{log_bytes, log_debug, log_error, log_trace, log_warn, LdkLogger, Logger};
 use crate::runtime::Runtime;
 use crate::types::{ChainMonitor, ChannelManager, DynStore, Sweeper, Wallet};
 use crate::PersistedNodeMetrics;
@@ -496,11 +499,12 @@ impl ElectrumRuntimeClient {
 	) -> Result<BdkFullScanResponse<BdkKeyChainKind>, Error> {
 		let bdk_electrum_client = Arc::clone(&self.bdk_electrum_client);
 		bdk_electrum_client.populate_tx_cache(cached_txs);
+		let full_scan_stop_gap = self.bounded_full_scan_stop_gap();
 
 		let spawn_fut = self.runtime.spawn_blocking(move || {
 			bdk_electrum_client.full_scan(
 				request,
-				BDK_CLIENT_STOP_GAP,
+				full_scan_stop_gap,
 				BDK_ELECTRUM_CLIENT_BATCH_SIZE,
 				true,
 			)
@@ -526,6 +530,22 @@ impl ElectrumRuntimeClient {
 			})
 	}
 
+	fn bounded_full_scan_stop_gap(&self) -> usize {
+		let configured = self.sync_config.full_scan_stop_gap;
+		let bounded = clamp_full_scan_stop_gap(configured);
+		if bounded != configured {
+			log_warn!(
+				self.logger,
+				"Configured Electrum on-chain wallet full-scan stop gap {} is outside the allowed range {}..={}; using {}.",
+				configured,
+				MIN_FULL_SCAN_STOP_GAP,
+				MAX_FULL_SCAN_STOP_GAP,
+				bounded
+			);
+		}
+		bounded as usize
+	}
+
 	async fn get_incremental_sync_wallet_update(
 		&self, request: BdkSyncRequest<(BdkKeyChainKind, u32)>,
 		cached_txs: impl IntoIterator<Item = impl Into<Arc<Transaction>>>,

src/config.rs

@@ -72,9 +72,6 @@ pub const MIN_FULL_SCAN_STOP_GAP: u32 = 1;
 /// Values above 1000 are clamped to 1000 when a full scan runs.
 pub const MAX_FULL_SCAN_STOP_GAP: u32 = 1000;
 
-// The fixed stop gap used by backends that don't yet expose a configurable value.
-pub(crate) const BDK_CLIENT_STOP_GAP: usize = DEFAULT_FULL_SCAN_STOP_GAP as usize;
-
 // The number of concurrent requests made against the API provider.
 pub(crate) const BDK_CLIENT_CONCURRENCY: usize = 4;
 
@@ -571,6 +568,23 @@ pub struct ElectrumSyncConfig {
 	pub background_sync_config: Option<BackgroundSyncConfig>,
 	/// Sync timeouts configuration.
 	pub timeouts_config: SyncTimeoutsConfig,
+	/// The stop gap used for BDK full scans of the on-chain wallet.
+	///
+	/// A full scan for each keychain stops after this many consecutive script pubkeys
+	/// with no associated transactions. This value is only used for BDK `full_scan`
+	/// calls, which ldk-node performs on the first on-chain wallet sync or when
+	/// [`Self::force_wallet_full_scan`] is set. Incremental BDK `sync` calls do not use it.
+	///
+	/// **Default:** 20 ([`DEFAULT_FULL_SCAN_STOP_GAP`])
+	///
+	/// **Allowed values:** 1 ([`MIN_FULL_SCAN_STOP_GAP`]) to 1000
+	/// ([`MAX_FULL_SCAN_STOP_GAP`]), inclusive. Values outside this range will be clamped to the
+	/// nearest bound and a warning will be logged when the full scan runs.
+	///
+	/// **Note:** Large values can cause many Electrum requests, hit server rate limits,
+	/// take a long time to complete, or cause syncs to fail with
+	/// [`SyncTimeoutsConfig::onchain_wallet_sync_timeout_secs`].
+	pub full_scan_stop_gap: u32,
 	/// 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
@@ -583,6 +597,7 @@ impl Default for ElectrumSyncConfig {
 		Self {
 			background_sync_config: Some(BackgroundSyncConfig::default()),
 			timeouts_config: SyncTimeoutsConfig::default(),
+			full_scan_stop_gap: DEFAULT_FULL_SCAN_STOP_GAP,
 			force_wallet_full_scan: false,
 		}
 	}
@@ -748,9 +763,9 @@ mod tests {
 	use std::str::FromStr;
 
 	use super::{
-		clamp_full_scan_stop_gap, may_announce_channel, AnnounceError, Config, EsploraSyncConfig,
-		NodeAlias, SocketAddress, DEFAULT_FULL_SCAN_STOP_GAP, MAX_FULL_SCAN_STOP_GAP,
-		MIN_FULL_SCAN_STOP_GAP,
+		clamp_full_scan_stop_gap, may_announce_channel, AnnounceError, Config, ElectrumSyncConfig,
+		EsploraSyncConfig, NodeAlias, SocketAddress, DEFAULT_FULL_SCAN_STOP_GAP,
+		MAX_FULL_SCAN_STOP_GAP, MIN_FULL_SCAN_STOP_GAP,
 	};
 
 	#[test]
@@ -802,6 +817,7 @@ mod tests {
 	#[test]
 	fn full_scan_stop_gap_defaults() {
 		assert_eq!(EsploraSyncConfig::default().full_scan_stop_gap, DEFAULT_FULL_SCAN_STOP_GAP);
+		assert_eq!(ElectrumSyncConfig::default().full_scan_stop_gap, DEFAULT_FULL_SCAN_STOP_GAP);
 	}
 
 	#[test]

tests/common/mod.rs

@@ -554,6 +554,9 @@ pub(crate) fn setup_node(chain_source: &TestChainSource, config: TestConfig) ->
 			let mut sync_config = ElectrumSyncConfig::default();
 			sync_config.background_sync_config = None;
 			sync_config.force_wallet_full_scan = config.force_wallet_full_scan;
+			if let Some(full_scan_stop_gap) = config.full_scan_stop_gap {
+				sync_config.full_scan_stop_gap = full_scan_stop_gap;
+			}
 			builder.set_chain_source_electrum(electrum_url.clone(), Some(sync_config));
 		},
 		TestChainSource::BitcoindRpcSync(bitcoind) => {

tests/integration_tests_rust.rs

@@ -1000,7 +1000,7 @@ async fn onchain_wallet_force_full_scan_rediscovers_esplora_funds() {
 }
 
 #[tokio::test(flavor = "multi_thread", worker_threads = 1)]
-async fn onchain_wallet_full_scan_stop_gap_recovers_far_esplora_funds() {
+async fn onchain_wallet_full_scan_stop_gap_recovers_far_esplora_and_electrum_funds() {
 	let (bitcoind, electrsd) = setup_bitcoind_and_electrsd();
 	premine_blocks(&bitcoind.client, &electrsd.client).await;
 
@@ -1010,6 +1010,12 @@ async fn onchain_wallet_full_scan_stop_gap_recovers_far_esplora_funds() {
 		&electrsd,
 	)
 	.await;
+	do_onchain_wallet_full_scan_stop_gap_recovers_far_funds(
+		TestChainSource::Electrum(&electrsd),
+		&bitcoind,
+		&electrsd,
+	)
+	.await;
 }
 
 async fn do_onchain_wallet_full_scan_stop_gap_recovers_far_funds(