feat: accept stale channel monitors for recovery from monitor desync

When a channel monitor's update_id falls behind the ChannelManager
(e.g. after a migration overwrote newer data with stale backup data),
LDK refuses to start with DangerousValue. This adds a recovery path:

- Builder: new `set_accept_stale_channel_monitors(bool)` flag
- Build: passes flag to ChannelManagerReadArgs, which force-syncs
  stale monitor update_ids instead of returning DangerousValue
- Startup: when flag is set, defers chain sync while sending probes
  on all channels to trigger commitment round-trips that heal the
  stale monitor state. Polls monitor update_ids with 60s timeout
  and retries probes every 10s for late-connecting peers.

The probe-triggered commitment round-trip provides:
- LatestHolderCommitmentTXInfo (correct current commitment state)
- CommitmentSecret (recovers all gap revocation secrets via the
  derivation tree)

Depends on: ben-kaufman/rust-lightning#fix/accept-stale-channel-monitors

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: ben-kaufman

Cargo.toml

@@ -124,18 +124,18 @@ check-cfg = [
 name = "payments"
 harness = false
 
-#[patch.crates-io]
-#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.crates-io]
+lightning = { git = "https://github.com/ben-kaufman/rust-lightning", branch = "fix/accept-stale-channel-monitors" }
+lightning-types = { git = "https://github.com/ben-kaufman/rust-lightning", branch = "fix/accept-stale-channel-monitors" }
+lightning-invoice = { git = "https://github.com/ben-kaufman/rust-lightning", branch = "fix/accept-stale-channel-monitors" }
+lightning-net-tokio = { git = "https://github.com/ben-kaufman/rust-lightning", branch = "fix/accept-stale-channel-monitors" }
+lightning-persister = { git = "https://github.com/ben-kaufman/rust-lightning", branch = "fix/accept-stale-channel-monitors" }
+lightning-background-processor = { git = "https://github.com/ben-kaufman/rust-lightning", branch = "fix/accept-stale-channel-monitors" }
+lightning-rapid-gossip-sync = { git = "https://github.com/ben-kaufman/rust-lightning", branch = "fix/accept-stale-channel-monitors" }
+lightning-block-sync = { git = "https://github.com/ben-kaufman/rust-lightning", branch = "fix/accept-stale-channel-monitors" }
+lightning-transaction-sync = { git = "https://github.com/ben-kaufman/rust-lightning", branch = "fix/accept-stale-channel-monitors" }
+lightning-liquidity = { git = "https://github.com/ben-kaufman/rust-lightning", branch = "fix/accept-stale-channel-monitors" }
+lightning-macros = { git = "https://github.com/ben-kaufman/rust-lightning", branch = "fix/accept-stale-channel-monitors" }
 
 #lightning = { git = "https://github.com/lightningdevkit/rust-lightning", branch = "main" }
 #lightning-types = { git = "https://github.com/lightningdevkit/rust-lightning", branch = "main" }

bindings/ldk_node.udl

@@ -109,6 +109,7 @@ interface Builder {
 	void set_entropy_seed_bytes(sequence<u8> seed_bytes);
 	void set_entropy_bip39_mnemonic(Mnemonic mnemonic, string? passphrase);
 	void set_channel_data_migration(ChannelDataMigration migration);
+	void set_accept_stale_channel_monitors(boolean accept);
 	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);

src/builder.rs

@@ -279,6 +279,7 @@ pub struct NodeBuilder {
 	runtime_handle: Option<tokio::runtime::Handle>,
 	pathfinding_scores_sync_config: Option<PathfindingScoresSyncConfig>,
 	channel_data_migration: Option<ChannelDataMigration>,
+	accept_stale_channel_monitors: bool,
 }
 
 impl NodeBuilder {
@@ -309,6 +310,7 @@ impl NodeBuilder {
 			async_payments_role: None,
 			pathfinding_scores_sync_config,
 			channel_data_migration,
+			accept_stale_channel_monitors: false,
 		}
 	}
 
@@ -361,6 +363,19 @@ impl NodeBuilder {
 		self
 	}
 
+	/// Accept stale channel monitors on startup instead of failing with `DangerousValue`.
+	///
+	/// When enabled, stale monitors have their `update_id` force-synced to match the
+	/// `ChannelManager`. The monitor's commitment state remains stale until the next real
+	/// channel update (e.g. a fee update round-trip after reconnecting to the peer).
+	///
+	/// Use this for recovery after monitor data was overwritten by a migration or backup restore.
+	/// Chain sync should be delayed until monitors are healed via a commitment round-trip.
+	pub fn set_accept_stale_channel_monitors(&mut self, accept: bool) -> &mut Self {
+		self.accept_stale_channel_monitors = accept;
+		self
+	}
+
 	/// Configures the [`Node`] instance to source its chain data from the given Esplora server.
 	///
 	/// If no `sync_config` is given, default values are used. See [`EsploraSyncConfig`] for more
@@ -813,6 +828,7 @@ impl NodeBuilder {
 			logger,
 			Arc::new(vss_store),
 			self.channel_data_migration.as_ref(),
+			self.accept_stale_channel_monitors,
 		)
 	}
 
@@ -848,6 +864,7 @@ impl NodeBuilder {
 			logger,
 			kv_store,
 			self.channel_data_migration.as_ref(),
+			self.accept_stale_channel_monitors,
 		)
 	}
 }
@@ -917,6 +934,13 @@ impl ArcedNodeBuilder {
 		self.inner.write().unwrap().set_channel_data_migration(migration);
 	}
 
+	/// Accept stale channel monitors on startup instead of failing.
+	///
+	/// See [`NodeBuilder::set_accept_stale_channel_monitors`] for details.
+	pub fn set_accept_stale_channel_monitors(&self, accept: bool) {
+		self.inner.write().unwrap().set_accept_stale_channel_monitors(accept);
+	}
+
 	/// Configures the [`Node`] instance to source its chain data from the given Esplora server.
 	///
 	/// If no `sync_config` is given, default values are used. See [`EsploraSyncConfig`] for more
@@ -1346,7 +1370,7 @@ fn build_with_store_internal(
 	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>,
-	channel_data_migration: Option<&ChannelDataMigration>,
+	channel_data_migration: Option<&ChannelDataMigration>, accept_stale_channel_monitors: bool,
 ) -> Result<Node, BuildError> {
 	optionally_install_rustls_cryptoprovider();
 
@@ -1876,7 +1900,7 @@ fn build_with_store_internal(
 			let mut reader = Cursor::new(res);
 			let channel_monitor_references =
 				channel_monitors.iter().map(|(_, chanmon)| chanmon).collect();
-			let read_args = ChannelManagerReadArgs::new(
+			let mut read_args = ChannelManagerReadArgs::new(
 				Arc::clone(&keys_manager),
 				Arc::clone(&keys_manager),
 				Arc::clone(&keys_manager),
@@ -1889,6 +1913,7 @@ fn build_with_store_internal(
 				user_config,
 				channel_monitor_references,
 			);
+			read_args.accept_stale_channel_monitors = accept_stale_channel_monitors;
 			let (_hash, channel_manager) =
 				<(BlockHash, ChannelManager)>::read(&mut reader, read_args).map_err(|e| {
 					log_error!(logger, "Failed to read channel manager from store: {}", e);
@@ -2250,6 +2275,7 @@ fn build_with_store_internal(
 		async_payments_role,
 		runtime_sync_intervals: Arc::new(RwLock::new(RuntimeSyncIntervals::default())),
 		local_rgs_timestamp,
+		accept_stale_channel_monitors,
 	})
 }