Gate tiered storage behind a Cargo feature

Add the opt-in storage-tier feature, gate tier-specific APIs and
implementation, and preserve direct store usage when disabled. Document
the feature, expose it on docs.rs, and run targeted tier storage tests
in CI.

AI-assisted: Developed with Amp.

Author: enigbe

.github/workflows/rust.yml

@@ -86,6 +86,14 @@ jobs:
         if: "matrix.platform != 'windows-latest'"
         run: |
           RUSTFLAGS="--cfg no_download --cfg cycle_tests --cfg tokio_unstable" cargo test
+      - name: Test tiered storage
+        if: matrix.check-fmt
+        run: |
+          cargo test --lib --features storage-tier io::tier_store
+          RUSTFLAGS="--cfg no_download" cargo test \
+            --features storage-tier \
+            --test integration_tests_rust \
+            builder_configures_sqlite_backup_store
       - name: Test with UniFFI support on Rust ${{ matrix.toolchain }}
         if: "matrix.platform != 'windows-latest' && matrix.build-uniffi"
         run: |

Cargo.toml

@@ -13,7 +13,7 @@ keywords = ["bitcoin", "lightning", "ldk", "bdk"]
 categories = ["cryptography::cryptocurrencies"]
 
 [package.metadata.docs.rs]
-features = ["storage-postgres-vendored-tls"]
+features = ["storage-postgres-vendored-tls", "storage-tier"]
 rustdoc-args = ["--cfg", "docsrs"]
 
 [lib]
@@ -53,6 +53,7 @@ chain-electrum = [
 ]
 chain-bitcoind = ["dep:lightning-block-sync"]
 storage-sqlite = ["dep:rusqlite"]
+storage-tier = ["storage-sqlite"]
 storage-filesystem = ["dep:lightning-persister"]
 storage-vss = ["dep:vss-client", "dep:prost"]
 storage-postgres = ["dep:tokio-postgres", "dep:native-tls", "dep:postgres-native-tls"]

README.md

@@ -78,6 +78,7 @@ LDK Node's optional dependencies are grouped by the functionality they provide:
 | `chain-electrum` | Electrum chain source |
 | `chain-bitcoind` | Bitcoin Core RPC and REST chain source |
 | `storage-sqlite` | SQLite storage |
+| `storage-tier` | Tiered storage with optional ephemeral and backup SQLite stores |
 | `storage-filesystem` | Filesystem storage |
 | `storage-vss` | Versioned Storage Service storage |
 | `storage-postgres` | PostgreSQL storage |
@@ -88,7 +89,8 @@ LDK Node's optional dependencies are grouped by the functionality they provide:
 
 The `default` feature set preserves the native Rust API's previous behavior. It enables all three
 chain sources, SQLite, filesystem and VSS storage, and unified payments. PostgreSQL and UniFFI
-remain opt-in. Every build must enable at least one chain source feature.
+remain opt-in. Tiered storage is also opt-in; enabling `storage-tier` automatically enables
+`storage-sqlite`. Every build must enable at least one chain source feature.
 
 On Linux, `storage-postgres` uses the system OpenSSL installation and requires the OpenSSL
 development headers and `pkg-config`. Enable `storage-postgres-vendored-tls` instead to build

src/builder.rs

@@ -11,7 +11,7 @@ use std::convert::TryInto;
 use std::default::Default;
 #[cfg(feature = "unified-payments")]
 use std::net::ToSocketAddrs;
-#[cfg(feature = "storage-filesystem")]
+#[cfg(any(feature = "storage-filesystem", feature = "storage-tier"))]
 use std::path::PathBuf;
 use std::sync::{Arc, Mutex, Once, RwLock};
 use std::time::SystemTime;
@@ -72,6 +72,7 @@ use crate::gossip::GossipSource;
 use crate::io::fs_store::open_or_migrate_fs_store;
 #[cfg(feature = "storage-sqlite")]
 use crate::io::sqlite_store::SqliteStore;
+#[cfg(feature = "storage-tier")]
 use crate::io::tier_store::{setup_index_store, TierStore};
 use crate::io::utils::{
 	read_all_objects, read_event_queue, read_external_pathfinding_scores_from_cache,
@@ -174,6 +175,7 @@ impl std::fmt::Debug for LogWriterConfig {
 	}
 }
 
