feat: miden client service

Cargo.toml

@@ -5,15 +5,16 @@ members = [
   "bin/integration-tests",
   "bin/miden-cli",
   "crates/idxdb-store",
-  "crates/rust-client",
+  "crates/miden-client",
+  "crates/miden-client-core",
   "crates/sqlite-store",
   "crates/testing/miden-client-tests",
   "crates/testing/node-builder",
   "crates/testing/prover",
   "crates/web-client",
 ]
 
-default-members = ["bin/miden-cli", "crates/rust-client"]
+default-members = ["bin/miden-cli", "crates/miden-client"]
 
 [workspace.package]
 authors      = ["miden contributors"]

Makefile

@@ -16,7 +16,7 @@ WARNINGS=RUSTDOCFLAGS="-D warnings"
 
 PROVER_DIR="crates/testing/prover"
 WEB_CLIENT_DIR=crates/web-client
-RUST_CLIENT_DIR=crates/rust-client
+RUST_CLIENT_DIR=crates/miden-client-core
 
 EXCLUDE_WASM_PACKAGES=--exclude miden-client-web --exclude miden-idxdb-store
 
@@ -73,11 +73,11 @@ rust-client-ts-lint:
 
 .PHONY: doc
 doc: ## Generate & check rust documentation. Ensure you have the nightly toolchain installed.
-	@cd crates/rust-client && \
+	@cd crates/miden-client-core && \
 	RUSTDOCFLAGS="-D warnings --cfg docsrs" cargo +nightly doc --lib --no-deps --all-features --keep-going --release
 
 doc-open: ## Generate & open rust documentation in browser. Ensure you have the nightly toolchain installed.
-	@cd crates/rust-client && \
+	@cd crates/miden-client-core && \
 	RUSTDOCFLAGS="-D warnings --cfg docsrs" cargo +nightly doc --lib --no-deps --all-features --keep-going --release --open
 
 .PHONY: serve-docs

README.md

@@ -14,10 +14,11 @@ The Miden client is still under heavy development and the project can be conside
 
 ## Overview
 
-The Miden client currently consists of two components:
+The Miden client currently consists of:
 
-- `miden-client` library, which can be used by other project to programmatically interact with the Miden rollup. You can find more information about the library in the [Rust client Library](./crates/rust-client/README.md) section.
-- `miden-client-cli`, which is a wrapper around the library exposing its functionality via a simple command-line interface (CLI). You can find more information about the CLI in the [Miden client CLI](./bin/miden-cli/README.md) section.
+- `miden-client-core` – the no_std-compatible library that implements the core client logic. More info in the [core library docs](./crates/miden-client-core/README.md).
+- `miden-client` – a std-only facade that re-exports the core APIs and adds a background service for continuous sync and event handling.
+- `miden-client-cli` – a wrapper around the library exposing its functionality via a simple command-line interface (CLI). You can find more information about the CLI in the [Miden client CLI](./bin/miden-cli/README.md) section.
 
 The client's main responsibility is to maintain a partial view of the blockchain which allows for locally executing and proving transactions. It keeps a local store of various entities that periodically get updated by syncing with the node.
 

bin/integration-tests/Cargo.toml

@@ -19,7 +19,7 @@ path = "tests/integration.rs"
 
 [dependencies]
 # Workspace dependencies
-miden-client              = { features = ["std", "testing", "tonic"], path = "../../crates/rust-client" }
+miden-client              = { features = ["std", "testing", "tonic"], path = "../../crates/miden-client" }
 miden-client-sqlite-store = { package = "miden-client-sqlite-store", path = "../../crates/sqlite-store" }
 
 # External dependencies

bin/miden-cli/Cargo.toml

@@ -18,7 +18,7 @@ path = "src/main.rs"
 
 [dependencies]
 # Workspace dependencies
-miden-client              = { features = ["tonic"], path = "../../crates/rust-client" }
+miden-client              = { features = ["tonic"], path = "../../crates/miden-client" }
 miden-client-sqlite-store = { package = "miden-client-sqlite-store", path = "../../crates/sqlite-store" }
 
 # External dependencies
@@ -36,12 +36,12 @@ tracing            = { workspace = true }
 tracing-subscriber = { version = "0.3" }
 
 [build-dependencies]
