Add bip157 dependency and CBF builder configuration

febyeji · febyeji · commit 4cb661819e49 · 2026-03-15T05:31:59.000+09:00
diff --git a/Cargo.toml b/Cargo.toml
@@ -54,6 +54,7 @@ lightning-macros = { git = "https://github.com/lightningdevkit/rust-lightning",
 bdk_chain = { version = "0.23.0", default-features = false, features = ["std"] }
 bdk_esplora = { version = "0.22.0", default-features = false, features = ["async-https-rustls", "tokio"]}
 bdk_electrum = { version = "0.23.0", default-features = false, features = ["use-rustls-ring"]}
+bip157 = { version = "0.4.2", default-features = false }
 bdk_wallet = { version = "2.3.0", default-features = false, features = ["std", "keys-bip39"]}
 
 bitreq = { version = "0.3", default-features = false, features = ["async-https", "json-using-serde"] }
diff --git a/src/builder.rs b/src/builder.rs
@@ -45,7 +45,7 @@ use vss_client::headers::VssHeaderProvider;
 use crate::chain::ChainSource;
 use crate::config::{
 	default_user_config, may_announce_channel, AnnounceError, AsyncPaymentsRole,
-	BitcoindRestClientConfig, Config, ElectrumSyncConfig, EsploraSyncConfig,
+	BitcoindRestClientConfig, CbfSyncConfig, Config, ElectrumSyncConfig, EsploraSyncConfig,
 	DEFAULT_ESPLORA_SERVER_URL, DEFAULT_LOG_FILENAME, DEFAULT_LOG_LEVEL,
 };
 use crate::connection::ConnectionManager;
@@ -105,6 +105,10 @@ enum ChainDataSourceConfig {
 		rpc_password: String,
 		rest_client_config: Option<BitcoindRestClientConfig>,
 	},
+	Cbf {
+		peers: Vec<String>,
+		sync_config: Option<CbfSyncConfig>,
+	},
 }
 
 #[derive(Debug, Clone)]
@@ -376,6 +380,21 @@ impl NodeBuilder {
 		self
 	}
 
+	/// Configures the [`Node`] instance to source its chain data via BIP 157 compact block
+	/// filters.
+	///
+	/// `peers` is an optional list of peer addresses to connect to for sourcing compact block
+	/// filters. If empty, the node will discover peers via DNS seeds.
+	///
+	/// If no `sync_config` is given, default values are used. See [`CbfSyncConfig`] for more
+	/// information.
+	pub fn set_chain_source_cbf(
+		&mut self, peers: Vec<String>, sync_config: Option<CbfSyncConfig>,
+	) -> &mut Self {
+		self.chain_data_source_config = Some(ChainDataSourceConfig::Cbf { peers, sync_config });
+		self
+	}
+
 	/// Configures the [`Node`] instance to source its gossip data from the Lightning peer-to-peer
 	/// network.
 	pub fn set_gossip_source_p2p(&mut self) -> &mut Self {
@@ -1255,6 +1274,20 @@ fn build_with_store_internal(
 			}),
 		},
 
