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

@@ -30,6 +30,10 @@ dictionary EsploraSyncConfig {
 	BackgroundSyncConfig? background_sync_config;
 };
 
+dictionary ElectrumSyncConfig {
+	BackgroundSyncConfig? background_sync_config;
+};
+
 dictionary LSPS2ServiceConfig {
 	string? require_token;
 	boolean advertise_service;
@@ -72,6 +76,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, may_announce_channel, AnnounceError, Config, EsploraSyncConfig,
-	DEFAULT_LOG_FILENAME, DEFAULT_LOG_LEVEL, WALLET_KEYS_SEED_LEN,
+	default_user_config, may_announce_channel, AnnounceError, Config, ElectrumSyncConfig,
+	EsploraSyncConfig, DEFAULT_LOG_FILENAME, DEFAULT_LOG_LEVEL, WALLET_KEYS_SEED_LEN,
 };
 
 use crate::connection::ConnectionManager;
@@ -83,6 +83,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 },
 }
 
@@ -284,6 +285,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(
@@ -691,6 +704,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(
@@ -1024,6 +1047,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,60 @@
+// 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 electrum_client::ConfigBuilder as ElectrumConfigBuilder;
+
+use std::sync::Arc;
+
+const ELECTRUM_CLIENT_NUM_RETRIES: u8 = 3;
+const ELECTRUM_CLIENT_TIMEOUT_SECS: u8 = 20;
+
+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_config = ElectrumConfigBuilder::new()
+			.retry(ELECTRUM_CLIENT_NUM_RETRIES)
+			.timeout(Some(ELECTRUM_CLIENT_TIMEOUT_SECS))
+			.build();
+
+		let electrum_client = Arc::new(
+			ElectrumClient::from_config(&server_url, electrum_config.clone()).map_err(|e| {
+				log_error!(logger, "Failed to connect to electrum server: {}", e);
+				Error::ConnectionFailed
+			})?,
+		);
+		let electrum_client_2 =
+			ElectrumClient::from_config(&server_url, electrum_config).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,
@@ -107,6 +109,45 @@ impl WalletSyncStatus {
 	}
 }
 
+pub(crate) enum ElectrumRuntimeStatus {
+	Started(Arc<ElectrumRuntimeClient>),
+	Stopped,
+}
+
+impl ElectrumRuntimeStatus {
+	pub(crate) fn new() -> Self {
+		Self::Stopped
+	}
+
+	pub(crate) fn start(
+		&mut self, server_url: String, runtime: Arc<tokio::runtime::Runtime>, logger: Arc<Logger>,
+	) -> Result<(), Error> {
+		match self {
+			Self::Stopped => {
+				let client =
+					Arc::new(ElectrumRuntimeClient::new(server_url.clone(), runtime, logger)?);
+
+				*self = Self::Started(client);
+			},
+			Self::Started(_) => {
+				debug_assert!(false, "We shouldn't call start if we're already started")
+			},
+		}
+		Ok(())
+	}
+
+	pub(crate) fn stop(&mut self) {
+		*self = Self::new()
+	}
+
+	pub(crate) fn client(&self) -> Option<&Arc<ElectrumRuntimeClient>> {
+		match self {
+			Self::Started(client) => Some(&client),
+			Self::Stopped { .. } => None,
+		}
+	}
+}
+
 pub(crate) enum ChainSource {
 	Esplora {
 		sync_config: EsploraSyncConfig,
@@ -122,6 +163,20 @@ pub(crate) enum ChainSource {
 		logger: Arc<Logger>,
 		node_metrics: Arc<RwLock<NodeMetrics>>,
 	},
+	Electrum {
+		server_url: String,
+		sync_config: ElectrumSyncConfig,
+		electrum_runtime_status: RwLock<ElectrumRuntimeStatus>,
+		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 +222,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_status = RwLock::new(ElectrumRuntimeStatus::new());
+		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_status,
+			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 +273,33 @@ impl ChainSource {
 		}
 	}
 
+	pub(crate) fn start(&self, runtime: Arc<tokio::runtime::Runtime>) -> Result<(), Error> {
+		match self {
+			Self::Electrum { server_url, electrum_runtime_status, logger, .. } => {
+				electrum_runtime_status.write().unwrap().start(
+					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_status, .. } => {
+				electrum_runtime_status.write().unwrap().stop();
+			},
+			_ => {
+				// 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()),
@@ -271,6 +378,7 @@ impl ChainSource {
 					return;
 				}
 			},
+			Self::Electrum { .. } => todo!(),
 			Self::BitcoindRpc {
 				bitcoind_rpc_client,
 				header_cache,
@@ -538,6 +646,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.
@@ -637,6 +746,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.
@@ -655,6 +765,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,
@@ -875,6 +990,7 @@ impl ChainSource {
 
 				Ok(())
 			},
+			Self::Electrum { .. } => todo!(),
 			Self::BitcoindRpc {
 				bitcoind_rpc_client,
 				fee_estimator,
@@ -1085,6 +1201,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
@@ -1147,12 +1264,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 { .. } => (),
 		}
 	}