Use DeferredChainMonitor for non-VSS storage backends

This change uses LDK's DeferredChainMonitor for local storage backends
(SQLite, filesystem) instead of the regular ChainMonitor. The deferred
variant queues watch_channel and update_channel operations for later
flushing, enabling safe persistence ordering where the ChannelManager
is persisted before the channel monitors. This ensures crash safety.

VSS storage backends continue to use the regular ChainMonitor since
VSS handles its own persistence ordering.

The implementation:
- Adds ChainMonitor enum that wraps both Regular and Deferred variants
- Implements all required traits (Watch, Listen, Confirm, AChainMonitor,
  BaseMessageHandler, SendOnlyMessageHandler, EventsProvider) for the enum
- Adds use_deferred_chain_monitor parameter to build_with_store_internal
- Updates VSS build methods to use regular ChainMonitor (false)
- Updates non-VSS build methods to use DeferredChainMonitor (true)

Co-Authored-By: Claude Opus 4.5 <[email protected]>

Author: joostjager

Cargo.toml

@@ -169,15 +169,15 @@ harness = false
 #vss-client-ng = { path = "../vss-client" }
 #vss-client-ng = { git = "https://github.com/lightningdevkit/vss-client", branch = "main" }
 #
-#[patch."https://github.com/lightningdevkit/rust-lightning"]
-#lightning = { path = "../rust-lightning/lightning" }
-#lightning-types = { path = "../rust-lightning/lightning-types" }
-#lightning-invoice = { path = "../rust-lightning/lightning-invoice" }
-#lightning-net-tokio = { path = "../rust-lightning/lightning-net-tokio" }
-#lightning-persister = { path = "../rust-lightning/lightning-persister" }
-#lightning-background-processor = { path = "../rust-lightning/lightning-background-processor" }
-#lightning-rapid-gossip-sync = { path = "../rust-lightning/lightning-rapid-gossip-sync" }
-#lightning-block-sync = { path = "../rust-lightning/lightning-block-sync" }
-#lightning-transaction-sync = { path = "../rust-lightning/lightning-transaction-sync" }
-#lightning-liquidity = { path = "../rust-lightning/lightning-liquidity" }
-#lightning-macros = { path = "../rust-lightning/lightning-macros" }
+[patch."https://github.com/lightningdevkit/rust-lightning"]
+lightning = { git = "https://github.com/joostjager/rust-lightning", branch = "chain-mon-deferred-writes" }
+lightning-types = { git = "https://github.com/joostjager/rust-lightning", branch = "chain-mon-deferred-writes" }
+lightning-invoice = { git = "https://github.com/joostjager/rust-lightning", branch = "chain-mon-deferred-writes" }
+lightning-net-tokio = { git = "https://github.com/joostjager/rust-lightning", branch = "chain-mon-deferred-writes" }
+lightning-persister = { git = "https://github.com/joostjager/rust-lightning", branch = "chain-mon-deferred-writes" }
+lightning-background-processor = { git = "https://github.com/joostjager/rust-lightning", branch = "chain-mon-deferred-writes" }
+lightning-rapid-gossip-sync = { git = "https://github.com/joostjager/rust-lightning", branch = "chain-mon-deferred-writes" }
+lightning-block-sync = { git = "https://github.com/joostjager/rust-lightning", branch = "chain-mon-deferred-writes" }
+lightning-transaction-sync = { git = "https://github.com/joostjager/rust-lightning", branch = "chain-mon-deferred-writes" }
+lightning-liquidity = { git = "https://github.com/joostjager/rust-lightning", branch = "chain-mon-deferred-writes" }
+lightning-macros = { git = "https://github.com/joostjager/rust-lightning", branch = "chain-mon-deferred-writes" }

src/builder.rs

@@ -599,7 +599,8 @@ impl NodeBuilder {
 			BuildError::KVStoreSetupFailed
 		})?;
 
-		self.build_with_store(node_entropy, vss_store)
+		// VSS handles its own persistence ordering, so don't use deferred chain monitor
+		self.build_with_store_internal(node_entropy, vss_store, false)
 	}
 
 	/// Builds a [`Node`] instance with a [VSS] backend and according to the options
@@ -626,7 +627,8 @@ impl NodeBuilder {
 			BuildError::KVStoreSetupFailed
 		})?;
 
-		self.build_with_store(node_entropy, vss_store)
+		// VSS handles its own persistence ordering, so don't use deferred chain monitor
+		self.build_with_store_internal(node_entropy, vss_store, false)
 	}
 
 	/// Builds a [`Node`] instance with a [VSS] backend and according to the options
