Add filtered backup restoration

Introduce a restore path that copies durable state from a configured
backup store into an empty primary store before normal node
initialization.

This commit:
- Adds a recovery module to define the durable restore scope, filter known
  durable keys, restore them into the primary store, and detect when a
  primary already contains durable state.
- Wires this into the builder by separating backup restore from wallet recovery,
  adding restore-specific build errors, and running restore before any normal
  startup reads.

Also, covers the new logic with unit tests plus an integration test that exercises
backup population, restore into a fresh primary, and successful node boot with
preserved identity.

Author: enigbe

src/builder.rs

@@ -26,7 +26,6 @@ use lightning::chain::{chainmonitor, BestBlock};
 use lightning::ln::channelmanager::{self, ChainParameters, ChannelManagerReadArgs};
 use lightning::ln::msgs::{RoutingMessageHandler, SocketAddress};
 use lightning::ln::peer_handler::{IgnoringMessageHandler, MessageHandler};
-use lightning::log_trace;
 use lightning::onion_message::dns_resolution::DNSResolverMessageHandler;
 use lightning::routing::gossip::NodeAlias;
 use lightning::routing::router::DefaultRouter;
@@ -42,6 +41,7 @@ use lightning::util::persist::{
 };
 use lightning::util::ser::ReadableArgs;
 use lightning::util::sweep::OutputSweeper;
+use lightning::{log_info, log_trace};
 use lightning_dns_resolver::OMDomainResolver;
 use lightning_persister::fs_store::v1::FilesystemStore;
 use vss_client::headers::VssHeaderProvider;
@@ -57,6 +57,7 @@ use crate::entropy::NodeEntropy;
 use crate::event::EventQueue;
 use crate::fee_estimator::OnchainFeeEstimator;
 use crate::gossip::GossipSource;
+use crate::io::recovery::{list_existing_durable_keys, restore_from_backup};
 use crate::io::sqlite_store::SqliteStore;
 use crate::io::tier_store::{BackupMode, BackupRetryQueue, TierStore};
 use crate::io::utils::{
@@ -173,6 +174,12 @@ impl std::fmt::Debug for TierStoreConfig {
 	}
 }
 
+#[derive(Debug, Clone, Copy, Default)]
+struct RecoveryConfig {
+	wallet_recovery: bool,
+	restore_from_backup: bool,
+}
+
 /// An error encountered during building a [`Node`].
 ///
 /// [`Node`]: crate::Node
@@ -219,6 +226,12 @@ pub enum BuildError {
 	AsyncPaymentsConfigMismatch,
 	/// An attempt to setup a DNS Resolver failed.
 	DNSResolverSetupFailed,
+	/// Restore was requested but no backup store is configured.
+	RestoreRequiresBackupStore,
+	/// Restore was requested but the primary store already contains durable data.
+	RestorePrimaryNotEmpty,
+	/// Failed to restore state from the backup store.
+	RestoreFailed,
 }
 
 impl fmt::Display for BuildError {
@@ -256,6 +269,15 @@ impl fmt::Display for BuildError {
 			Self::DNSResolverSetupFailed => {
 				write!(f, "An attempt to setup a DNS resolver has failed.")
 			},
+			Self::RestoreRequiresBackupStore => {
+				write!(f, "Restore from backup was requested but no backup store is configured.")
+			},
+			Self::RestorePrimaryNotEmpty => {
+				write!(f, "Restore from backup was requested but the primary store already contains durable data.")
+			},
+			Self::RestoreFailed => {
+				write!(f, "Failed to restore state from the backup store.")
+			},
 		}
 	}
 }
