feat: add builder extension trait for sqlite store (0xMiden#1416)

* feat: add builder extension trait for sqlite store

* review: update error message

* chore: lint

Author: TomasArrachea

CHANGELOG.md

@@ -34,6 +34,7 @@
 * [BREAKING] Removed WebClient's `compileNoteScript` method and both `TransactionScript` and `NoteScript` compile methods; the new `ScriptBuilder` should be used instead ([#1331](https://github.com/0xMiden/miden-client/pull/1274)).
 * [BREAKING] Implemented `AccountFile` in the WebClient ([#1258](https://github.com/0xMiden/miden-client/pull/1258)).
 * [BREAKING] Added remote key storage and signature requesting to the `WebKeyStore` ([#1371](https://github.com/0xMiden/miden-client/pull/1371))
+* Added `sqlite_store` under `ClientBuilderSqliteExt` method to the `ClientBuilder` ([#1416](https://github.com/0xMiden/miden-client/pull/1416))
 
 ## 0.11.8 (2025-09-29)
 

bin/integration-tests/src/tests/client.rs

@@ -27,7 +27,7 @@ use miden_client::transaction::{
     TransactionRequestBuilder,
     TransactionStatus,
 };
-use miden_client_sqlite_store::SqliteStore;
+use miden_client_sqlite_store::ClientBuilderSqliteExt;
 
 use crate::tests::config::ClientConfig;
 
@@ -36,12 +36,10 @@ pub async fn test_client_builder_initializes_client_with_endpoint(
 ) -> Result<()> {
     let (endpoint, _, store_config, auth_path) = client_config.as_parts();
 
-    let sqlite_store = SqliteStore::new(store_config).await?;
-
     let mut client = ClientBuilder::<FilesystemKeyStore<_>>::new()
         .grpc_client(&endpoint, Some(10_000))
         .filesystem_keystore(auth_path.to_str().context("failed to convert auth path to string")?)
-        .store(Arc::new(sqlite_store))
+        .sqlite_store(store_config)
         .in_debug_mode(miden_client::DebugMode::Enabled)
         .build()
         .await?;

bin/integration-tests/src/tests/config.rs

@@ -9,7 +9,7 @@ use miden_client::keystore::FilesystemKeyStore;
 use miden_client::rpc::{Endpoint, GrpcClient};
 use miden_client::testing::common::{TestClient, TestClientKeyStore, create_test_store_path};
 use miden_client::{DebugMode, Felt};
-use miden_client_sqlite_store::SqliteStore;
+use miden_client_sqlite_store::ClientBuilderSqliteExt;
 use rand::Rng;
 use uuid::Uuid;
 
@@ -64,21 +64,14 @@ impl ClientConfig {
 
         let rng = RpoRandomCoin::new(coin_seed.map(Felt::new).into());
 
-        let store = {
-            let sqlite_store = SqliteStore::new(store_config)
-                .await
-                .with_context(|| "failed to create SQLite store")?;
-            Arc::new(sqlite_store)
-        };
-
         let keystore = FilesystemKeyStore::new(auth_path.clone()).with_context(|| {
             format!("failed to create keystore at path: {}", auth_path.to_string_lossy())
         })?;
 
         let builder = ClientBuilder::new()
             .rpc(Arc::new(GrpcClient::new(&rpc_endpoint, rpc_timeout)))
             .rng(Box::new(rng))
-            .store(store)
+            .sqlite_store(store_config)
             .filesystem_keystore(auth_path.to_str().with_context(|| {
                 format!("failed to convert auth path to string: {}", auth_path.to_string_lossy())
             })?)

bin/miden-cli/src/lib.rs

@@ -12,7 +12,7 @@ use miden_client::keystore::FilesystemKeyStore;
 use miden_client::note_transport::grpc::GrpcNoteTransportClient;
 use miden_client::store::{NoteFilter as ClientNoteFilter, OutputNoteRecord};
 use miden_client::{Client, DebugMode, IdPrefixFetchError};
-use miden_client_sqlite_store::SqliteStore;
+use miden_client_sqlite_store::ClientBuilderSqliteExt;
 use rand::rngs::StdRng;
 mod commands;
 use commands::account::AccountCmd;
@@ -173,12 +173,8 @@ impl Cli {
         let keystore = CliKeyStore::new(cli_config.secret_keys_directory.clone())
             .map_err(CliError::KeyStore)?;
 
-        let sqlite_store = SqliteStore::new(cli_config.store_filepath.clone())
-            .await
-            .map_err(|e| CliError::Internal(Box::new(e)))?;
-
         let mut builder = ClientBuilder::new()
-            .store(Arc::new(sqlite_store))
+            .sqlite_store(cli_config.store_filepath.clone())
             .grpc_client(&cli_config.rpc.endpoint.clone().into(), Some(cli_config.rpc.timeout_ms))
             .authenticator(Arc::new(keystore.clone()))
             .in_debug_mode(in_debug_mode)

crates/rust-client/src/builder.rs

@@ -11,7 +11,7 @@ use rand::Rng;
 use crate::keystore::FilesystemKeyStore;
 use crate::note_transport::NoteTransportClient;
 use crate::rpc::NodeRpcClient;
-use crate::store::Store;
+use crate::store::{Store, StoreError};
 use crate::{Client, ClientError, DebugMode};
 
 // CONSTANTS
@@ -35,6 +35,23 @@ enum AuthenticatorConfig<AUTH> {
     Instance(Arc<AUTH>),
 }
 
+// STORE BUILDER
+// ================================================================================================
+
+/// Allows the [`ClientBuilder`] to accept either an already built store instance or a factory for
+/// deferring the store instantiation.
+pub enum StoreBuilder {
+    Store(Arc<dyn Store>),
+    Factory(Box<dyn StoreFactory>),
+}
+
+/// Trait for building a store instance.
+#[async_trait::async_trait]
+pub trait StoreFactory {
+    /// Returns a new store instance.
+    async fn build(&self) -> Result<Arc<dyn Store>, StoreError>;
+}
+
 // CLIENT BUILDER
 // ================================================================================================
 
@@ -47,7 +64,7 @@ pub struct ClientBuilder<AUTH> {
     /// An optional custom RPC client. If provided, this takes precedence over `rpc_endpoint`.
     rpc_api: Option<Arc<dyn NodeRpcClient>>,
     /// An optional store provided by the user.
-    store: Option<Arc<dyn Store>>,
+    pub store: Option<StoreBuilder>,
     /// An optional RNG provided by the user.
     rng: Option<Box<dyn FeltRng>>,
     /// The keystore configuration provided by the user.
@@ -70,7 +87,6 @@ impl<AUTH> Default for ClientBuilder<AUTH> {
             rpc_api: None,
             store: None,
             rng: None,
-
             keystore: None,
             in_debug_mode: DebugMode::Disabled,
             tx_graceful_blocks: Some(TX_GRACEFUL_BLOCKS),
@@ -113,10 +129,10 @@ where
         self
     }
 
-    /// Optionally provide a store directly.
+    /// Provide a store to be used by the client.
     #[must_use]
     pub fn store(mut self, store: Arc<dyn Store>) -> Self {
-        self.store = Some(store);
+        self.store = Some(StoreBuilder::Store(store));
         self
     }
 
@@ -188,12 +204,14 @@ where
         };
 
         // Ensure a store was provided.
-        let store: Arc<dyn Store> = if let Some(store) = self.store {
-            store
+        let store = if let Some(store_builder) = self.store {
+            match store_builder {
+                StoreBuilder::Store(store) => store,
+                StoreBuilder::Factory(factory) => factory.build().await?,
+            }
         } else {
             return Err(ClientError::ClientInitializationError(
-                "Store must be specified. Call `.store(...)` or `.sqlite_store(...)` with a store path if `sqlite` is enabled."
-                    .into(),
+                "Store must be specified. Call `.store(...)`.".into(),
             ));
         };
 

crates/sqlite-store/src/builder.rs

@@ -0,0 +1,35 @@
+use std::path::PathBuf;
+use std::sync::Arc;
+
+use miden_client::builder::{BuilderAuthenticator, ClientBuilder, StoreBuilder, StoreFactory};
+use miden_client::store::{Store, StoreError};
+
+use crate::SqliteStore;
+
+/// Extends the [`ClientBuilder`] with a method to add a [`SqliteStore`].
+pub trait ClientBuilderSqliteExt<AUTH> {
+    fn sqlite_store(self, database_filepath: PathBuf) -> ClientBuilder<AUTH>;
+}
+
+impl<AUTH: BuilderAuthenticator> ClientBuilderSqliteExt<AUTH> for ClientBuilder<AUTH> {
+    /// Sets a [`SqliteStore`] to the [`ClientBuilder`]. The store will be instantiated when the
+    /// [`build`](ClientBuilder::build) method is called.
+    fn sqlite_store(mut self, database_filepath: PathBuf) -> ClientBuilder<AUTH> {
+        self.store =
+            Some(StoreBuilder::Factory(Box::new(SqliteStoreFactory { database_filepath })));
+        self
+    }
+}
+
+/// Factory for building a [`SqliteStore`].
+struct SqliteStoreFactory {
+    database_filepath: PathBuf,
+}
+
+#[async_trait::async_trait]
+impl StoreFactory for SqliteStoreFactory {
+    async fn build(&self) -> Result<Arc<dyn Store>, StoreError> {
+        let sqlite_store = SqliteStore::new(self.database_filepath.clone()).await?;
+        Ok(Arc::new(sqlite_store))
+    }
+}

crates/sqlite-store/src/lib.rs

@@ -54,6 +54,7 @@ use rusqlite::types::Value;
 use crate::merkle_store::{insert_asset_nodes, insert_storage_map_nodes};
 
 mod account;
+mod builder;
 mod chain_data;
 mod db_management;
 mod merkle_store;
@@ -62,6 +63,8 @@ mod sql_error;
 mod sync;
 mod transaction;
 
+pub use builder::ClientBuilderSqliteExt;
+
 // SQLITE STORE
 // ================================================================================================
 
@@ -80,7 +83,7 @@ impl SqliteStore {
 
     /// Returns a new instance of [Store] instantiated with the specified configuration options.
     pub async fn new(database_filepath: PathBuf) -> Result<Self, StoreError> {
-        let sqlite_pool_manager = SqlitePoolManager::new(database_filepath.clone());
+        let sqlite_pool_manager = SqlitePoolManager::new(database_filepath);
         let pool = Pool::builder(sqlite_pool_manager)
             .build()
             .map_err(|e| StoreError::DatabaseError(e.to_string()))?;

crates/testing/miden-client-tests/src/tests.rs

@@ -45,7 +45,7 @@ use miden_client::transaction::{
 };
 use miden_client::utils::RwLock;
 use miden_client::{ClientError, DebugMode};
-use miden_client_sqlite_store::SqliteStore;
+use miden_client_sqlite_store::ClientBuilderSqliteExt;
 use miden_lib::account::auth::AuthRpoFalcon512;
 use miden_lib::account::faucets::BasicFungibleFaucet;
 use miden_lib::account::interface::AccountInterfaceError;
@@ -2103,11 +2103,10 @@ pub async fn create_test_client_builder()
     let rpc_api = MockRpcApi::new(Box::pin(create_prebuilt_mock_chain()).await);
     let arc_rpc_api = Arc::new(rpc_api.clone());
 
-    let sqlite_store = SqliteStore::new(create_test_store_path()).await.unwrap();
     let builder = ClientBuilder::new()
         .rpc(arc_rpc_api)
         .rng(Box::new(rng))
-        .store(Arc::new(sqlite_store))
+        .sqlite_store(create_test_store_path())
         .filesystem_keystore(keystore_path.to_str().unwrap())
         .in_debug_mode(DebugMode::Enabled)
         .tx_graceful_blocks(None);