Allow disabling wallet background syncing

Author: alexanderwiederin

bindings/ldk_node.udl

@@ -20,9 +20,9 @@ dictionary AnchorChannelsConfig {
 };
 
 dictionary EsploraSyncConfig {
-	u64 onchain_wallet_sync_interval_secs;
-	u64 lightning_wallet_sync_interval_secs;
-	u64 fee_rate_cache_update_interval_secs;
+	u64? onchain_wallet_sync_interval_secs;
+	u64? lightning_wallet_sync_interval_secs;
+	u64? fee_rate_cache_update_interval_secs;
 };
 
 dictionary LSPS2ServiceConfig {

src/chain/mod.rs

@@ -207,57 +207,81 @@ impl ChainSource {
 	) {
 		match self {
 			Self::Esplora { sync_config, logger, .. } => {
-				// Setup syncing intervals
-				let onchain_wallet_sync_interval_secs = sync_config
-					.onchain_wallet_sync_interval_secs
-					.max(WALLET_SYNC_INTERVAL_MINIMUM_SECS);
-				let mut onchain_wallet_sync_interval =
-					tokio::time::interval(Duration::from_secs(onchain_wallet_sync_interval_secs));
-				onchain_wallet_sync_interval
-					.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Skip);
+				// Setup background syncing intervals if enabled
+				if let Some(background_sync_config) = sync_config.background_sync_config {
+					let onchain_interval_secs = background_sync_config
+						.onchain_wallet_sync_interval_secs
+						.max(WALLET_SYNC_INTERVAL_MINIMUM_SECS);
+					let mut onchain_interval =
+						tokio::time::interval(Duration::from_secs(onchain_interval_secs));
+					onchain_interval
+						.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Skip);
+					log_info!(
+						logger,
+						"Onchain wallet background syncing enabled with interval of {} seconds",
+						onchain_interval_secs
+					);
 
-				let fee_rate_cache_update_interval_secs = sync_config
-					.fee_rate_cache_update_interval_secs
-					.max(WALLET_SYNC_INTERVAL_MINIMUM_SECS);
-				let mut fee_rate_update_interval =
-					tokio::time::interval(Duration::from_secs(fee_rate_cache_update_interval_secs));
-				// When starting up, we just blocked on updating, so skip the first tick.
-				fee_rate_update_interval.reset();
-				fee_rate_update_interval
-					.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Skip);
+					let lightning_interval_secs = background_sync_config
+						.lightning_wallet_sync_interval_secs
+						.max(WALLET_SYNC_INTERVAL_MINIMUM_SECS);
+					let mut lightning_interval =
+						tokio::time::interval(Duration::from_secs(lightning_interval_secs));
+					lightning_interval
+						.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Skip);
+					log_info!(
+						logger,
+						"Lightning wallet background syncing enabled with interval of {} seconds",
+						lightning_interval_secs
+					);
 
-				let lightning_wallet_sync_interval_secs = sync_config
-					.lightning_wallet_sync_interval_secs
-					.max(WALLET_SYNC_INTERVAL_MINIMUM_SECS);
-				let mut lightning_wallet_sync_interval =
-					tokio::time::interval(Duration::from_secs(lightning_wallet_sync_interval_secs));
-				lightning_wallet_sync_interval
-					.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Skip);
+					let fee_rate_interval_secs = background_sync_config
+						.fee_rate_cache_update_interval_secs
+						.max(WALLET_SYNC_INTERVAL_MINIMUM_SECS);
+					let mut fee_rate_interval =
+						tokio::time::interval(Duration::from_secs(fee_rate_interval_secs));
+					// When starting up, we just blocked on updating, so skip the first tick.
+					fee_rate_interval.reset();
+					fee_rate_interval
+						.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Skip);
+					log_info!(
+						logger,
+						"Fee rate background syncing enabled with interval of {} seconds",
+						fee_rate_interval_secs
+					);
 