@@ -311,7 +333,7 @@ pub struct NodeBuilder {
 	tier_store_config: Option<TierStoreConfig>,
 	runtime_handle: Option<tokio::runtime::Handle>,
 	pathfinding_scores_sync_config: Option<PathfindingScoresSyncConfig>,
-	recovery_mode: bool,
+	recovery_config: RecoveryConfig,
 }
 
 impl NodeBuilder {
@@ -330,7 +352,7 @@ impl NodeBuilder {
 		let tier_store_config = None;
 		let runtime_handle = None;
 		let pathfinding_scores_sync_config = None;
-		let recovery_mode = false;
+		let recovery_config = RecoveryConfig::default();
 		Self {
 			config,
 			chain_data_source_config,
@@ -341,7 +363,7 @@ impl NodeBuilder {
 			runtime_handle,
 			async_payments_role: None,
 			pathfinding_scores_sync_config,
-			recovery_mode,
+			recovery_config,
 		}
 	}
 
@@ -643,7 +665,28 @@ impl NodeBuilder {
 	/// This should only be set on first startup when importing an older wallet from a previously
 	/// used [`NodeEntropy`].
 	pub fn set_wallet_recovery_mode(&mut self) -> &mut Self {
-		self.recovery_mode = true;
+		self.recovery_config.wallet_recovery = true;
+		self
+	}
+
+	/// Configures the [`Node`] to restore durable state from the configured backup
+	/// store before normal startup reads occur.
+	///
+	/// This is intended for disaster recovery: when the primary store has been lost
+	/// or corrupted, the node can be rebuilt from a backup store that was previously
+	/// configured via [`set_backup_store`] and actively receiving writes during
+	/// normal operation.
+	///
+	/// The primary store must be empty (contain no durable state) else the build will
+	/// fail with [`BuildError::RestorePrimaryNotEmpty`] if existing durable data
+	/// is detected.
+	///
+	/// Note: this is distinct from wallet recovery mode, which controls whether the
+	/// on-chain wallet is rescanned from genesis on first startup.
+	///
+	/// [`set_backup_store`]: Self::set_backup_store
+	pub fn restore_from_backup(&mut self) -> &mut Self {
+		self.recovery_config.restore_from_backup = true;
 		self
 	}
 
@@ -909,7 +952,7 @@ impl NodeBuilder {
 			self.liquidity_source_config.as_ref(),
 			self.pathfinding_scores_sync_config.as_ref(),
 			self.async_payments_role,
-			self.recovery_mode,
+			self.recovery_config,
 			seed_bytes,
 			runtime,
 			logger,
@@ -1352,10 +1395,38 @@ fn build_with_store_internal(
 	gossip_source_config: Option<&GossipSourceConfig>,
 	liquidity_source_config: Option<&LiquiditySourceConfig>,
 	pathfinding_scores_sync_config: Option<&PathfindingScoresSyncConfig>,
-	async_payments_role: Option<AsyncPaymentsRole>, recovery_mode: bool, seed_bytes: [u8; 64],
-	runtime: Arc<Runtime>, logger: Arc<Logger>, kv_store: Arc<DynStore>,
+	async_payments_role: Option<AsyncPaymentsRole>, recovery_config: RecoveryConfig,
+	seed_bytes: [u8; 64], runtime: Arc<Runtime>, logger: Arc<Logger>, kv_store: Arc<DynStore>,
 	tier_store: Arc<TierStore>,
 ) -> Result<Node, BuildError> {
+	if recovery_config.restore_from_backup {
+		let backup = Arc::clone(
+			&tier_store.backup_store().ok_or(BuildError::RestoreRequiresBackupStore)?.store,
+		);
+
+		let existing_durable_keys = list_existing_durable_keys(&*tier_store.primary_store())
+			.map_err(|e| {
+				log_error!(logger, "Failed to enumerate primary store during restore: {}", e);
+				BuildError::ReadFailed
+			})?;
+
+		if !existing_durable_keys.is_empty() {
+			log_error!(
+				logger,
+				"Restore refused: primary store already contains {} durable key(s)",
+				existing_durable_keys.len()
+			);
+			return Err(BuildError::RestorePrimaryNotEmpty);
+		}
+
+		restore_from_backup(&*tier_store.primary_store(), &*backup).map_err(|e| {
+			log_error!(logger, "Failed to restore from backup: {}", e);
+			BuildError::RestoreFailed
+		})?;
+
+		log_info!(logger, "Successfully restored durable state from backup store");
+	}
+
 	optionally_install_rustls_cryptoprovider();
 
 	if let Err(err) = may_announce_channel(&config) {
@@ -1561,7 +1632,7 @@ fn build_with_store_internal(
 					BuildError::WalletSetupFailed
 				})?;
 
-			if !recovery_mode {
+			if !recovery_config.wallet_recovery {
 				if let Some(best_block) = chain_tip_opt {
 					// Insert the first checkpoint if we have it, to avoid resyncing from genesis.
 					// TODO: Use a proper wallet birthday once BDK supports it.
@@ -2262,7 +2333,11 @@ pub(crate) fn sanitize_alias(alias_str: &str) -> Result<NodeAlias, BuildError> {
 
 #[cfg(test)]
 mod tests {
-	use super::{sanitize_alias, BuildError, NodeAlias};
+	use lightning::util::persist::KVStoreSync;
+
+	use crate::io::test_utils::InMemoryStore;
+
+	use super::*;
 
 	#[test]
 	fn sanitize_empty_node_alias() {
@@ -2299,4 +2374,39 @@ mod tests {
 		let node = sanitize_alias(alias);
 		assert_eq!(node.err().unwrap(), BuildError::InvalidNodeAlias);
 	}
+
+	#[test]
+	fn restore_requires_backup_store() {
+		let mut builder = NodeBuilder::new();
+		let entropy = NodeEntropy::from_seed_bytes([42; 64]);
+		let primary = InMemoryStore::new();
+
+		let res = builder.restore_from_backup().build_with_store(entropy, primary);
+
+		assert!(matches!(res, Err(BuildError::RestoreRequiresBackupStore)));
+	}
+
+	#[test]
+	fn restore_refuses_nonempty_primary() {
+		let mut builder = NodeBuilder::new();
+		let entropy = NodeEntropy::from_seed_bytes([43; 64]);
+
+		let primary = InMemoryStore::new();
+		let backup: Arc<DynStore> = Arc::new(DynStoreWrapper(InMemoryStore::new()));
+
+		KVStoreSync::write(
+			&primary,
+			CHANNEL_MANAGER_PERSISTENCE_PRIMARY_NAMESPACE,
+			CHANNEL_MANAGER_PERSISTENCE_SECONDARY_NAMESPACE,
+			CHANNEL_MANAGER_PERSISTENCE_KEY,
+			b"existing".to_vec(),
+		)
+		.unwrap();
+
+		builder.set_backup_store(backup, BackupMode::BestEffortBackup);
+		builder.restore_from_backup();
+
+		let res = builder.build_with_store(entropy, primary);
+		assert!(matches!(res, Err(BuildError::RestorePrimaryNotEmpty)));
+	}
 }

src/io/mod.rs

@@ -7,6 +7,7 @@
 
 //! Objects and traits for data persistence.
 
+pub(crate) mod recovery;
 pub mod sqlite_store;
 #[cfg(test)]
 pub(crate) mod test_utils;