docs: Introduce top-level module docs for Rust client crate

.github/workflows/test.yml

@@ -17,6 +17,19 @@ jobs:
       - name: make - test
         run: make test
 
+  doc-tests:
+    name: doc-tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@main
+      - uses: Swatinem/rust-cache@v2
+        with:
+          save-if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/next' }}
+      - name: Install rust
+        run: rustup update --no-self-update
+      - name: Run doc-tests
+        run: make test-docs  
+
   integration-tests:
     name: Run integration tests on ubuntu-latest
     runs-on: ubuntu-latest

CHANGELOG.md

@@ -21,6 +21,7 @@
 * Added fixed seed option for web client generation (#688)
 * [BREAKING] Updated `init` command in the CLI to receive a `--network` flag (#690).
 * Improved CLI error messages (#682).
+* [BREAKING] Renamed APIs for retrieving account information to use the `try_get_*` naming convention, and added/improved module documentation (#683).
 
 ### Fixes
 

Makefile

@@ -6,6 +6,11 @@ help: ## Show description of all commands
 
 # --- Variables -----------------------------------------------------------------------------------
 
+# Enable file generation in the `src` directory.
+# This is used in the build script of the client to generate the node RPC-related code, from the
+# protobuf files.
+CODEGEN=CODEGEN=1
+
 FEATURES_WEB_CLIENT=--features "testing"
 FEATURES_CLIENT=--features "testing, concurrent" --no-default-features
 FEATURES_CLI=--features "concurrent"
@@ -76,29 +81,33 @@ doc: ## Generate & check rust documentation. You'll need `jq` in order for this
 
 .PHONY: test
 test: ## Run tests
-	CODEGEN=1 cargo nextest run --workspace --exclude miden-client-web --release --lib $(FEATURES_CLIENT)
+	$(CODEGEN) cargo nextest run --workspace --exclude miden-client-web --release --lib $(FEATURES_CLIENT)
 
 .PHONY: test-deps
 test-deps: ## Install dependencies for tests
-	CODEGEN=1 cargo install cargo-nextest
+	$(CODEGEN) cargo install cargo-nextest
+
+.PHONY: test-docs
+test-docs: ## Run documentation tests
+	$(CODEGEN) cargo test --doc $(FEATURES_CLIENT)
 
 # --- Integration testing -------------------------------------------------------------------------
 
 .PHONY: integration-test
 integration-test: ## Run integration tests
-	CODEGEN=1 cargo nextest run --workspace --exclude miden-client-web --release --test=integration $(FEATURES_CLI) 
+	$(CODEGEN) cargo nextest run --workspace --exclude miden-client-web --release --test=integration $(FEATURES_CLI) 
 
 .PHONY: integration-test-web-client
 integration-test-web-client: ## Run integration tests for the web client
-	CODEGEN=1 cd ./crates/web-client && npm run test:clean
+	$(CODEGEN) cd ./crates/web-client && npm run test:clean
 
 .PHONY: integration-test-remote-prover-web-client
 integration-test-remote-prover-web-client: ## Run integration tests for the web client with remote prover
-	CODEGEN=1 cd ./crates/web-client && npm run test:remote_prover
+	$(CODEGEN) cd ./crates/web-client && npm run test:remote_prover
 
 .PHONY: integration-test-full
 integration-test-full: ## Run the integration test binary with ignored tests included
-	CODEGEN=1 cargo nextest run --workspace --exclude miden-client-web --release --test=integration $(FEATURES_CLI)
+	$(CODEGEN) cargo nextest run --workspace --exclude miden-client-web --release --test=integration $(FEATURES_CLI)
 	cargo nextest run --workspace --exclude miden-client-web --release --test=integration $(FEATURES_CLI) --run-ignored ignored-only -- test_import_genesis_accounts_can_be_used_for_transactions
 
 .PHONY: kill-node

bin/miden-cli/src/commands/account.rs

@@ -1,7 +1,7 @@
 use clap::Parser;
 use miden_client::{
     account::{Account, AccountId, AccountType, StorageSlot},
-    assets::Asset,
+    asset::Asset,
     crypto::FeltRng,
     Client, ZERO,
 };
@@ -67,8 +67,7 @@ impl AccountCmd {
                             })?;
 
                             // Check whether we're tracking that account
-                            let (account, _) =
-                                client.get_account_header_or_error(account_id).await?;
+                            let (account, _) = client.try_get_account_header(account_id).await?;
 
                             Some(account.id())
                         };

bin/miden-cli/src/commands/init.rs

@@ -52,12 +52,12 @@ the CLI and client configurations, and will be placed by default in the current
 directory."
 )]
 pub struct InitCmd {
-    /// Network configuration to use. Options are devnet, testnet, localhost or a custom RPC
+    /// Network configuration to use. Options are `devnet`, `testnet`, `localhost` or a custom RPC
     /// endpoint. Defaults to the testnet network.
     #[clap(long, short, default_value = "testnet")]
     network: Option<Network>,
 
-    /// Store file path.
+    /// Path to the store file.
     #[clap(long)]
     store_path: Option<String>,
 

bin/miden-cli/src/commands/new_account.rs

@@ -4,7 +4,7 @@ use miden_client::{
         AccountBuilder, AccountStorageMode, AccountType, BasicFungibleFaucetComponent,
         BasicWalletComponent, RpoFalcon512Component,
     },
-    assets::TokenSymbol,
+    asset::TokenSymbol,
     auth::AuthSecretKey,
     crypto::{FeltRng, SecretKey},
     Client, Felt,

bin/miden-cli/src/commands/new_transactions.rs

@@ -3,7 +3,7 @@ use std::{io, sync::Arc};
 use clap::{Parser, ValueEnum};
 use miden_client::{
     account::AccountId,
-    assets::{FungibleAsset, NonFungibleDeltaAction},
+    asset::{FungibleAsset, NonFungibleDeltaAction},
     crypto::{Digest, FeltRng},
     note::{build_swap_tag, get_input_note_with_id_prefix, BlockNumber, NoteType as MidenNoteType},
     store::NoteRecordError,

bin/miden-cli/src/commands/notes.rs

@@ -2,7 +2,7 @@ use clap::ValueEnum;
 use comfy_table::{presets, Attribute, Cell, ContentArrangement, Table};
 use miden_client::{
     account::AccountId,
-    assets::Asset,
+    asset::Asset,
     crypto::{Digest, FeltRng},
     note::{
         get_input_note_with_id_prefix,

bin/miden-cli/src/faucet_details_map.rs

@@ -3,7 +3,7 @@ use std::{
     path::PathBuf,
 };
 
-use miden_client::{account::AccountId, assets::FungibleAsset};
+use miden_client::{account::AccountId, asset::FungibleAsset};
 use miden_lib::account::faucets::BasicFungibleFaucet;
 use serde::{Deserialize, Serialize};
 

crates/rust-client/README.md

@@ -12,14 +12,16 @@ miden-client = { version = "0.6" }
 
 ## Crate Features
 
-- `concurrent`: used to enable concurrency during execution and proof generation. Disabled by default.
-- `idxdb`: includes `WebStore`, an IdexedDB implementation of the `Store` trait. Disabled by default.
-- `sqlite`: includes `SqliteStore`, a SQLite implementation of the `Store` trait. Disabled by default.
-- `tonic`: includes `TonicRpcClient`, a Tonic client to communicate with Miden node. Disabled by default.
-- `web-tonic`: includes `WebTonicRpcClient`, an Tonic client to communicate with the Miden node in the browser. Disabled by default.
-- `testing`: useful feature that lowers PoW difficulty when enabled, meant to be used during development and not on production. Disabled by default.
-
-To compile with `no_std`, disable default features via `--no-default-features` flag.
+| Features     | Description                                                                                                                                               |
+| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `concurrent` | Used to enable concurrency during execution and proof generation. **Disabled by default.**                                                               |
+| `idxdb`      | Includes `WebStore`, an IndexedDB implementation of the `Store` trait. **Disabled by default.**                                                          |
+| `sqlite`     | Includes `SqliteStore`, a SQLite implementation of the `Store` trait. This relies on the standard library. **Disabled by default.**                                                           |
+| `tonic`      | Includes `TonicRpcClient`, a Tonic client to communicate with Miden node. This relies on the standard library. **Disabled by default.**                                                        |
+| `web-tonic`  | Includes `WebTonicRpcClient`, a Tonic client to communicate with the Miden node in the browser. **Disabled by default.**                                   |
+| `testing`    | Enables functions meant to be used in testing environments. **Disabled by default.**             |
+
+Features `sqlite` and `idxdb` are mutually exclusive.
 
 ### Store and RpcClient implementations
 

crates/rust-client/src/account.rs

@@ -1,8 +1,43 @@
-//! The `accounts` module provides types and client APIs for managing accounts within the Miden
-//! rollup network .
+//! The `account` module provides types and client APIs for managing accounts within the Miden
+//! network.
 //!
-//! Once accounts start being tracked by the client, their state will be
-//! updated accordingly on every transaction, and validated against the rollup on every sync.
+//! Accounts are foundational entities of the Miden protocol. They store assets and define
+//! rules for manipulating them. Once an account is registered with the client, its state will
+//! be updated accordingly, and validated against the network state on every sync.
+//!
+//! # Example
+//!
+//! To add a new account to the client's store, you might use the [`Client::add_account`] method as
+//! follows:
+//!
+//! ```rust
+//! # use miden_client::account::{Account, AccountBuilder, AccountType, BasicWalletComponent};
+//! # use miden_objects::account::{AuthSecretKey, AccountStorageMode};
+//! # use miden_client::crypto::{FeltRng, SecretKey};
+//! # async fn add_new_account_example(
+//! #     client: &mut miden_client::Client<impl FeltRng>
+//! # ) -> Result<(), miden_client::ClientError> {
+//! #   let random_seed = Default::default();
+//! let key_pair = SecretKey::with_rng(client.rng());
+//!
+//! let (account, seed) = AccountBuilder::new(random_seed)
+//!     .account_type(AccountType::RegularAccountImmutableCode)
+//!     .storage_mode(AccountStorageMode::Private)
+//!     .with_component(BasicWalletComponent)
+//!     .build()?;
+//!
+//! // Add the account to the client. The account seed and authentication key are required
+//! // for new accounts.
+//! client.add_account(&account,
+//!     Some(seed),
+//!     &AuthSecretKey::RpoFalcon512(key_pair),
+//!     false
+//! ).await?;
+//! #   Ok(())
+//! # }
+//! ```
+//!
+//! For more details on accounts, refer to the [Account] documentation.
 
 use alloc::vec::Vec;
 
@@ -15,14 +50,25 @@ pub use miden_objects::account::{
     Account, AccountBuilder, AccountCode, AccountData, AccountHeader, AccountId, AccountStorage,
     AccountStorageMode, AccountType, StorageSlot, StorageSlotType,
 };
-use miden_objects::{account::AuthSecretKey, crypto::rand::FeltRng, Digest, Word};
+use miden_objects::{account::AuthSecretKey, crypto::rand::FeltRng, Word};
 
 use super::Client;
 use crate::{
     store::{AccountRecord, AccountStatus},
     ClientError,
 };
 
+/// This section of the [Client] contains methods for:
+///
+/// - **Account creation:** Use the [`AccountBuilder`] to construct new accounts, specifying account
+///   type, storage mode (public/private), and attaching necessary components (e.g., basic wallet or
+///   fungible faucet). After creation, they can be added to the client.
+///
+/// - **Account tracking:** Accounts added via the client are persisted to the local store, where
+///   their state (including nonce, balance, and metadata) is updated upon every synchronization
+///   with the network.
+///
+/// - **Data retrieval:** The module also provides methods to fetch account-related data.
 impl<R: FeltRng> Client<R> {
     // ACCOUNT CREATION
     // --------------------------------------------------------------------------------------------
@@ -37,7 +83,7 @@ impl<R: FeltRng> Client<R> {
     ///
     /// # Errors
     ///
-    /// - Trying to import a new account without providing its seed.
+    /// - If the account is new but no seed is provided.
     /// - If the account is already tracked and `overwrite` is set to `false`.
     /// - If `overwrite` is set to `true` and the `account_data` nonce is lower than the one already
     ///   being tracked.
@@ -149,7 +195,13 @@ impl<R: FeltRng> Client<R> {
         self.store.get_account_auth(account_id).await.map_err(|err| err.into())
     }
 
-    pub async fn get_account_or_error(
+    /// Attempts to retrieve an [AccountRecord] by its [AccountId].
+    ///
+    /// # Errors
+    ///
+    /// - If the account record is not found.
+    /// - If the underlying store operation fails.
+    pub async fn try_get_account(
         &self,
         account_id: AccountId,
     ) -> Result<AccountRecord, ClientError> {
@@ -158,7 +210,13 @@ impl<R: FeltRng> Client<R> {
             .ok_or(ClientError::AccountDataNotFound(account_id))
     }
 
-    pub async fn get_account_header_or_error(
+    /// Attempts to retrieve an [AccountHeader] by its [AccountId].
+    ///
+    /// # Errors
+    ///
+    /// - If the account header is not found.
+    /// - If the underlying store operation fails.
+    pub async fn try_get_account_header(
         &self,
         account_id: AccountId,
     ) -> Result<(AccountHeader, AccountStatus), ClientError> {
@@ -167,7 +225,13 @@ impl<R: FeltRng> Client<R> {
             .ok_or(ClientError::AccountDataNotFound(account_id))
     }
 
-    pub async fn get_account_auth_or_error(
+    /// Attempts to retrieve an [AuthSecretKey] by the [AccountId] associated with the account.
+    ///
+    /// # Errors
+    ///
+    /// - If the key is not found for the passed `account_id`.
+    /// - If the underlying store operation fails.
+    pub async fn try_get_account_auth(
         &self,
         account_id: AccountId,
     ) -> Result<AuthSecretKey, ClientError> {
@@ -177,40 +241,6 @@ impl<R: FeltRng> Client<R> {
     }
 }
 
-// ACCOUNT UPDATES
-// ================================================================================================
-
-/// Contains account changes to apply to the store.
-pub struct AccountUpdates {
-    /// Updated public accounts.
-    updated_public_accounts: Vec<Account>,
-    /// Node account hashes that don't match the current tracked state for private accounts.
-    mismatched_private_accounts: Vec<(AccountId, Digest)>,
-}
-
-impl AccountUpdates {
-    /// Creates a new instance of `AccountUpdates`.
-    pub fn new(
-        updated_public_accounts: Vec<Account>,
-        mismatched_private_accounts: Vec<(AccountId, Digest)>,
-    ) -> Self {
-        Self {
-            updated_public_accounts,
-            mismatched_private_accounts,
-        }
-    }
-
-    /// Returns the updated public accounts.
-    pub fn updated_public_accounts(&self) -> &[Account] {
-        &self.updated_public_accounts
-    }
-
-    /// Returns the mismatched private accounts.
-    pub fn mismatched_private_accounts(&self) -> &[(AccountId, Digest)] {
-        &self.mismatched_private_accounts
-    }
-}
-
 // TESTS
 // ================================================================================================