+		Some(ChainDataSourceConfig::Cbf { peers, sync_config }) => {
+			let sync_config = sync_config.clone().unwrap_or(CbfSyncConfig::default());
+			ChainSource::new_cbf(
+				peers.clone(),
+				sync_config,
+				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();
diff --git a/src/chain/cbf.rs b/src/chain/cbf.rs
@@ -0,0 +1,93 @@
+// 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 std::sync::{Arc, RwLock};
+
+use bitcoin::{Script, Transaction, Txid};
+use lightning::chain::WatchedOutput;
+
+use crate::config::{CbfSyncConfig, Config};
+use crate::fee_estimator::OnchainFeeEstimator;
+use crate::logger::{log_error, LdkLogger, Logger};
+use crate::runtime::Runtime;
+use crate::types::{ChainMonitor, ChannelManager, DynStore, Sweeper, Wallet};
+use crate::{Error, NodeMetrics};
+
+pub(super) struct CbfChainSource {
+	/// Peer addresses for sourcing compact block filters via P2P.
+	peers: Vec<String>,
+	/// User-provided sync configuration (timeouts, background sync intervals).
+	pub(super) sync_config: CbfSyncConfig,
+	/// Shared fee rate estimator, updated by this chain source.
+	fee_estimator: Arc<OnchainFeeEstimator>,
+	/// Persistent key-value store for node metrics.
+	kv_store: Arc<DynStore>,
+	/// Node configuration (network, storage path, etc.).
+	config: Arc<Config>,
+	/// Logger instance.
+	logger: Arc<Logger>,
+	/// Shared node metrics (sync timestamps, etc.).
+	node_metrics: Arc<RwLock<NodeMetrics>>,
+}
+
+impl CbfChainSource {
+	pub(crate) fn new(
+		peers: Vec<String>, sync_config: CbfSyncConfig, fee_estimator: Arc<OnchainFeeEstimator>,
+		kv_store: Arc<DynStore>, config: Arc<Config>, logger: Arc<Logger>,
+		node_metrics: Arc<RwLock<NodeMetrics>>,
+	) -> Self {
+		Self { peers, sync_config, fee_estimator, kv_store, config, logger, node_metrics }
+	}
+
+	/// Start the bip157 node and spawn background tasks for event processing.
+	pub(crate) fn start(&self, _runtime: Arc<Runtime>) {
+		log_error!(self.logger, "CBF chain source start is not yet implemented.");
+	}
+
+	/// Shut down the bip157 node and stop all background tasks.
+	pub(crate) fn stop(&self) {
+		log_error!(self.logger, "CBF chain source stop is not yet implemented.");
+	}
+
+	/// Sync the on-chain wallet by scanning compact block filters for relevant transactions.
+	pub(crate) async fn sync_onchain_wallet(
+		&self, _onchain_wallet: Arc<Wallet>,
+	) -> Result<(), Error> {
+		log_error!(self.logger, "On-chain wallet sync via CBF is not yet implemented.");
+		Err(Error::WalletOperationFailed)
+	}
+
+	/// Sync the Lightning wallet by confirming channel transactions via compact block filters.
+	pub(crate) async fn sync_lightning_wallet(
+		&self, _channel_manager: Arc<ChannelManager>, _chain_monitor: Arc<ChainMonitor>,
+		_output_sweeper: Arc<Sweeper>,
+	) -> Result<(), Error> {
+		log_error!(self.logger, "Lightning wallet sync via CBF is not yet implemented.");
+		Err(Error::TxSyncFailed)
+	}
+
+	/// Estimate fee rates from recent block data.
+	pub(crate) async fn update_fee_rate_estimates(&self) -> Result<(), Error> {
+		log_error!(self.logger, "Fee rate estimation via CBF is not yet implemented.");
+		Err(Error::FeerateEstimationUpdateFailed)
+	}
+
+	/// Broadcast a package of transactions via the P2P network.
+	pub(crate) async fn process_broadcast_package(&self, _package: Vec<Transaction>) {
+		log_error!(self.logger, "Transaction broadcasting via CBF is not yet implemented.");
+	}
+
+	/// Register a transaction script for Lightning channel monitoring.
+	pub(crate) fn register_tx(&self, _txid: &Txid, _script_pubkey: &Script) {
+		log_error!(self.logger, "CBF register_tx is not yet implemented.");
+	}
+
+	/// Register a watched output script for Lightning channel monitoring.
+	pub(crate) fn register_output(&self, _output: WatchedOutput) {
+		log_error!(self.logger, "CBF register_output is not yet implemented.");
+	}
+}
diff --git a/src/chain/mod.rs b/src/chain/mod.rs
@@ -6,6 +6,7 @@
 // accordance with one or both of these licenses.
 
 pub(crate) mod bitcoind;
+mod cbf;
 mod electrum;
 mod esplora;
 
@@ -17,11 +18,12 @@ use bitcoin::{Script, Txid};
 use lightning::chain::{BestBlock, Filter};
 
 use crate::chain::bitcoind::{BitcoindChainSource, UtxoSourceClient};
+use crate::chain::cbf::CbfChainSource;
 use crate::chain::electrum::ElectrumChainSource;
 use crate::chain::esplora::EsploraChainSource;
 use crate::config::{
-	BackgroundSyncConfig, BitcoindRestClientConfig, Config, ElectrumSyncConfig, EsploraSyncConfig,
-	WALLET_SYNC_INTERVAL_MINIMUM_SECS,
+	BackgroundSyncConfig, BitcoindRestClientConfig, CbfSyncConfig, Config, ElectrumSyncConfig,
+	EsploraSyncConfig, WALLET_SYNC_INTERVAL_MINIMUM_SECS,
 };
 use crate::fee_estimator::OnchainFeeEstimator;
 use crate::logger::{log_debug, log_info, log_trace, LdkLogger, Logger};
@@ -93,6 +95,7 @@ enum ChainSourceKind {
 	Esplora(EsploraChainSource),
 	Electrum(ElectrumChainSource),
 	Bitcoind(BitcoindChainSource),
+	Cbf(CbfChainSource),
 }
 
 impl ChainSource {
@@ -184,11 +187,33 @@ impl ChainSource {
 		(Self { kind, registered_txids, tx_broadcaster, logger }, best_block)
 	}
 
+	pub(crate) fn new_cbf(
+		peers: Vec<String>, sync_config: CbfSyncConfig, fee_estimator: Arc<OnchainFeeEstimator>,
+		tx_broadcaster: Arc<Broadcaster>, kv_store: Arc<DynStore>, config: Arc<Config>,
+		logger: Arc<Logger>, node_metrics: Arc<RwLock<NodeMetrics>>,
+	) -> (Self, Option<BestBlock>) {
+		let cbf_chain_source = CbfChainSource::new(
+			peers,
+			sync_config,
+			fee_estimator,
+			kv_store,
+			config,
+			Arc::clone(&logger),
+			node_metrics,
+		);
+		let kind = ChainSourceKind::Cbf(cbf_chain_source);
+		let registered_txids = Mutex::new(Vec::new());
+		(Self { kind, registered_txids, tx_broadcaster, logger }, None)
+	}
+
 	pub(crate) fn start(&self, runtime: Arc<Runtime>) -> Result<(), Error> {
 		match &self.kind {
 			ChainSourceKind::Electrum(electrum_chain_source) => {
 				electrum_chain_source.start(runtime)?
 			},
+			ChainSourceKind::Cbf(cbf_chain_source) => {
+				cbf_chain_source.start(runtime);
+			},
 			_ => {
 				// Nothing to do for other chain sources.
 			},
@@ -199,6 +224,9 @@ impl ChainSource {
 	pub(crate) fn stop(&self) {
 		match &self.kind {
 			ChainSourceKind::Electrum(electrum_chain_source) => electrum_chain_source.stop(),
+			ChainSourceKind::Cbf(cbf_chain_source) => {
+				cbf_chain_source.stop();
+			},
 			_ => {
 				// Nothing to do for other chain sources.
 			},
@@ -210,6 +238,7 @@ impl ChainSource {
 			ChainSourceKind::Bitcoind(bitcoind_chain_source) => {
 				Some(bitcoind_chain_source.as_utxo_source())
 			},
+			ChainSourceKind::Cbf { .. } => None,
 			_ => None,
 		}
 	}
@@ -223,6 +252,7 @@ impl ChainSource {
 			ChainSourceKind::Esplora(_) => true,
 			ChainSourceKind::Electrum { .. } => true,
 			ChainSourceKind::Bitcoind { .. } => false,
+			ChainSourceKind::Cbf { .. } => false,
 		}
 	}
 
@@ -289,6 +319,28 @@ impl ChainSource {
 					)
 					.await
 			},
+			ChainSourceKind::Cbf(cbf_chain_source) => {
+				if let Some(background_sync_config) =
+					cbf_chain_source.sync_config.background_sync_config.as_ref()
+				{
+					self.start_tx_based_sync_loop(
+						stop_sync_receiver,
+						onchain_wallet,
+						channel_manager,
+						chain_monitor,
+						output_sweeper,
+						background_sync_config,
+						Arc::clone(&self.logger),
+					)
+					.await
+				} else {
+					log_info!(
+						self.logger,
+						"Background syncing is disabled. Manual syncing required for onchain wallet, lightning wallet, and fee rate updates.",
+					);
+					return;
+				}
+			},
 		}
 	}
 
@@ -368,6 +420,9 @@ impl ChainSource {
 				// `ChainPoller`. So nothing to do here.
 				unreachable!("Onchain wallet will be synced via chain polling")
 			},
+			ChainSourceKind::Cbf(cbf_chain_source) => {
+				cbf_chain_source.sync_onchain_wallet(onchain_wallet).await
+			},
 		}
 	}
 
@@ -393,6 +448,11 @@ impl ChainSource {
 				// `ChainPoller`. So nothing to do here.
 				unreachable!("Lightning wallet will be synced via chain polling")
 			},
+			ChainSourceKind::Cbf(cbf_chain_source) => {
+				cbf_chain_source
+					.sync_lightning_wallet(channel_manager, chain_monitor, output_sweeper)
+					.await
+			},
 		}
 	}
 