-miden-client = { path = "../../crates/rust-client" }
+miden-client = { path = "../../crates/miden-client" }
 
 [dev-dependencies]
 anyhow       = { workspace = true }
 assert_cmd   = { version = "2.0" }
-miden-client = { features = ["testing"], path = "../../crates/rust-client" }
+miden-client = { features = ["testing"], path = "../../crates/miden-client" }
 predicates   = { version = "3.0" }
 regex        = { version = "1.0" }
 serial_test  = { version = "3.0" }

crates/idxdb-store/Cargo.toml

@@ -13,7 +13,7 @@ crate-type = ["cdylib", "rlib"]
 
 [dependencies]
 # Miden dependencies
-miden-client = { default-features = false, path = "../rust-client" }
+miden-client = { default-features = false, package = "miden-client-core", path = "../miden-client-core" }
 
 # Workspace dependencies
 async-trait = { workspace = true }

crates/idxdb-store/src/README.md

@@ -12,5 +12,4 @@ files under `src/js`. This is because to use extern functions, we still need to
 .js files.
 
 To unify and make this setup straightforward, the top-most makefile from this project has a
-useful target: `make rust-client-ts-build`, which takes the .ts files and compiles them down to .js files.
-
+useful target: `make rust-client-ts-build`, which takes the .ts files and compiles them down to .js files for the core client.

crates/rust-client/Cargo.toml → crates/miden-client-core/Cargo.toml

@@ -1,12 +1,12 @@
 [package]
 authors.workspace      = true
 categories             = ["no-std"]
-description            = "Client library that facilitates interaction with the Miden network"
-documentation          = "https://docs.rs/miden-client"
+description            = "Core client library that facilitates interaction with the Miden network"
+documentation          = "https://docs.rs/miden-client-core"
 edition.workspace      = true
 keywords               = ["client", "miden"]
 license.workspace      = true
-name                   = "miden-client"
+name                   = "miden-client-core"
 readme                 = "README.md"
 repository.workspace   = true
 rust-version.workspace = true
@@ -78,7 +78,7 @@ tonic-prost                      = { version = "0.14" }
 tonic-prost-build                = { version = "0.14" }
 
 [dev-dependencies]
-miden-client              = { features = ["std", "testing"], path = "." }
+miden-client              = { features = ["std", "testing"], package = "miden-client-core", path = "." }
 miden-client-sqlite-store = { package = "miden-client-sqlite-store", path = "../sqlite-store" }
 miden-lib                 = { features = ["testing"], workspace = true }
 miden-objects             = { default-features = false, features = ["testing"], workspace = true }

crates/rust-client/README.md → crates/miden-client-core/README.md

@@ -1,13 +1,13 @@
-# Rust Client Library
+# Miden Client Core
 
-Rust library, which can be used by other project to programmatically interact with the Miden rollup.
+Rust library, which can be used by other project to programmatically interact with the Miden rollup. This crate is no_std-compatible and is re-exported by the std-only `miden-client` facade.
 
-## Adding miden-client as a dependency
+## Adding miden-client-core as a dependency
 
-In order to utilize the `miden-client` library, you can add the dependency to your project's `Cargo.toml` file:
+In order to utilize the `miden-client-core` library, you can add the dependency to your project's `Cargo.toml` file:
 
 ````toml
-miden-client = { version = "0.13" }
+miden-client-core = { version = "0.13" }
 ````
 
 ## Crate Features

crates/rust-client/src/lib.rs → crates/miden-client-core/src/lib.rs

@@ -46,7 +46,7 @@
 //!
 //! ```toml
 //! [dependencies]
-//! miden-client = "0.10"
+//! miden-client-core = "0.13"
 //! ```
 //!
 //! ## Example
@@ -56,13 +56,13 @@
 //! ```rust
 //! use std::sync::Arc;
 //!
