Crate miden_client

Expand description

A no_std-compatible client library for interacting with the Miden network.

This crate provides a lightweight client that handles connections to the Miden node, manages accounts and their state, and facilitates executing, proving, and submitting transactions.

For a protocol-level overview and guides for getting started, please visit the official Miden docs.

§Overview

The library is organized into several key modules:

Accounts: Provides types for managing accounts. Once accounts are tracked by the client, their state is updated with every transaction and validated during each sync.
Notes: Contains types and utilities for working with notes in the Miden client.
RPC: Facilitates communication with Miden node, exposing RPC methods for syncing state, fetching block headers, and submitting transactions.
Store: Defines and implements the persistence layer for accounts, transactions, notes, and other entities.
Sync: Provides functionality to synchronize the local state with the current state on the Miden network.
Transactions: Offers capabilities to build, execute, prove, and submit transactions.

Additionally, the crate re-exports several utility modules:

Assembly: Types for working with Miden Assembly.
Assets: Types and utilities for working with assets.
Auth: Authentication-related types and functionalities.
Blocks: Types for handling block headers.
Crypto: Cryptographic types and utilities, including random number generators.
Utils: Miscellaneous utilities for serialization and common operations.

The library is designed to work in both no_std and std environments and is configurable via Cargo features.

§Usage

To use the Miden client library in your project, add it as a dependency in your Cargo.toml:

[dependencies]
miden-client = "0.10"

§Example

Below is a brief example illustrating how to instantiate the client:

use std::sync::Arc;

use miden_client::crypto::RpoRandomCoin;
use miden_client::keystore::FilesystemKeyStore;
use miden_client::rpc::{Endpoint, TonicRpcClient};
use miden_client::store::Store;
use miden_client::store::sqlite_store::SqliteStore;
use miden_client::{Client, ExecutionOptions, Felt};
use miden_objects::crypto::rand::FeltRng;
use miden_objects::{MAX_TX_EXECUTION_CYCLES, MIN_TX_EXECUTION_CYCLES};
use rand::Rng;
use rand::rngs::StdRng;

// Create the SQLite store from the client configuration.
let sqlite_store = SqliteStore::new("path/to/store".try_into()?).await?;
let store = Arc::new(sqlite_store);

// Generate a random seed for the RpoRandomCoin.
let mut rng = rand::rng();
let coin_seed: [u64; 4] = rng.random();

// Initialize the random coin using the generated seed.
let rng = RpoRandomCoin::new(coin_seed.map(Felt::new).into());
let keystore = FilesystemKeyStore::new("path/to/keys/directory".try_into()?)?;

// Determine the number of blocks to consider a transaction stale.
// 20 is simply an example value.
let tx_graceful_blocks = Some(20);
// Determine the maximum number of blocks that the client can be behind from the network.
// 256 is simply an example value.
let max_block_number_delta = Some(256);

// Instantiate the client using a Tonic RPC client
let endpoint = Endpoint::new("https".into(), "localhost".into(), Some(57291));
let client: Client<FilesystemKeyStore<StdRng>> = Client::new(
    Arc::new(TonicRpcClient::new(&endpoint, 10_000)),
    Box::new(rng),
    store,
    Some(Arc::new(keystore)), // or None if no authenticator is needed
    ExecutionOptions::new(
        Some(MAX_TX_EXECUTION_CYCLES),
        MIN_TX_EXECUTION_CYCLES,
        false,
        false, // Set to true for debug mode, if needed.
    )
    .unwrap(),
    tx_graceful_blocks,
    max_block_number_delta,
)
.await
.unwrap();

For additional usage details, configuration options, and examples, consult the documentation for each module.

Modules§

account: The account module provides types and client APIs for managing accounts within the Miden network.
assembly: Provides types and utilities for working with Miden Assembly.
asset: Provides types and utilities for working with assets within the Miden network.
auth: Provides authentication-related types and functionalities for the Miden network.
block: Provides types for working with blocks within the Miden network.
builder
crypto: Provides cryptographic types and utilities used within the Miden rollup network. It re-exports commonly used types and random number generators like FeltRng from the miden_objects crate.
keystore
note: Contains the Client APIs related to notes. Notes can contain assets and scripts that are executed as part of transactions.
rpc: Provides an interface for the client to communicate with a Miden node using Remote Procedure Calls (RPC).
store: Defines the storage interfaces used by the Miden client.
sync: Provides the client APIs for synchronizing the client’s local state with the Miden network. It ensures that the client maintains a valid, up-to-date view of the chain.
transaction: Provides APIs for creating, executing, proving, and submitting transactions to the Miden network.
utils: Provides various utilities that are commonly used throughout the Miden client library.

Structs§

Client: A light client for connecting to the Miden network.
ClientRng: A wrapper around a FeltRng that implements the RngCore trait. This allows the user to pass their own generic RNG so that it’s used by the client.
ExecutionOptions: A set of parameters specifying execution parameters of the VM.
Felt: Represents base field element in the field using Montgomery representation.
RemoteTransactionProver: A RemoteTransactionProver is a transaction prover that sends witness data to a remote gRPC server and receives a proven transaction.
ScriptBuilder: A builder for compiling note scripts and transaction scripts with optional library dependencies.
Word: A unit of data consisting of 4 field elements.

Enums§

AuthenticationError
ClientError: Errors generated by the client.
DebugMode: Indicates whether the client is operating in debug mode.
IdPrefixFetchError: Error when Looking for a specific ID from a partial ID.

Constants§

EMPTY_WORD: Array of field elements representing word of ZEROs in the Miden base field.
ONE: Field element representing ONE in the Miden base filed.
ZERO: Field element representing ZERO in the Miden base filed.

Traits§

StarkField: Defines an element in a STARK-friendly finite field.