Integrate TierStore into NodeBuilder

Add native builder support for tiered storage by introducing
`TierStoreConfig` and builder methods for configuring ephemeral storage
and a local SQLite backup mirror.

During node construction, wrap the configured primary store in
`TierStore` and attach secondary tiers for cache-like ephemeral data and
mirrored durable backup writes. The builder constructs the backup  and
ephemeral stores internally using a dedicated SQLite database file.

Add test coverage for full-cycle backup mirroring, same-path rejection,
and UniFFI-backed builder configuration. Update `setup_builder!` so
FFI-backed builder tests can use mutable configuration helpers.

Author: enigbe

src/builder.rs

@@ -57,6 +57,7 @@ use crate::event::EventQueue;
 use crate::fee_estimator::OnchainFeeEstimator;
 use crate::gossip::GossipSource;
 use crate::io::sqlite_store::SqliteStore;
+use crate::io::tier_store::TierStore;
 use crate::io::utils::{
 	open_or_migrate_fs_store, read_all_objects, read_event_queue,
 	read_external_pathfinding_scores_from_cache, read_network_graph, read_node_metrics,
@@ -150,6 +151,12 @@ impl std::fmt::Debug for LogWriterConfig {
 	}
 }
 
+#[derive(Default, Debug)]
+struct TierStoreConfig {
+	ephemeral_storage_dir_path: Option<PathBuf>,
+	backup_storage_dir_path: Option<PathBuf>,
+}
+
 /// An error encountered during building a [`Node`].
 ///
 /// [`Node`]: crate::Node