-//! use miden_client::crypto::RpoRandomCoin;
-//! use miden_client::keystore::FilesystemKeyStore;
-//! use miden_client::note_transport::NOTE_TRANSPORT_DEFAULT_ENDPOINT;
-//! use miden_client::note_transport::grpc::GrpcNoteTransportClient;
-//! use miden_client::rpc::{Endpoint, GrpcClient};
-//! use miden_client::store::Store;
-//! use miden_client::{Client, ExecutionOptions, Felt};
+//! use miden_client_core::crypto::RpoRandomCoin;
+//! use miden_client_core::keystore::FilesystemKeyStore;
+//! use miden_client_core::note_transport::NOTE_TRANSPORT_DEFAULT_ENDPOINT;
+//! use miden_client_core::note_transport::grpc::GrpcNoteTransportClient;
+//! use miden_client_core::rpc::{Endpoint, GrpcClient};
+//! use miden_client_core::store::Store;
+//! use miden_client_core::{Client, ExecutionOptions, Felt};
 //! use miden_client_sqlite_store::SqliteStore;
 //! use miden_objects::crypto::rand::FeltRng;
 //! use miden_objects::{MAX_TX_EXECUTION_CYCLES, MIN_TX_EXECUTION_CYCLES};

crates/rust-client/src/sync/mod.rs → crates/miden-client-core/src/sync/mod.rs

@@ -100,26 +100,12 @@ where
         self.store.get_sync_height().await.map_err(Into::into)
     }
 
-    /// Syncs the client's state with the current state of the Miden network and returns a
-    /// [`SyncSummary`] corresponding to the local state update.
+    /// Performs a sync against the network and returns the raw [`StateSyncUpdate`].
     ///
-    /// The sync process is done in multiple steps:
-    /// 1. A request is sent to the node to get the state updates. This request includes tracked
-    ///    account IDs and the tags of notes that might have changed or that might be of interest to
-    ///    the client.
-    /// 2. A response is received with the current state of the network. The response includes
-    ///    information about new/committed/consumed notes, updated accounts, and committed
-    ///    transactions.
-    /// 3. Tracked notes are updated with their new states.
-    /// 4. New notes are checked, and only relevant ones are stored. Relevant notes are those that
-    ///    can be consumed by accounts the client is tracking (this is checked by the
-    ///    [`crate::note::NoteScreener`])
-    /// 5. Transactions are updated with their new states.
-    /// 6. Tracked public accounts are updated and private accounts are validated against the node
-    ///    state.
-    /// 7. The MMR is updated with the new peaks and authentication nodes.
-    /// 8. All updates are applied to the store to be persisted.
-    pub async fn sync_state(&mut self) -> Result<SyncSummary, ClientError> {
+    /// This does **not** apply the update to the store. Consumers can either call
+    /// [`Client::apply_state_sync`] manually or use [`Client::sync_state`], which wraps this
+    /// method and applies the update automatically.
+    pub async fn sync_state_update(&mut self) -> Result<StateSyncUpdate, ClientError> {
         _ = self.ensure_genesis_in_place().await?;
 
         let note_screener = NoteScreener::new(self.store.clone(), self.authenticator.clone());
@@ -165,17 +151,25 @@ where
             )
             .await?;
 
+        Ok(state_sync_update)
+    }
+
+    /// Syncs the client's state with the current state of the Miden network and returns a
+    /// [`SyncSummary`] corresponding to the local state update.
+    ///
+    /// This wraps [`Client::sync_state_update`] and applies the resulting update to the store.
+    pub async fn sync_state(&mut self) -> Result<SyncSummary, ClientError> {
+        let state_sync_update = self.sync_state_update().await?;
+
         let sync_summary: SyncSummary = (&state_sync_update).into();
         debug!(sync_summary = ?sync_summary, "Sync summary computed");
         info!("Applying changes to the store.");
 
-        // Apply received and computed updates to the store
         self.store
             .apply_state_sync(state_sync_update)
             .await
             .map_err(ClientError::StoreError)?;
 
-        // Remove irrelevant block headers
         self.store.prune_irrelevant_blocks().await?;
 
         Ok(sync_summary)
@@ -196,7 +190,7 @@ where
 // ================================================================================================
 
 /// Contains stats about the sync operation.
-#[derive(Debug, PartialEq)]
+#[derive(Debug, PartialEq, Clone)]
 pub struct SyncSummary {
     /// Block number up to which the client has been synced.
     pub block_num: BlockNumber,

crates/rust-client/src/transaction/request/mod.rs → crates/miden-client-core/src/transaction/request/mod.rs

@@ -99,6 +99,10 @@ pub struct TransactionRequest {
 }
 
 impl TransactionRequest {
+    pub fn builder() -> TransactionRequestBuilder {
+        TransactionRequestBuilder::new()
+    }
+
     // PUBLIC ACCESSORS
     // --------------------------------------------------------------------------------------------