Merge pull request #486 from tnull/2025-02-add-electrum-support

Add support for sourcing chain data from Electrum

Author: tnull

.github/workflows/kotlin.yml

@@ -39,6 +39,9 @@ jobs:
       - name: Generate Kotlin JVM
         run: ./scripts/uniffi_bindgen_generate_kotlin.sh
 
+      - name: Install `bindgen-cli`
+        run: cargo install --force bindgen-cli
+
       - name: Generate Kotlin Android
         run: ./scripts/uniffi_bindgen_generate_kotlin_android.sh
 

Cargo.toml

@@ -36,7 +36,7 @@ lightning-persister = { version = "0.1.0" }
 lightning-background-processor = { version = "0.1.0", features = ["futures"] }
 lightning-rapid-gossip-sync = { version = "0.1.0" }
 lightning-block-sync = { version = "0.1.0", features = ["rpc-client", "tokio"] }
-lightning-transaction-sync = { version = "0.1.0", features = ["esplora-async-https", "time"] }
+lightning-transaction-sync = { version = "0.1.0", features = ["esplora-async-https", "time", "electrum"] }
 lightning-liquidity = { version = "0.1.0", features = ["std"] }
 
 #lightning = { git = "https://github.com/lightningdevkit/rust-lightning", branch = "main", features = ["std"] }
@@ -63,6 +63,7 @@ lightning-liquidity = { version = "0.1.0", features = ["std"] }
 
 bdk_chain = { version = "0.21.1", default-features = false, features = ["std"] }
 bdk_esplora = { version = "0.20.1", default-features = false, features = ["async-https-rustls", "tokio"]}
+bdk_electrum = { version = "0.20.1", default-features = false, features = ["use-rustls"]}
 bdk_wallet = { version = "1.0.0", default-features = false, features = ["std", "keys-bip39"]}
 
 reqwest = { version = "0.11", default-features = false, features = ["json", "rustls-tls"] }
@@ -76,6 +77,7 @@ rand = "0.8.5"
 chrono = { version = "0.4", default-features = false, features = ["clock"] }
 tokio = { version = "1.37", default-features = false, features = [ "rt-multi-thread", "time", "sync", "macros" ] }
 esplora-client = { version = "0.11", default-features = false, features = ["tokio", "async-https-rustls"] }
+electrum-client = { version = "0.22.0", default-features = true }
 libc = "0.2"
 uniffi = { version = "0.27.3", features = ["build"], optional = true }
 serde = { version = "1.0.210", default-features = false, features = ["std", "derive"] }
@@ -92,16 +94,15 @@ winapi = { version = "0.3", features = ["winbase"] }
 lightning = { version = "0.1.0", features = ["std", "_test_utils"] }
 #lightning = { git = "https://github.com/lightningdevkit/rust-lightning", branch="main", features = ["std", "_test_utils"] }
 #lightning = { path = "../rust-lightning/lightning", features = ["std", "_test_utils"] }
-electrum-client = { version = "0.21.0", default-features = true }
-bitcoincore-rpc = { version = "0.19.0", default-features = false }
 proptest = "1.0.0"
 regex = "1.5.6"
 
 [target.'cfg(not(no_download))'.dev-dependencies]
-electrsd = { version = "0.29.0", features = ["legacy", "esplora_a33e97e1", "bitcoind_25_0"] }
+electrsd = { version = "0.33.0", default-features = false, features = ["legacy", "esplora_a33e97e1", "corepc-node_27_2"] }
 
 [target.'cfg(no_download)'.dev-dependencies]
-electrsd = { version = "0.29.0", features = ["legacy"] }
+electrsd = { version = "0.33.0", default-features = false, features = ["legacy"] }
+corepc-node = { version = "0.7.0", default-features = false, features = ["27_2"] }
 
 [target.'cfg(cln_test)'.dev-dependencies]
 clightningrpc = { version = "0.3.0-beta.8", default-features = false }

README.md