-				// Start the syncing loop.
-				loop {
-					tokio::select! {
-						_ = stop_sync_receiver.changed() => {
-							log_trace!(
-								logger,
-								"Stopping background syncing on-chain wallet.",
-							);
-							return;
-						}
-						_ = onchain_wallet_sync_interval.tick() => {
-							let _ = self.sync_onchain_wallet().await;
-						}
-						_ = fee_rate_update_interval.tick() => {
-							let _ = self.update_fee_rate_estimates().await;
-						}
-						_ = lightning_wallet_sync_interval.tick() => {
-							let _ = self.sync_lightning_wallet(
-								Arc::clone(&channel_manager),
-								Arc::clone(&chain_monitor),
-								Arc::clone(&output_sweeper),
-							).await;
+					loop {
+						tokio::select! {
+							_ = stop_sync_receiver.changed() => {
+								log_trace!(logger, "Stopping Esplora background syncing.");
+								return;
+							}
+
+							_ = onchain_interval.tick() => {
+								let _ = self.sync_onchain_wallet().await;
+							}
+
+							_ = fee_rate_interval.tick() => {
+								let _ = self.update_fee_rate_estimates().await;
+							}
+
+							_ = lightning_interval.tick() => {
+								let _ = self.sync_lightning_wallet(
+									Arc::clone(&channel_manager),
+									Arc::clone(&chain_monitor),
+									Arc::clone(&output_sweeper),
+								).await;
+							}
 						}
 					}
+				} else {
+					// Background syncing is disabled
+					log_info!(
+						logger,
+						"Background syncing disabled. Manual syncing required for onchain wallet, lightning wallet, and fee rate updates.",
+					);
+
+					return;
 				}
 			},
 			Self::BitcoindRpc {

src/config.rs

@@ -19,6 +19,7 @@ use lightning::util::config::UserConfig;
 use bitcoin::secp256k1::PublicKey;
 use bitcoin::Network;
 
+use crate::Node;
 use std::time::Duration;
 
 // Config defaults
@@ -282,7 +283,7 @@ pub(crate) fn default_user_config(config: &Config) -> UserConfig {
 	user_config
 }
 
-/// Options related to syncing the Lightning and on-chain wallets via an Esplora backend.
+/// Options related to background syncing the Lightning and on-chain wallets via an Esplora backend.
 ///
 /// ### Defaults
 ///
@@ -292,27 +293,39 @@ pub(crate) fn default_user_config(config: &Config) -> UserConfig {
 /// | `lightning_wallet_sync_interval_secs`  | 30                 |
 /// | `fee_rate_cache_update_interval_secs`  | 600                |
 #[derive(Debug, Copy, Clone, PartialEq, Eq)]
-pub struct EsploraSyncConfig {
+pub struct BackgroundSyncConfig {
 	/// The time in-between background sync attempts of the onchain wallet, in seconds.
 	///
-	/// **Note:** A minimum of 10 seconds is always enforced.
+	/// **Note:** A minimum of 10 seconds is enforced when background syncing is enabled.
 	pub onchain_wallet_sync_interval_secs: u64,
+
 	/// The time in-between background sync attempts of the LDK wallet, in seconds.
 	///
-	/// **Note:** A minimum of 10 seconds is always enforced.
+	/// **Note:** A minimum of 10 seconds is enforced when background syncing is enabled.
 	pub lightning_wallet_sync_interval_secs: u64,
+
 	/// The time in-between background update attempts to our fee rate cache, in seconds.
 	///
-	/// **Note:** A minimum of 10 seconds is always enforced.
+	/// **Note:** A minimum of 10 seconds is enforced when background syncing is enabled.
 	pub fee_rate_cache_update_interval_secs: u64,
 }
 
+/// Configuration for syncing with an Esplora backend.
+#[derive(Debug, Copy, Clone, PartialEq, Eq)]
+pub struct EsploraSyncConfig {
+	/// Background sync configuration. If set to `None`, background syncing will be disabled.
+	/// Users will need to manually sync via [`Node::sync_wallets`] for the wallets and fee rate updates.
+	pub background_sync_config: Option<BackgroundSyncConfig>,
+}
+
 impl Default for EsploraSyncConfig {
 	fn default() -> Self {
 		Self {
-			onchain_wallet_sync_interval_secs: DEFAULT_BDK_WALLET_SYNC_INTERVAL_SECS,
-			lightning_wallet_sync_interval_secs: DEFAULT_LDK_WALLET_SYNC_INTERVAL_SECS,
-			fee_rate_cache_update_interval_secs: DEFAULT_FEE_RATE_CACHE_UPDATE_INTERVAL_SECS,
+			background_sync_config: Some(BackgroundSyncConfig {
+				onchain_wallet_sync_interval_secs: DEFAULT_BDK_WALLET_SYNC_INTERVAL_SECS,
+				lightning_wallet_sync_interval_secs: DEFAULT_LDK_WALLET_SYNC_INTERVAL_SECS,
+				fee_rate_cache_update_interval_secs: DEFAULT_FEE_RATE_CACHE_UPDATE_INTERVAL_SECS,
+			}),
 		}
 	}
 }

src/lib.rs

@@ -1219,14 +1219,13 @@ impl Node {
 	/// Manually sync the LDK and BDK wallets with the current chain state and update the fee rate
 	/// cache.
 	///
-	/// **Note:** The wallets are regularly synced in the background, which is configurable via the
-	/// respective config object, e.g., via
-	/// [`EsploraSyncConfig::onchain_wallet_sync_interval_secs`] and
-	/// [`EsploraSyncConfig::lightning_wallet_sync_interval_secs`]. Therefore, using this blocking
-	/// sync method is almost always redundant and should be avoided where possible.
+	/// **Note:** The wallets are regularly synced in the background if background syncing is enabled
+	/// via [`EsploraSyncConfig::background_sync_config`]. Therefore, using this blocking sync method
+	/// is almost always redundant when background syncing is enabled and should be avoided where possible.
+	/// However, if background syncing is disabled (i.e., `background_sync_config` is set to `None`),
+	/// this method must be called manually to keep wallets in sync with the chain state.
 	///
-	/// [`EsploraSyncConfig::onchain_wallet_sync_interval_secs`]: crate::config::EsploraSyncConfig::onchain_wallet_sync_interval_secs
-	/// [`EsploraSyncConfig::lightning_wallet_sync_interval_secs`]: crate::config::EsploraSyncConfig::lightning_wallet_sync_interval_secs
+	/// [`EsploraSyncConfig::background_sync_config`]: crate::config::EsploraSyncConfig::background_sync_config
 	pub fn sync_wallets(&self) -> Result<(), Error> {
 		let rt_lock = self.runtime.read().unwrap();
 		if rt_lock.is_none() {

tests/common/mod.rs

@@ -311,8 +311,8 @@ pub(crate) fn setup_node(
 		TestChainSource::Esplora(electrsd) => {
 			let esplora_url = format!("http://{}", electrsd.esplora_url.as_ref().unwrap());
 			let mut sync_config = EsploraSyncConfig::default();
-			sync_config.onchain_wallet_sync_interval_secs = 100000;
-			sync_config.lightning_wallet_sync_interval_secs = 100000;
+			sync_config.onchain_wallet_sync_interval_secs = Some(100000);
+			sync_config.lightning_wallet_sync_interval_secs = Some(100000);
 			builder.set_chain_source_esplora(esplora_url.clone(), Some(sync_config));
 		},
 		TestChainSource::BitcoindRpc(bitcoind) => {

tests/integration_tests_rust.rs

@@ -128,8 +128,8 @@ fn multi_hop_sending() {
 	for _ in 0..5 {
 		let config = random_config(true);
 		let mut sync_config = EsploraSyncConfig::default();
-		sync_config.onchain_wallet_sync_interval_secs = 100000;
-		sync_config.lightning_wallet_sync_interval_secs = 100000;
+		sync_config.onchain_wallet_sync_interval_secs = None;
+		sync_config.lightning_wallet_sync_interval_secs = None;
 		setup_builder!(builder, config.node_config);
 		builder.set_chain_source_esplora(esplora_url.clone(), Some(sync_config));
 		let node = builder.build().unwrap();
@@ -228,8 +228,8 @@ fn start_stop_reinit() {
 		Arc::new(TestSyncStore::new(config.node_config.storage_dir_path.clone().into()));
 
 	let mut sync_config = EsploraSyncConfig::default();
-	sync_config.onchain_wallet_sync_interval_secs = 100000;
-	sync_config.lightning_wallet_sync_interval_secs = 100000;
+	sync_config.onchain_wallet_sync_interval_secs = Some(100000);
+	sync_config.lightning_wallet_sync_interval_secs = Some(100000);
 	setup_builder!(builder, config.node_config);
 	builder.set_chain_source_esplora(esplora_url.clone(), Some(sync_config));
 
@@ -1049,8 +1049,8 @@ fn lsps2_client_service_integration() {
 	let esplora_url = format!("http://{}", electrsd.esplora_url.as_ref().unwrap());
 
 	let mut sync_config = EsploraSyncConfig::default();
-	sync_config.onchain_wallet_sync_interval_secs = 100000;
-	sync_config.lightning_wallet_sync_interval_secs = 100000;
+	sync_config.onchain_wallet_sync_interval_secs = Some(100000);
+	sync_config.lightning_wallet_sync_interval_secs = Some(100000);
 
 	// Setup three nodes: service, client, and payer
 	let channel_opening_fee_ppm = 10_000;