@@ -421,6 +481,10 @@ impl ChainSource {
 					)
 					.await
 			},
+			ChainSourceKind::Cbf { .. } => {
+				// In CBF mode we sync wallets via compact block filters.
+				unreachable!("Listeners will be synced via compact block filter syncing")
+			},
 		}
 	}
 
@@ -435,6 +499,9 @@ impl ChainSource {
 			ChainSourceKind::Bitcoind(bitcoind_chain_source) => {
 				bitcoind_chain_source.update_fee_rate_estimates().await
 			},
+			ChainSourceKind::Cbf(cbf_chain_source) => {
+				cbf_chain_source.update_fee_rate_estimates().await
+			},
 		}
 	}
 
@@ -463,6 +530,9 @@ impl ChainSource {
 						ChainSourceKind::Bitcoind(bitcoind_chain_source) => {
 							bitcoind_chain_source.process_broadcast_package(next_package).await
 						},
+						ChainSourceKind::Cbf(cbf_chain_source) => {
+							cbf_chain_source.process_broadcast_package(next_package).await
+						},
 					}
 				}
 			}
@@ -481,6 +551,9 @@ impl Filter for ChainSource {
 				electrum_chain_source.register_tx(txid, script_pubkey)
 			},
 			ChainSourceKind::Bitcoind { .. } => (),