@@ -55,7 +55,7 @@ fn main() {
 LDK Node currently comes with a decidedly opinionated set of design choices:
 
 - On-chain data is handled by the integrated [BDK][bdk] wallet.
-- Chain data may currently be sourced from the Bitcoin Core RPC interface or an [Esplora][esplora] server, while support for Electrum will follow soon.
+- Chain data may currently be sourced from the Bitcoin Core RPC interface, or from an [Electrum][electrum] or [Esplora][esplora] server.
 - Wallet and channel state may be persisted to an [SQLite][sqlite] database, to file system, or to a custom back-end to be implemented by the user.
 - Gossip data may be sourced via Lightning's peer-to-peer network or the [Rapid Gossip Sync](https://docs.rs/lightning-rapid-gossip-sync/*/lightning_rapid_gossip_sync/) protocol.
 - Entropy for the Lightning and on-chain wallets may be sourced from raw bytes or a [BIP39](https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki) mnemonic. In addition, LDK Node offers the means to generate and persist the entropy bytes to disk.
@@ -72,6 +72,7 @@ The Minimum Supported Rust Version (MSRV) is currently 1.75.0.
 [rust_crate]: https://crates.io/
 [ldk]: https://lightningdevkit.org/
 [bdk]: https://bitcoindevkit.org/
+[electrum]: https://github.com/spesmilo/electrum-protocol
 [esplora]: https://github.com/Blockstream/esplora
 [sqlite]: https://sqlite.org/
 [rust]: https://www.rust-lang.org/

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);

docker-compose-cln.yml

@@ -1,8 +1,6 @@
-version: '3'
-
 services:
   bitcoin:
-    image: blockstream/bitcoind:24.1
+    image: blockstream/bitcoind:27.2
     platform: linux/amd64
     command:
       [

scripts/download_bitcoind_electrs.sh

@@ -1,3 +1,6 @@
+#!/bin/bash
+set -eox pipefail
+
 # Our Esplora-based tests require `electrs` and `bitcoind`
 # binaries. Here, we download the binaries, validate them, and export their
 # location via `ELECTRS_EXE`/`BITCOIND_EXE` which will be used by the
@@ -7,19 +10,20 @@ HOST_PLATFORM="$(rustc --version --verbose | grep "host:" | awk '{ print $2 }')"
 ELECTRS_DL_ENDPOINT="https://github.com/RCasatta/electrsd/releases/download/electrs_releases"
 ELECTRS_VERSION="esplora_a33e97e1a1fc63fa9c20a116bb92579bbf43b254"
 BITCOIND_DL_ENDPOINT="https://bitcoincore.org/bin/"
-BITCOIND_VERSION="25.1"
+BITCOIND_VERSION="27.2"
 if [[ "$HOST_PLATFORM" == *linux* ]]; then
 	ELECTRS_DL_FILE_NAME=electrs_linux_"$ELECTRS_VERSION".zip
 	ELECTRS_DL_HASH="865e26a96e8df77df01d96f2f569dcf9622fc87a8d99a9b8fe30861a4db9ddf1"
 	BITCOIND_DL_FILE_NAME=bitcoin-"$BITCOIND_VERSION"-x86_64-linux-gnu.tar.gz
-	BITCOIND_DL_HASH="a978c407b497a727f0444156e397b50491ce862d1f906fef9b521415b3611c8b"
+	BITCOIND_DL_HASH="acc223af46c178064c132b235392476f66d486453ddbd6bca6f1f8411547da78"
 elif [[ "$HOST_PLATFORM" == *darwin* ]]; then
 	ELECTRS_DL_FILE_NAME=electrs_macos_"$ELECTRS_VERSION".zip
 	ELECTRS_DL_HASH="2d5ff149e8a2482d3658e9b386830dfc40c8fbd7c175ca7cbac58240a9505bcd"
 	BITCOIND_DL_FILE_NAME=bitcoin-"$BITCOIND_VERSION"-x86_64-apple-darwin.tar.gz
-	BITCOIND_DL_HASH="1acfde0ec3128381b83e3e5f54d1c7907871d324549129592144dd12a821eff1"
+	BITCOIND_DL_HASH="6ebc56ca1397615d5a6df2b5cf6727b768e3dcac320c2d5c2f321dcaabc7efa2"
 else
-	echo "\n\nUnsupported platform: $HOST_PLATFORM Exiting.."
+	printf "\n\n"
+	echo "Unsupported platform: $HOST_PLATFORM Exiting.."
 	exit 1
 fi
 

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(),