feat: support chain sourcing via REST interface

This commit:
- Adds support for syncing data via Bitcoin Core's
REST interface.
- Unifies the REST and RPC Bitcoin Core API clients

Author: enigbe

Cargo.toml

@@ -35,7 +35,7 @@ lightning-net-tokio = { version = "0.1.0" }
 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-block-sync = { version = "0.1.0", features = ["rpc-client", "rest-client", "tokio"] }
 lightning-transaction-sync = { version = "0.1.0", features = ["esplora-async-https", "time", "electrum"] }
 lightning-liquidity = { version = "0.1.0", features = ["std"] }
 

bindings/ldk_node.udl

@@ -78,6 +78,7 @@ interface Builder {
 	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_chain_source_bitcoind_rest(string rest_host, u16 rest_port, 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);
 	void set_liquidity_source_lsps1(PublicKey node_id, SocketAddress address, string? token);

docker-compose.yml

@@ -13,10 +13,11 @@ services:
         "-rpcbind=0.0.0.0",
         "-rpcuser=user",
         "-rpcpassword=pass",
-        "-fallbackfee=0.00001"
+        "-fallbackfee=0.00001",
+        "-rest"
       ]
     ports:
-      - "18443:18443"  # Regtest RPC port
+      - "18443:18443"  # Regtest REST and RPC port
       - "18444:18444"  # Regtest P2P port
     networks:
       - bitcoin-electrs

src/builder.rs

@@ -7,8 +7,9 @@
 
 use crate::chain::{ChainSource, DEFAULT_ESPLORA_SERVER_URL};
 use crate::config::{
-	default_user_config, may_announce_channel, AnnounceError, Config, ElectrumSyncConfig,
-	EsploraSyncConfig, DEFAULT_LOG_FILENAME, DEFAULT_LOG_LEVEL, WALLET_KEYS_SEED_LEN,
+	default_user_config, may_announce_channel, AnnounceError, BitcoindRestClientConfig, Config,
+	ElectrumSyncConfig, EsploraSyncConfig, DEFAULT_LOG_FILENAME, DEFAULT_LOG_LEVEL,
+	WALLET_KEYS_SEED_LEN,
 };
 
 use crate::connection::ConnectionManager;
@@ -84,9 +85,21 @@ 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 },
+	Esplora {
+		server_url: String,
+		sync_config: Option<EsploraSyncConfig>,
+	},
+	Electrum {
+		server_url: String,
+		sync_config: Option<ElectrumSyncConfig>,
+	},
+	Bitcoind {
+		rpc_host: String,
+		rpc_port: u16,
+		rpc_user: String,
+		rpc_password: String,
+		rest_client_config: Option<BitcoindRestClientConfig>,
+	},
 }
 
 #[derive(Debug, Clone)]
@@ -299,13 +312,48 @@ impl NodeBuilder {
 		self
 	}
 
-	/// Configures the [`Node`] instance to source its chain data from the given Bitcoin Core RPC
-	/// endpoint.
+	/// Configures the [`Node`] instance to connect to a Bitcoin Core node via RPC.
+	///
+	/// This method establishes an RPC connection that enables all essential chain operations including
+	/// transaction broadcasting and chain data synchronization.
+	///
+	/// ## Parameters:
+	/// * `rpc_host`, `rpc_port`, `rpc_user`, `rpc_password` - Required parameters for the Bitcoin Core RPC
+	///   connection.
 	pub fn set_chain_source_bitcoind_rpc(
 		&mut self, rpc_host: String, rpc_port: u16, rpc_user: String, rpc_password: String,
 	) -> &mut Self {
-		self.chain_data_source_config =
-			Some(ChainDataSourceConfig::BitcoindRpc { rpc_host, rpc_port, rpc_user, rpc_password });
+		self.chain_data_source_config = Some(ChainDataSourceConfig::Bitcoind {
+			rpc_host,
+			rpc_port,
+			rpc_user,
+			rpc_password,
+			rest_client_config: None,
+		});
+		self
+	}
+
+	/// Configures the [`Node`] instance to synchronize chain data from a Bitcoin Core REST endpoint.
+	///
+	/// This method enables chain data synchronization via Bitcoin Core's REST interface. We pass
+	/// additional RPC configuration to non-REST-supported API calls like transaction broadcasting.
+	///
+	/// ## Parameters:
+	/// * `rest_host`, `rest_port` - Required parameters for the Bitcoin Core REST connection.
+	/// * `rpc_host`, `rpc_port`, `rpc_user`, `rpc_password` - Required parameters for the Bitcoin Core RPC
+	///   connection
+	pub fn set_chain_source_bitcoind_rest(
+		&mut self, rest_host: String, rest_port: u16, rpc_host: String, rpc_port: u16,
+		rpc_user: String, rpc_password: String,
+	) -> &mut Self {
+		self.chain_data_source_config = Some(ChainDataSourceConfig::Bitcoind {
+			rpc_host,
+			rpc_port,
+			rpc_user,
+			rpc_password,
+			rest_client_config: Some(BitcoindRestClientConfig { rest_host, rest_port }),
+		});
+
 		self
 	}
 