+#[cfg(feature = "storage-tier")]
 #[derive(Default, Debug)]
 struct TierStoreConfig {
 	ephemeral_storage_dir_path: Option<PathBuf>,
@@ -333,6 +335,7 @@ pub struct NodeBuilder {
 	liquidity_source_config: Option<LiquiditySourceConfig>,
 	log_writer_config: Option<LogWriterConfig>,
 	async_payments_role: Option<AsyncPaymentsRole>,
+	#[cfg(feature = "storage-tier")]
 	tier_store_config: Option<TierStoreConfig>,
 	runtime_handle: Option<tokio::runtime::Handle>,
 	pathfinding_scores_sync_config: Option<PathfindingScoresSyncConfig>,
@@ -355,6 +358,7 @@ impl NodeBuilder {
 		let gossip_source_config = None;
 		let liquidity_source_config = None;
 		let log_writer_config = None;
+		#[cfg(feature = "storage-tier")]
 		let tier_store_config = None;
 		let runtime_handle = None;
 		let pathfinding_scores_sync_config = None;
@@ -365,6 +369,7 @@ impl NodeBuilder {
 			gossip_source_config,
 			liquidity_source_config,
 			log_writer_config,
+			#[cfg(feature = "storage-tier")]
 			tier_store_config,
 			runtime_handle,
 			async_payments_role: None,
@@ -709,7 +714,7 @@ impl NodeBuilder {
 	/// 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"))]
+	#[cfg(all(not(feature = "uniffi"), feature = "storage-tier"))]
 	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());
@@ -722,7 +727,7 @@ impl NodeBuilder {
 	/// 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"))]
+	#[cfg(all(not(feature = "uniffi"), feature = "storage-tier"))]
 	pub fn set_ephemeral_storage_dir_path(
 		&mut self, ephemeral_storage_dir_path: String,
 	) -> &mut Self {
@@ -982,45 +987,52 @@ 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()))
+		#[cfg(feature = "storage-tier")]
+		let store: Arc<DynStore> = {
+			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 tier-store index: {}", e);
+						log_error!(logger, "Failed to setup ephemeral SQLite store: {}", 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);
-			}
+					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);
+				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);
+				}
 			}
-		}
+			Arc::new(DynStoreWrapper(tier_store))
+		};
+		#[cfg(not(feature = "storage-tier"))]
+		let store: Arc<DynStore> = Arc::new(DynStoreWrapper(kv_store));
 
 		let seed_bytes = node_entropy.to_seed_bytes();
 		let config = Arc::new(self.config.clone());
@@ -1036,7 +1048,7 @@ impl NodeBuilder {
 			seed_bytes,
 			runtime,
 			logger,
-			Arc::new(DynStoreWrapper(tier_store)),
+			store,
 		)
 	}
 }

src/io/mod.rs

@@ -15,6 +15,7 @@ pub mod postgres_store;
 pub mod sqlite_store;
 #[cfg(test)]
 pub(crate) mod test_utils;
+#[cfg(feature = "storage-tier")]
 pub(crate) mod tier_store;
 pub(crate) mod utils;
 #[cfg(feature = "storage-vss")]

src/io/sqlite_store/mod.rs

@@ -29,10 +29,13 @@ mod migrations;
 /// LDK Node's database file name.
 pub const SQLITE_DB_FILE_NAME: &str = "ldk_node_data.sqlite";
 /// LDK Node's internal tier-store index database file name.
+#[cfg(feature = "storage-tier")]
 pub(crate) const SQLITE_TIER_INDEX_DB_FILE_NAME: &str = "ldk_node_tier_index.sqlite";
 /// LDK Node's backup database file name.
+#[cfg(feature = "storage-tier")]
 pub const SQLITE_BACKUP_DB_FILE_NAME: &str = "ldk_node_data_backup.sqlite";
 /// LDK Node's ephemeral database file name.
+#[cfg(feature = "storage-tier")]
 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";
@@ -85,6 +88,7 @@ impl SqliteStore {
 	}
 
 	/// Constructs a new [`SqliteStore`] which exclusively owns its database for its lifetime.
+	#[cfg(feature = "storage-tier")]
 	pub(crate) fn new_exclusive(
 		data_dir: PathBuf, db_file_name: Option<String>, kv_table_name: Option<String>,
 	) -> io::Result<Self> {

tests/integration_tests_rust.rs

@@ -38,7 +38,7 @@ use ldk_node::config::{
 	AsyncPaymentsRole, EsploraSyncConfig, ADDRESS_POOL_SIZE, DEFAULT_FULL_SCAN_STOP_GAP,
 };
 use ldk_node::entropy::NodeEntropy;
-#[cfg(not(feature = "uniffi"))]
+#[cfg(all(not(feature = "uniffi"), feature = "storage-tier"))]
 use ldk_node::io::sqlite_store::SqliteStore;
 use ldk_node::liquidity::LSPS2ServiceConfig;
 use ldk_node::payment::{
@@ -4942,7 +4942,7 @@ async fn do_lsps2_multi_lsp_picks_cheapest(reverse_order: bool) {
 }
 
 // Builder backup-store configuration is not yet exposed via FFI (see #871)
-#[cfg(not(feature = "uniffi"))]
+#[cfg(all(not(feature = "uniffi"), feature = "storage-tier"))]
 #[tokio::test(flavor = "multi_thread", worker_threads = 1)]
 async fn builder_configures_sqlite_backup_store() {
 	let (bitcoind, electrsd) = setup_bitcoind_and_electrsd();