+			ChainSourceKind::Cbf(cbf_chain_source) => {
+				cbf_chain_source.register_tx(txid, script_pubkey)
+			},
 		}
 	}
 	fn register_output(&self, output: lightning::chain::WatchedOutput) {
@@ -492,6 +565,7 @@ impl Filter for ChainSource {
 				electrum_chain_source.register_output(output)
 			},
 			ChainSourceKind::Bitcoind { .. } => (),
+			ChainSourceKind::Cbf(cbf_chain_source) => cbf_chain_source.register_output(output),
 		}
 	}
 }
diff --git a/src/config.rs b/src/config.rs
@@ -478,6 +478,32 @@ impl Default for ElectrumSyncConfig {
 	}
 }
 
+/// Configuration for syncing via BIP 157 compact block filters.
+///
+/// Background syncing is enabled by default, using the default values specified in
+/// [`BackgroundSyncConfig`].
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct CbfSyncConfig {
+	/// 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.
+	///
+	/// [`Node::sync_wallets`]: crate::Node::sync_wallets
+	pub background_sync_config: Option<BackgroundSyncConfig>,
+	/// Sync timeouts configuration.
+	pub timeouts_config: SyncTimeoutsConfig,
+}
+
+impl Default for CbfSyncConfig {
+	fn default() -> Self {
+		Self {
+			background_sync_config: Some(BackgroundSyncConfig::default()),
+			timeouts_config: SyncTimeoutsConfig::default(),
+		}
+	}
+}
+
 /// Configuration for syncing with Bitcoin Core backend via REST.
 #[derive(Debug, Clone)]
 pub struct BitcoindRestClientConfig {