@@ -651,12 +653,25 @@ impl NodeBuilder {
 			BuildError::KVStoreSetupFailed
 		})?;
 
-		self.build_with_store(node_entropy, vss_store)
+		// VSS handles its own persistence ordering, so don't use deferred chain monitor
+		self.build_with_store_internal(node_entropy, vss_store, false)
 	}
 
 	/// Builds a [`Node`] instance according to the options previously configured.
+	///
+	/// For local storage backends (SQLite, filesystem), this uses `DeferredChainMonitor` which
+	/// enables safe persistence ordering where the `ChannelManager` is persisted before the
+	/// channel monitors.
 	pub fn build_with_store<S: SyncAndAsyncKVStore + Send + Sync + 'static>(
 		&self, node_entropy: NodeEntropy, kv_store: S,
+	) -> Result<Node, BuildError> {
+		// Use deferred chain monitor for local storage backends
+		self.build_with_store_internal(node_entropy, kv_store, true)
+	}
+
+	/// Internal method that builds a node with configurable chain monitor type.
+	fn build_with_store_internal<S: SyncAndAsyncKVStore + Send + Sync + 'static>(
+		&self, node_entropy: NodeEntropy, kv_store: S, use_deferred_chain_monitor: bool,
 	) -> Result<Node, BuildError> {
 		let logger = setup_logger(&self.log_writer_config, &self.config)?;
 
@@ -683,6 +698,7 @@ impl NodeBuilder {
 			runtime,
 			logger,
 			Arc::new(DynStoreWrapper(kv_store)),
+			use_deferred_chain_monitor,
 		)
 	}
 }
@@ -1028,13 +1044,18 @@ impl ArcedNodeBuilder {
 }
 
 /// Builds a [`Node`] instance according to the options previously configured.
+///
+/// If `use_deferred_chain_monitor` is true, uses `DeferredChainMonitor` which defers monitor
+/// operations until explicitly flushed. This enables safe persistence ordering where the
+/// `ChannelManager` is persisted before the channel monitors. This should be used for local
+/// storage backends (SQLite, etc.) but NOT for VSS which handles its own persistence ordering.
 fn build_with_store_internal(
 	config: Arc<Config>, chain_data_source_config: Option<&ChainDataSourceConfig>,
 	gossip_source_config: Option<&GossipSourceConfig>,
 	liquidity_source_config: Option<&LiquiditySourceConfig>,
 	pathfinding_scores_sync_config: Option<&PathfindingScoresSyncConfig>,
 	async_payments_role: Option<AsyncPaymentsRole>, seed_bytes: [u8; 64], runtime: Arc<Runtime>,
-	logger: Arc<Logger>, kv_store: Arc<DynStore>,
+	logger: Arc<Logger>, kv_store: Arc<DynStore>, use_deferred_chain_monitor: bool,
 ) -> Result<Node, BuildError> {
 	optionally_install_rustls_cryptoprovider();
 
@@ -1334,15 +1355,29 @@ fn build_with_store_internal(
 	));
 
 	// Initialize the ChainMonitor
-	let chain_monitor: Arc<ChainMonitor> = Arc::new(chainmonitor::ChainMonitor::new(
-		Some(Arc::clone(&chain_source)),
-		Arc::clone(&tx_broadcaster),
-		Arc::clone(&logger),
-		Arc::clone(&fee_estimator),
-		Arc::clone(&persister),
-		Arc::clone(&keys_manager),
-		peer_storage_key,
-	));
+	// Use DeferredChainMonitor for local storage backends to enable safe persistence ordering.
+	// VSS handles its own persistence ordering, so it uses the regular ChainMonitor.
+	let chain_monitor: Arc<ChainMonitor> = if use_deferred_chain_monitor {
+		Arc::new(ChainMonitor::Deferred(lightning::chain::deferred::DeferredChainMonitor::new(
+			Some(Arc::clone(&chain_source)),
+			Arc::clone(&tx_broadcaster),
+			Arc::clone(&logger),
+			Arc::clone(&fee_estimator),
+			Arc::clone(&persister),
+			Arc::clone(&keys_manager),
+			peer_storage_key,
+		)))
+	} else {
+		Arc::new(ChainMonitor::Regular(chainmonitor::ChainMonitor::new(
+			Some(Arc::clone(&chain_source)),
+			Arc::clone(&tx_broadcaster),
+			Arc::clone(&logger),
+			Arc::clone(&fee_estimator),
+			Arc::clone(&persister),
+			Arc::clone(&keys_manager),
+			peer_storage_key,
+		)))
+	};
 
 	// Initialize the network graph, scorer, and router
 	let network_graph = match network_graph_res {