Allow to configure ChainSource::Electrum via builder

We here setup the basic API and structure for the
`ChainSource::Electrum`.

Currently, we won't have a `Runtime` available when initializing
`ChainSource::Electrum` in `Builder::build`. We therefore isolate any
runtime-specific behavior into an `ElectrumRuntimeClient`.

This might change in the future, but for now we do need this workaround.

Author: tnull

bindings/ldk_node.udl

@@ -25,6 +25,12 @@ dictionary EsploraSyncConfig {
 	u64 fee_rate_cache_update_interval_secs;
 };
 
+dictionary ElectrumSyncConfig {
+	u64 onchain_wallet_sync_interval_secs;
+	u64 lightning_wallet_sync_interval_secs;
+	u64 fee_rate_cache_update_interval_secs;
+};
+
 dictionary LSPS2ServiceConfig {
 	string? require_token;
 	boolean advertise_service;
@@ -67,6 +73,7 @@ interface Builder {
 	void set_entropy_seed_bytes(sequence<u8> seed_bytes);
 	void set_entropy_bip39_mnemonic(Mnemonic mnemonic, string? passphrase);
 	void set_chain_source_esplora(string server_url, EsploraSyncConfig? config);
+	void set_chain_source_electrum(string server_url, ElectrumSyncConfig? config);
 	void set_chain_source_bitcoind_rpc(string rpc_host, u16 rpc_port, string rpc_user, string rpc_password);
 	void set_gossip_source_p2p();
 	void set_gossip_source_rgs(string rgs_server_url);

src/builder.rs

@@ -7,8 +7,8 @@
 
 use crate::chain::{ChainSource, DEFAULT_ESPLORA_SERVER_URL};
 use crate::config::{
-	default_user_config, Config, EsploraSyncConfig, DEFAULT_LOG_FILENAME, DEFAULT_LOG_LEVEL,
-	WALLET_KEYS_SEED_LEN,
+	default_user_config, Config, ElectrumSyncConfig, EsploraSyncConfig, DEFAULT_LOG_FILENAME,
+	DEFAULT_LOG_LEVEL, WALLET_KEYS_SEED_LEN,
 };
 
 use crate::connection::ConnectionManager;
@@ -84,6 +84,7 @@ const LSPS_HARDENED_CHILD_INDEX: u32 = 577;
 #[derive(Debug, Clone)]
 enum ChainDataSourceConfig {
 	Esplora { server_url: String, sync_config: Option<EsploraSyncConfig> },
+	Electrum { server_url: String, sync_config: Option<ElectrumSyncConfig> },
 	BitcoindRpc { rpc_host: String, rpc_port: u16, rpc_user: String, rpc_password: String },
 }
 
@@ -280,6 +281,18 @@ impl NodeBuilder {
 		self
 	}
 
+	/// Configures the [`Node`] instance to source its chain data from the given Electrum server.
+	///
+	/// If no `sync_config` is given, default values are used. See [`ElectrumSyncConfig`] for more
+	/// information.
+	pub fn set_chain_source_electrum(
+		&mut self, server_url: String, sync_config: Option<ElectrumSyncConfig>,
+	) -> &mut Self {
+		self.chain_data_source_config =
+			Some(ChainDataSourceConfig::Electrum { server_url, sync_config });
+		self
+	}
+
 	/// Configures the [`Node`] instance to source its chain data from the given Bitcoin Core RPC
 	/// endpoint.
 	pub fn set_chain_source_bitcoind_rpc(
@@ -671,6 +684,16 @@ impl ArcedNodeBuilder {
 		self.inner.write().unwrap().set_chain_source_esplora(server_url, sync_config);
 	}
 
+	/// Configures the [`Node`] instance to source its chain data from the given Electrum server.
+	///
+	/// If no `sync_config` is given, default values are used. See [`ElectrumSyncConfig`] for more
+	/// information.
+	pub fn set_chain_source_electrum(
+		&self, server_url: String, sync_config: Option<ElectrumSyncConfig>,
+	) {
+		self.inner.write().unwrap().set_chain_source_electrum(server_url, sync_config);
+	}
+
 	/// Configures the [`Node`] instance to source its chain data from the given Bitcoin Core RPC
 	/// endpoint.
 	pub fn set_chain_source_bitcoind_rpc(
@@ -976,6 +999,20 @@ fn build_with_store_internal(
 				Arc::clone(&node_metrics),
 			))
 		},
+		Some(ChainDataSourceConfig::Electrum { server_url, sync_config }) => {
+			let sync_config = sync_config.unwrap_or(ElectrumSyncConfig::default());
+			Arc::new(ChainSource::new_electrum(
+				server_url.clone(),
+				sync_config,
+				Arc::clone(&wallet),
+				Arc::clone(&fee_estimator),
+				Arc::clone(&tx_broadcaster),
+				Arc::clone(&kv_store),
+				Arc::clone(&config),
+				Arc::clone(&logger),
+				Arc::clone(&node_metrics),
+			))
+		},
 		Some(ChainDataSourceConfig::BitcoindRpc { rpc_host, rpc_port, rpc_user, rpc_password }) => {
 			Arc::new(ChainSource::new_bitcoind_rpc(
 				rpc_host.clone(),

src/chain/electrum.rs

@@ -0,0 +1,48 @@
+// This file is Copyright its original authors, visible in version control history.
+//
+// This file is licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
+// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license <LICENSE-MIT or
+// http://opensource.org/licenses/MIT>, at your option. You may not use this file except in
+// accordance with one or both of these licenses.
+
+use crate::error::Error;
+use crate::logger::{log_error, LdkLogger, Logger};
+
+use lightning_transaction_sync::ElectrumSyncClient;
+
+use bdk_electrum::BdkElectrumClient;
+
+use electrum_client::Client as ElectrumClient;
+
+use std::sync::Arc;
+
+pub(crate) struct ElectrumRuntimeClient {
+	electrum_client: Arc<ElectrumClient>,
+	bdk_electrum_client: Arc<BdkElectrumClient<ElectrumClient>>,
+	tx_sync: Arc<ElectrumSyncClient<Arc<Logger>>>,
+	runtime: Arc<tokio::runtime::Runtime>,
+	logger: Arc<Logger>,
+}
+
+impl ElectrumRuntimeClient {
+	pub(crate) fn new(
+		server_url: String, runtime: Arc<tokio::runtime::Runtime>, logger: Arc<Logger>,
+	) -> Result<Self, Error> {
+		let electrum_client = Arc::new(ElectrumClient::new(&server_url).map_err(|e| {
+			log_error!(logger, "Failed to connect to electrum server: {}", e);
+			Error::ConnectionFailed
+		})?);
+		let electrum_client_2 = ElectrumClient::new(&server_url).map_err(|e| {
+			log_error!(logger, "Failed to connect to electrum server: {}", e);
+			Error::ConnectionFailed
+		})?;
+		let bdk_electrum_client = Arc::new(BdkElectrumClient::new(electrum_client_2));
+		let tx_sync = Arc::new(
+			ElectrumSyncClient::new(server_url.clone(), Arc::clone(&logger)).map_err(|e| {
+				log_error!(logger, "Failed to connect to electrum server: {}", e);
+				Error::ConnectionFailed
+			})?,
+		);
+		Ok(Self { electrum_client, bdk_electrum_client, tx_sync, runtime, logger })
+	}
+}

src/chain/mod.rs

@@ -6,12 +6,14 @@
 // accordance with one or both of these licenses.
 
 mod bitcoind_rpc;
+mod electrum;
 
 use crate::chain::bitcoind_rpc::{
 	BitcoindRpcClient, BoundedHeaderCache, ChainListener, FeeRateEstimationMode,
 };
+use crate::chain::electrum::ElectrumRuntimeClient;
 use crate::config::{
-	Config, EsploraSyncConfig, BDK_CLIENT_CONCURRENCY, BDK_CLIENT_STOP_GAP,
+	Config, ElectrumSyncConfig, EsploraSyncConfig, BDK_CLIENT_CONCURRENCY, BDK_CLIENT_STOP_GAP,
 	BDK_WALLET_SYNC_TIMEOUT_SECS, FEE_RATE_CACHE_UPDATE_TIMEOUT_SECS, LDK_WALLET_SYNC_TIMEOUT_SECS,
 	RESOLVED_CHANNEL_MONITOR_ARCHIVAL_INTERVAL, TX_BROADCAST_TIMEOUT_SECS,
 	WALLET_SYNC_INTERVAL_MINIMUM_SECS,
@@ -122,6 +124,20 @@ pub(crate) enum ChainSource {
 		logger: Arc<Logger>,
 		node_metrics: Arc<RwLock<NodeMetrics>>,
 	},
+	Electrum {
+		server_url: String,
+		sync_config: ElectrumSyncConfig,
+		electrum_runtime_client: RwLock<Option<ElectrumRuntimeClient>>,
+		onchain_wallet: Arc<Wallet>,
+		onchain_wallet_sync_status: Mutex<WalletSyncStatus>,
+		lightning_wallet_sync_status: Mutex<WalletSyncStatus>,
+		fee_estimator: Arc<OnchainFeeEstimator>,
+		tx_broadcaster: Arc<Broadcaster>,
+		kv_store: Arc<DynStore>,
+		config: Arc<Config>,
+		logger: Arc<Logger>,
+		node_metrics: Arc<RwLock<NodeMetrics>>,
+	},
 	BitcoindRpc {
 		bitcoind_rpc_client: Arc<BitcoindRpcClient>,
 		header_cache: tokio::sync::Mutex<BoundedHeaderCache>,
@@ -167,6 +183,31 @@ impl ChainSource {
 		}
 	}
 
+	pub(crate) fn new_electrum(
+		server_url: String, sync_config: ElectrumSyncConfig, onchain_wallet: Arc<Wallet>,
+		fee_estimator: Arc<OnchainFeeEstimator>, tx_broadcaster: Arc<Broadcaster>,
+		kv_store: Arc<DynStore>, config: Arc<Config>, logger: Arc<Logger>,
+		node_metrics: Arc<RwLock<NodeMetrics>>,
+	) -> Self {
+		let electrum_runtime_client = RwLock::new(None);
+		let onchain_wallet_sync_status = Mutex::new(WalletSyncStatus::Completed);
+		let lightning_wallet_sync_status = Mutex::new(WalletSyncStatus::Completed);
+		Self::Electrum {
+			server_url,
+			sync_config,
+			electrum_runtime_client,
+			onchain_wallet,
+			onchain_wallet_sync_status,
+			lightning_wallet_sync_status,
+			fee_estimator,
+			tx_broadcaster,
+			kv_store,
+			config,
+			logger,
+			node_metrics,
+		}
+	}
+
 	pub(crate) fn new_bitcoind_rpc(
 		host: String, port: u16, rpc_user: String, rpc_password: String,
 		onchain_wallet: Arc<Wallet>, fee_estimator: Arc<OnchainFeeEstimator>,
@@ -193,6 +234,35 @@ impl ChainSource {
 		}
 	}
 
+	pub(crate) fn start(&self, runtime: Arc<tokio::runtime::Runtime>) -> Result<(), Error> {
+		match self {
+			Self::Electrum { server_url, electrum_runtime_client, logger, .. } => {
+				let mut locked_client = electrum_runtime_client.write().unwrap();
+				*locked_client = Some(ElectrumRuntimeClient::new(
+					server_url.clone(),
+					runtime,
+					Arc::clone(&logger),
+				)?);
+			},
+			_ => {
+				// Nothing to do for other chain sources.
+			},
+		}
+		Ok(())
+	}
+
+	pub(crate) fn stop(&self) {
+		match self {
+			Self::Electrum { electrum_runtime_client, .. } => {
+				let mut locked_client = electrum_runtime_client.write().unwrap();
+				*locked_client = None;
+			},
+			_ => {
+				// Nothing to do for other chain sources.
+			},
+		}
+	}
+
 	pub(crate) fn as_utxo_source(&self) -> Option<Arc<dyn UtxoSource>> {
 		match self {
 			Self::BitcoindRpc { bitcoind_rpc_client, .. } => Some(bitcoind_rpc_client.rpc_client()),
@@ -260,6 +330,7 @@ impl ChainSource {
 					}
 				}
 			},
+			Self::Electrum { .. } => todo!(),
 			Self::BitcoindRpc {
 				bitcoind_rpc_client,
 				header_cache,
@@ -527,6 +598,7 @@ impl ChainSource {
 
 				res
 			},
+			Self::Electrum { .. } => todo!(),
 			Self::BitcoindRpc { .. } => {
 				// In BitcoindRpc mode we sync lightning and onchain wallet in one go by via
 				// `ChainPoller`. So nothing to do here.
@@ -626,6 +698,7 @@ impl ChainSource {
 
 				res
 			},
+			Self::Electrum { .. } => todo!(),
 			Self::BitcoindRpc { .. } => {
 				// In BitcoindRpc mode we sync lightning and onchain wallet in one go by via
 				// `ChainPoller`. So nothing to do here.
@@ -644,6 +717,11 @@ impl ChainSource {
 				// `sync_onchain_wallet` and `sync_lightning_wallet`. So nothing to do here.
 				unreachable!("Listeners will be synced via transction-based syncing")
 			},
+			Self::Electrum { .. } => {
+				// In Electrum mode we sync lightning and onchain wallets via
+				// `sync_onchain_wallet` and `sync_lightning_wallet`. So nothing to do here.
+				unreachable!("Listeners will be synced via transction-based syncing")
+			},
 			Self::BitcoindRpc {
 				bitcoind_rpc_client,
 				header_cache,
@@ -864,6 +942,7 @@ impl ChainSource {
 
 				Ok(())
 			},
+			Self::Electrum { .. } => todo!(),
 			Self::BitcoindRpc {
 				bitcoind_rpc_client,
 				fee_estimator,
@@ -1074,6 +1153,7 @@ impl ChainSource {
 					}
 				}
 			},
+			Self::Electrum { .. } => todo!(),
 			Self::BitcoindRpc { bitcoind_rpc_client, tx_broadcaster, logger, .. } => {
 				// While it's a bit unclear when we'd be able to lean on Bitcoin Core >v28
 				// features, we should eventually switch to use `submitpackage` via the
@@ -1136,12 +1216,14 @@ impl Filter for ChainSource {
 	fn register_tx(&self, txid: &bitcoin::Txid, script_pubkey: &bitcoin::Script) {
 		match self {
 			Self::Esplora { tx_sync, .. } => tx_sync.register_tx(txid, script_pubkey),
+			Self::Electrum { .. } => todo!(),
 			Self::BitcoindRpc { .. } => (),
 		}
 	}
 	fn register_output(&self, output: lightning::chain::WatchedOutput) {
 		match self {
 			Self::Esplora { tx_sync, .. } => tx_sync.register_output(output),
+			Self::Electrum { .. } => todo!(),
 			Self::BitcoindRpc { .. } => (),
 		}
 	}

src/config.rs

@@ -317,6 +317,41 @@ impl Default for EsploraSyncConfig {
 	}
 }
 
+/// Options related to syncing the Lightning and on-chain wallets via an Electrum backend.
+///
+/// ### Defaults
+///
+/// | Parameter                              | Value              |
+/// |----------------------------------------|--------------------|
+/// | `onchain_wallet_sync_interval_secs`    | 80                 |
+/// | `lightning_wallet_sync_interval_secs`  | 30                 |
+/// | `fee_rate_cache_update_interval_secs`  | 600                |
+#[derive(Debug, Copy, Clone, PartialEq, Eq)]
+pub struct ElectrumSyncConfig {
+	/// The time in-between background sync attempts of the onchain wallet, in seconds.
+	///
+	/// **Note:** A minimum of 10 seconds is always enforced.
+	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.
+	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.
+	pub fee_rate_cache_update_interval_secs: u64,
+}
+
+impl Default for ElectrumSyncConfig {
+	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,
+		}
+	}
+}
+
 /// Options which apply on a per-channel basis and may change at runtime or based on negotiation
 /// with our counterparty.
 #[derive(Copy, Clone, Debug, PartialEq, Eq)]

src/lib.rs

@@ -236,6 +236,12 @@ impl Node {
 			self.config.network
 		);
 
+		// Start up any runtime-dependant chain sources (e.g. Electrum)
+		self.chain_source.start(Arc::clone(&runtime)).map_err(|e| {
+			log_error!(self.logger, "Failed to start chain syncing: {}", e);
+			e
+		})?;
+
 		// Block to ensure we update our fee rate cache once on startup
 		let chain_source = Arc::clone(&self.chain_source);
 		let runtime_ref = &runtime;
@@ -638,6 +644,9 @@ impl Node {
 
 		log_info!(self.logger, "Shutting down LDK Node with node ID {}...", self.node_id());
 
+		// Stop any runtime-dependant chain sources.
+		self.chain_source.stop();
+
 		// Stop the runtime.
 		match self.stop_sender.send(()) {
 			Ok(_) => (),
@@ -1248,6 +1257,13 @@ impl Node {
 								.await?;
 							chain_source.sync_onchain_wallet().await?;
 						},
+						ChainSource::Electrum { .. } => {
+							chain_source.update_fee_rate_estimates().await?;
+							chain_source
+								.sync_lightning_wallet(sync_cman, sync_cmon, sync_sweeper)
+								.await?;
+							chain_source.sync_onchain_wallet().await?;
+						},
 						ChainSource::BitcoindRpc { .. } => {
 							chain_source.update_fee_rate_estimates().await?;
 							chain_source