Integrate TierStore into NodeBuilder

TierStore remains internal until NodeBuilder provisions and installs its
storage backends.

Add builder options for local ephemeral and backup SQLite stores, wrap the
configured primary store in TierStore, and pass the resulting store into
node construction. When ephemeral storage is enabled, automatically create
the persistent ordering index in the node's storage directory and require
TierStore to own it exclusively.

Update filesystem-backed tests and add integration coverage confirming that
configured backup storage receives durable primary-backed data.

Assisted-by: Amp (AI coding agent)

Author: enigbe

src/builder.rs

@@ -60,6 +60,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::{setup_index_store, TierStore};
 use crate::io::utils::{
 	open_or_migrate_fs_store, read_all_objects, read_event_queue,
 	read_external_pathfinding_scores_from_cache, read_n_objects, read_network_graph,
@@ -158,6 +159,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
@@ -311,6 +318,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>,
 	probing_config: Option<ProbingConfig>,
@@ -329,6 +337,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 probing_config = None;
@@ -338,6 +347,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,
@@ -663,6 +673,41 @@ 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
+	#[cfg(not(feature = "uniffi"))]
+	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.
+	#[cfg(not(feature = "uniffi"))]
+	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> {
@@ -872,11 +917,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: PaginatedKVStore + 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)
 	}
 
@@ -901,6 +953,46 @@ impl NodeBuilder {
 	fn build_with_store_runtime_and_logger<S: PaginatedKVStore + 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 index_store = runtime
+					.block_on(setup_index_store(self.config.storage_dir_path.clone().into()))
+					.map_err(|e| {
+						log_error!(logger, "Failed to setup tier-store index: {}", e);
+						BuildError::KVStoreSetupFailed
+					})?;
+				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_index_store(index_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());
 
@@ -915,7 +1007,7 @@ impl NodeBuilder {
 			seed_bytes,
 			runtime,
 			logger,
-			Arc::new(DynStoreWrapper(kv_store)),
+			Arc::new(DynStoreWrapper(tier_store)),
 		)
 	}
 }

src/io/sqlite_store/mod.rs

@@ -30,6 +30,10 @@ mod migrations;
 pub const SQLITE_DB_FILE_NAME: &str = "ldk_node_data.sqlite";
 /// LDK Node's internal tier-store index database file name.
 pub(crate) const SQLITE_TIER_INDEX_DB_FILE_NAME: &str = "ldk_node_tier_index.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;

tests/common/mod.rs

@@ -56,7 +56,7 @@ use lightning::ln::msgs::SocketAddress;
 use lightning::routing::gossip::NodeAlias;
 use lightning::util::persist::{KVStore, PageToken, PaginatedKVStore, PaginatedListResponse};
 use lightning_invoice::{Bolt11InvoiceDescription, Description};
-use lightning_persister::fs_store::v1::FilesystemStore;
+use lightning_persister::fs_store::v2::FilesystemStoreV2;
 use lightning_types::payment::{PaymentHash, PaymentPreimage};
 use logging::TestLogWriter;
 use rand::distr::Alphanumeric;
@@ -1901,7 +1901,7 @@ impl PaginatedKVStore for TestSyncStore {
 struct TestSyncStoreInner {
 	serializer: tokio::sync::RwLock<()>,
 	test_store: InMemoryStore,
-	fs_store: FilesystemStore,
+	fs_store: FilesystemStoreV2,
 	sqlite_store: SqliteStore,
 }
 
@@ -1910,7 +1910,7 @@ impl TestSyncStoreInner {
 		let serializer = tokio::sync::RwLock::new(());
 		let mut fs_dir = dest_dir.clone();
 		fs_dir.push("fs_store");
-		let fs_store = FilesystemStore::new(fs_dir);
+		let fs_store = FilesystemStoreV2::new(fs_dir).unwrap();
 		let mut sql_dir = dest_dir.clone();
 		sql_dir.push("sqlite_store");
 		let sqlite_store = SqliteStore::new(

tests/integration_tests_rust.rs

@@ -38,6 +38,8 @@ use ldk_node::config::{
 	AsyncPaymentsRole, EsploraSyncConfig, ADDRESS_POOL_SIZE, DEFAULT_FULL_SCAN_STOP_GAP,
 };
 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, PayerProofOptions, PaymentDetails, PaymentDirection, PaymentKind,
@@ -4925,3 +4927,74 @@ async fn do_lsps2_multi_lsp_picks_cheapest(reverse_order: bool) {
 	cheap.stop().unwrap();
 	expensive.stop().unwrap();
 }
+
+// Builder backup-store configuration is not yet exposed via FFI (see #871)
+#[cfg(not(feature = "uniffi"))]
+#[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();
+	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 mut config_b = random_config();
+	config_b.node_config.manually_handle_unknown_bolt11_payments = 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}");
+	}
+}