@@ -716,8 +764,15 @@ impl ArcedNodeBuilder {
 		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.
+	/// Configures the [`Node`] instance to connect to a Bitcoin Core node via RPC.
+	///
+	/// This method establishes an RPC connection that enables all essential chain operations including
+	/// transaction broadcasting and chain data synchronization. RPC is the minimum required configuration
+	/// for Bitcoin Core chain interactions and must be set up before any other Bitcoin Core connection options.
+	///
+	/// ## Parameters:
+	/// * `rpc_host`, `rpc_port`, `rpc_user`, `rpc_password` - Required parameters for the Bitcoin Core RPC
+	///   connection.
 	pub fn set_chain_source_bitcoind_rpc(
 		&self, rpc_host: String, rpc_port: u16, rpc_user: String, rpc_password: String,
 	) {
@@ -729,6 +784,29 @@ impl ArcedNodeBuilder {
 		);
 	}
 
+	/// Configures the [`Node`] instance to synchronize chain data from a Bitcoin Core REST endpoint.
+	///
+	/// This method enables chain data synchronization via Bitcoin Core's REST interface.
+	/// It must be called after [`set_chain_source_bitcoind_rpc`] because REST is used only for chain
+	/// synchronization, while RPC is still required for other essential operations like transaction
+	/// broadcasting.
+	///
+	/// ## Parameters:
+	/// * `rest_host`, `rest_port` - Required parameters for the Bitcoin Core REST connection.
+	pub fn set_chain_source_bitcoind_rest(
+		&self, rest_host: String, rest_port: u16, rpc_host: String, rpc_port: u16,
+		rpc_user: String, rpc_password: String,
+	) {
+		self.inner.write().unwrap().set_chain_source_bitcoind_rest(
+			rest_host,
+			rest_port,
+			rpc_host,
+			rpc_port,
+			rpc_user,
+			rpc_password,
+		);
+	}
+
 	/// Configures the [`Node`] instance to source its gossip data from the Lightning peer-to-peer
 	/// network.
 	pub fn set_gossip_source_p2p(&self) {
@@ -1068,8 +1146,14 @@ fn build_with_store_internal(
 				Arc::clone(&node_metrics),
 			))
 		},
-		Some(ChainDataSourceConfig::BitcoindRpc { rpc_host, rpc_port, rpc_user, rpc_password }) => {
-			Arc::new(ChainSource::new_bitcoind_rpc(
+		Some(ChainDataSourceConfig::Bitcoind {
+			rpc_host,
+			rpc_port,
+			rpc_user,
+			rpc_password,
+			rest_client_config,
+		}) => match rest_client_config {
+			Some(rest_client_config) => Arc::new(ChainSource::new_bitcoind_rest(
 				rpc_host.clone(),
 				*rpc_port,
 				rpc_user.clone(),
@@ -1079,10 +1163,25 @@ fn build_with_store_internal(
 				Arc::clone(&tx_broadcaster),
 				Arc::clone(&kv_store),
 				Arc::clone(&config),
+				rest_client_config.clone(),
 				Arc::clone(&logger),
 				Arc::clone(&node_metrics),
-			))
+			)),
+			None => Arc::new(ChainSource::new_bitcoind_rpc(
+				rpc_host.clone(),
+				*rpc_port,
+				rpc_user.clone(),
+				rpc_password.clone(),
+				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),
+			)),
 		},
+
 		None => {
 			// Default to Esplora client.
 			let server_url = DEFAULT_ESPLORA_SERVER_URL.to_string();