@@ -285,6 +292,7 @@ pub struct NodeBuilder {
 	liquidity_source_config: Option<LiquiditySourceConfig>,
 	log_writer_config: Option<LogWriterConfig>,
 	async_payments_role: Option<AsyncPaymentsRole>,
+	tier_store_config: Option<TierStoreConfig>,
 	runtime_handle: Option<tokio::runtime::Handle>,
 	pathfinding_scores_sync_config: Option<PathfindingScoresSyncConfig>,
 	recovery_mode: bool,
@@ -303,6 +311,7 @@ impl NodeBuilder {
 		let gossip_source_config = None;
 		let liquidity_source_config = None;
 		let log_writer_config = None;
+		let tier_store_config = None;
 		let runtime_handle = None;
 		let pathfinding_scores_sync_config = None;
 		let recovery_mode = false;
@@ -312,6 +321,7 @@ impl NodeBuilder {
 			gossip_source_config,
 			liquidity_source_config,
 			log_writer_config,
+			tier_store_config,
 			runtime_handle,
 			async_payments_role: None,
 			pathfinding_scores_sync_config,
@@ -612,6 +622,39 @@ impl NodeBuilder {
 		self
 	}
 
+	/// Configures a local SQLite backup store for disaster recovery.
+	///
+	/// When building with tiered storage, a SQLite store will be created at the
+	/// given directory path using [`SQLITE_BACKUP_DB_FILE_NAME`] as its database
+	/// file name. It receives a second durable copy of data written to the
+	/// primary store.
+	///
+	/// Writes and removals for primary-backed data only succeed once both the
+	/// primary and backup SQLite stores complete successfully.
+	///
+	/// If not set, durable data will be stored only in the primary store.
+	///
+	/// [`SQLITE_BACKUP_DB_FILE_NAME`]: crate::io::sqlite_store::SQLITE_BACKUP_DB_FILE_NAME
+	pub fn set_backup_storage_dir_path(&mut self, backup_storage_dir_path: String) -> &mut Self {
+		let tier_store_config = self.tier_store_config.get_or_insert(TierStoreConfig::default());
+		tier_store_config.backup_storage_dir_path = Some(backup_storage_dir_path.into());
+		self
+	}
+
+	/// Configures the ephemeral storage directory path for non-critical, frequently-accessed data.
+	///
+	/// When set, a local SQLite store is created at this path for ephemeral data like
+	/// the network graph and scorer. Data stored here can be rebuilt if lost.
+	///
+	/// If not set, non-critical data will be stored in the primary store.
+	pub fn set_ephemeral_storage_dir_path(
+		&mut self, ephemeral_storage_dir_path: String,
+	) -> &mut Self {
+		let tier_store_config = self.tier_store_config.get_or_insert(TierStoreConfig::default());
+		tier_store_config.ephemeral_storage_dir_path = Some(ephemeral_storage_dir_path.into());
+		self
+	}
+
 	/// Builds a [`Node`] instance with a [`SqliteStore`] backend and according to the options
 	/// previously configured.
 	pub fn build(&self, node_entropy: NodeEntropy) -> Result<Node, BuildError> {
@@ -813,11 +856,18 @@ impl NodeBuilder {
 	}
 
 	/// Builds a [`Node`] instance according to the options previously configured.
+	///
+	/// The provided `kv_store` will be used as the primary storage backend. Optionally,
+	/// an ephemeral store for frequently-accessed non-critical data (e.g., network graph, scorer)
+	/// and a local SQLite backup store for disaster recovery can be configured via
+	/// [`set_ephemeral_storage_dir_path`] and [`set_backup_storage_dir_path`].
+	///
+	/// [`set_ephemeral_storage_dir_path`]: Self::set_ephemeral_storage_dir_path
+	/// [`set_backup_storage_dir_path`]: Self::set_backup_storage_dir_path
 	pub fn build_with_store<S: KVStore + Send + Sync + 'static>(
 		&self, node_entropy: NodeEntropy, kv_store: S,
 	) -> Result<Node, BuildError> {
 		let logger = setup_logger(&self.log_writer_config, &self.config)?;
-
 		self.build_with_store_and_logger(node_entropy, kv_store, logger)
 	}
 
@@ -842,6 +892,39 @@ impl NodeBuilder {
 	fn build_with_store_runtime_and_logger<S: KVStore + Send + Sync + 'static>(
 		&self, node_entropy: NodeEntropy, kv_store: S, runtime: Arc<Runtime>, logger: Arc<Logger>,
 	) -> Result<Node, BuildError> {
+		let ts_config = self.tier_store_config.as_ref();
+		let primary_store = Arc::new(DynStoreWrapper(kv_store));
+		let mut tier_store = TierStore::new(primary_store, Arc::clone(&logger));
+		if let Some(config) = ts_config {
+			if let Some(ephemeral_storage_dir_path) = config.ephemeral_storage_dir_path.as_ref() {
+				let ephemeral_store = SqliteStore::new(
+					ephemeral_storage_dir_path.clone(),
+					Some(io::sqlite_store::SQLITE_EPHEMERAL_DB_FILE_NAME.to_string()),
+					Some(io::sqlite_store::KV_TABLE_NAME.to_string()),
+				)
+				.map_err(|e| {
+					log_error!(logger, "Failed to setup ephemeral SQLite store: {}", e);
+					BuildError::KVStoreSetupFailed
+				})?;
+				let ephemeral_store: Arc<DynStore> = Arc::new(DynStoreWrapper(ephemeral_store));
+				tier_store.set_ephemeral_store(ephemeral_store);
+			}
+
+			if let Some(backup_storage_dir_path) = config.backup_storage_dir_path.as_ref() {
+				let backup_store = SqliteStore::new(
+					backup_storage_dir_path.clone(),
+					Some(io::sqlite_store::SQLITE_BACKUP_DB_FILE_NAME.to_string()),
+					Some(io::sqlite_store::KV_TABLE_NAME.to_string()),
+				)
+				.map_err(|e| {
+					log_error!(logger, "Failed to setup backup SQLite store: {}", e);
+					BuildError::KVStoreSetupFailed
+				})?;
+				let backup_store: Arc<DynStore> = Arc::new(DynStoreWrapper(backup_store));
+				tier_store.set_backup_store(backup_store);
+			}
+		}
+
 		let seed_bytes = node_entropy.to_seed_bytes();
 		let config = Arc::new(self.config.clone());
 
@@ -856,7 +939,7 @@ impl NodeBuilder {
 			seed_bytes,
 			runtime,
 			logger,
-			Arc::new(DynStoreWrapper(kv_store)),
+			Arc::new(DynStoreWrapper(tier_store)),
 		)
 	}
 }

src/io/sqlite_store/mod.rs

@@ -24,6 +24,10 @@ mod migrations;
 
 /// LDK Node's database file name.
 pub const SQLITE_DB_FILE_NAME: &str = "ldk_node_data.sqlite";
+/// LDK Node's backup database file name.
+pub const SQLITE_BACKUP_DB_FILE_NAME: &str = "ldk_node_data_backup.sqlite";
+/// LDK Node's ephemeral database file name.
+pub const SQLITE_EPHEMERAL_DB_FILE_NAME: &str = "ldk_node_data_ephemeral.sqlite";
 /// LDK Node's table in which we store all data.
 pub const KV_TABLE_NAME: &str = "ldk_node_data";
 

src/io/tier_store.rs

@@ -4,7 +4,6 @@
 // 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.
-#![allow(dead_code)] // TODO: Temporal warning silencer. Will be removed in later commit.
 
 use std::collections::HashMap;
 use std::future::Future;

src/types.rs

@@ -46,7 +46,7 @@ use crate::message_handler::NodeCustomMessageHandler;
 use crate::payment::{PaymentDetails, PendingPaymentDetails};
 use crate::runtime::RuntimeSpawner;
 
-pub(crate) trait DynStoreTrait: Send + Sync {
+pub trait DynStoreTrait: Send + Sync {
 	fn read_async(
 		&self, primary_namespace: &str, secondary_namespace: &str, key: &str,
 	) -> Pin<Box<dyn Future<Output = Result<Vec<u8>, bitcoin::io::Error>> + Send + 'static>>;
@@ -87,7 +87,7 @@ impl<'a> KVStore for dyn DynStoreTrait + 'a {
 	}
 }
 
-pub(crate) type DynStore = dyn DynStoreTrait;
+pub type DynStore = dyn DynStoreTrait;
 
 // Newtype wrapper that implements `KVStore` for `Arc<DynStore>`. This is needed because `KVStore`
 // methods return `impl Future`, which is not object-safe. `DynStoreTrait` works around this by

tests/common/mod.rs

@@ -532,6 +532,7 @@ pub(crate) fn setup_two_nodes_with_store(
 
 pub(crate) fn setup_node(chain_source: &TestChainSource, config: TestConfig) -> TestNode {
 	setup_builder!(builder, config.node_config);
+
 	match chain_source {
 		TestChainSource::Esplora(electrsd) => {
 			let esplora_url = format!("http://{}", electrsd.esplora_url.as_ref().unwrap());
@@ -601,10 +602,6 @@ pub(crate) fn setup_node(chain_source: &TestChainSource, config: TestConfig) ->
 		},
 	};
 
-	if config.recovery_mode {
-		builder.set_wallet_recovery_mode();
-	}
-
 	node.start().unwrap();
 	assert!(node.status().is_running);
 	assert!(node.status().latest_fee_rate_cache_update_timestamp.is_some());

tests/integration_tests_rust.rs

@@ -30,6 +30,8 @@ use electrsd::corepc_node::Node as BitcoinD;
 use electrsd::ElectrsD;
 use ldk_node::config::{AsyncPaymentsRole, EsploraSyncConfig};
 use ldk_node::entropy::NodeEntropy;
+#[cfg(not(feature = "uniffi"))]
+use ldk_node::io::sqlite_store::SqliteStore;
 use ldk_node::liquidity::LSPS2ServiceConfig;
 use ldk_node::payment::{
 	ConfirmationStatus, PaymentDetails, PaymentDirection, PaymentKind, PaymentStatus,
@@ -39,6 +41,8 @@ use ldk_node::{Builder, Event, NodeError};
 use lightning::ln::channelmanager::PaymentId;
 use lightning::routing::gossip::{NodeAlias, NodeId};
 use lightning::routing::router::RouteParametersConfig;
+#[cfg(not(feature = "uniffi"))]
+use lightning::util::persist::KVStore;
 use lightning_invoice::{Bolt11InvoiceDescription, Description};
 use lightning_types::payment::{PaymentHash, PaymentPreimage};
 use log::LevelFilter;
@@ -3046,6 +3050,7 @@ async fn splice_in_with_all_balance() {
 	node_b.stop().unwrap();
 }
 
+#[cfg(not(feature = "uniffi"))]
 #[tokio::test(flavor = "multi_thread", worker_threads = 1)]
 async fn lsps2_multi_lsp_picks_cheapest() {
 	do_lsps2_multi_lsp_picks_cheapest(false).await;
@@ -3140,3 +3145,71 @@ async fn do_lsps2_multi_lsp_picks_cheapest(reverse_order: bool) {
 	cheap.stop().unwrap();
 	expensive.stop().unwrap();
 }
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 1)]
+async fn builder_configures_sqlite_backup_store() {
+	let (bitcoind, electrsd) = setup_bitcoind_and_electrsd();
+	let chain_source = random_chain_source(&bitcoind, &electrsd);
+
+	let mut config_a = random_config(true);
+	config_a.store_type = TestStoreType::Sqlite;
+	let primary_dir = config_a.node_config.storage_dir_path.clone();
+	let backup_dir = common::random_storage_path();
+
+	// Build node_a with backup storage configured
+	setup_builder!(builder_a, config_a.node_config.clone());
+	builder_a.set_chain_source_esplora(
+		format!("http://{}", electrsd.esplora_url.as_ref().unwrap()),
+		None,
+	);
+	builder_a.set_filesystem_logger(None, None);
+	builder_a.set_backup_storage_dir_path(backup_dir.to_str().unwrap().to_owned());
+
+	let node_a = builder_a.build(config_a.node_entropy.into()).unwrap();
+	node_a.start().unwrap();
+	assert!(node_a.status().is_running);
+	assert!(node_a.status().latest_fee_rate_cache_update_timestamp.is_some());
+
+	let config_b = random_config(true);
+	let node_b = setup_node(&chain_source, config_b);
+
+	do_channel_full_cycle(
+		node_a,
+		node_b,
+		&bitcoind.client,
+		&electrsd.client,
+		false,
+		true,
+		true,
+		false,
+	)
+	.await;
+
+	let primary_store = SqliteStore::new(
+		primary_dir.into(),
+		Some(ldk_node::io::sqlite_store::SQLITE_DB_FILE_NAME.to_string()),
+		Some(ldk_node::io::sqlite_store::KV_TABLE_NAME.to_string()),
+	)
+	.unwrap();
+
+	let backup_store = SqliteStore::new(
+		backup_dir,
+		Some(ldk_node::io::sqlite_store::SQLITE_BACKUP_DB_FILE_NAME.to_string()),
+		Some(ldk_node::io::sqlite_store::KV_TABLE_NAME.to_string()),
+	)
+	.unwrap();
+
+	for (pn, sn, key) in [
+		("bdk_wallet", "", "descriptor"),
+		("bdk_wallet", "", "change_descriptor"),
+		("bdk_wallet", "", "network"),
+		("", "", "node_metrics"),
+		("", "", "events"),
+		("", "", "peers"),
+	] {
+		let primary = primary_store.read(pn, sn, key).await.unwrap();
+		let backup = backup_store.read(pn, sn, key).await.unwrap();
+
+		assert_eq!(backup, primary, "backup mismatch for {pn}/{sn}/{key}");
+	}
+}