Struct Client

pub struct Client<R: FeltRng> { /* private fields */ }

A light client for connecting to the Miden network.

Miden client is responsible for managing a set of accounts. Specifically, the client:

• Keeps track of the current and historical states of a set of accounts and related objects such as notes and transactions.
• Connects to a Miden node to periodically sync with the current state of the network.
• Executes, proves, and submits transactions to the network as directed by the user.

Implementations

impl<R: FeltRng> Client<R>

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.

pub async fn add_account( &mut self, account: &Account, account_seed: Option<Word>, auth_secret_key: &AuthSecretKey, overwrite: bool, ) -> Result<(), ClientError>

Adds the provided Account in the store so it can start being tracked by the client.

If the account is already being tracked and overwrite is set to true, the account will be overwritten. The account_seed should be provided if the account is newly created. The auth_secret_key is stored in client but it is never exposed. It is used to authenticate transactions against the account. The seed is used when notifying the network about a new account and is not used for any other purpose.

Errors

• 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.
• If overwrite is set to true and the account_data hash doesn’t match the network’s account hash.

pub async fn get_account_headers( &self, ) -> Result<Vec<(AccountHeader, AccountStatus)>, ClientError>

Returns a list of AccountHeader of all accounts stored in the database along with their statuses.

Said accounts’ state is the state after the last performed sync.

pub async fn get_account( &self, account_id: AccountId, ) -> Result<Option<AccountRecord>, ClientError>

Retrieves a full AccountRecord object for the specified account_id. This result represents data for the latest state known to the client, alongside its status. Returns None if the account ID is not found.

pub async fn get_account_header_by_id( &self, account_id: AccountId, ) -> Result<Option<(AccountHeader, AccountStatus)>, ClientError>

Retrieves an AccountHeader object for the specified AccountId along with its status. Returns None if the account ID is not found.

Said account’s state is the state according to the last sync performed.

pub async fn get_account_auth( &self, account_id: AccountId, ) -> Result<Option<AuthSecretKey>, ClientError>

Returns an AuthSecretKey object utilized to authenticate an account. Returns None if the account ID is not found.

pub async fn try_get_account( &self, account_id: AccountId, ) -> Result<AccountRecord, ClientError>

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_header( &self, account_id: AccountId, ) -> Result<(AccountHeader, AccountStatus), ClientError>

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_auth( &self, account_id: AccountId, ) -> Result<AuthSecretKey, ClientError>

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.

impl<R: FeltRng> Client<R>

Note importing methods.

pub async fn import_note( &mut self, note_file: NoteFile, ) -> Result<NoteId, ClientError>

Imports a new input note into the client’s store. The information stored depends on the type of note file provided. If the note existed previously, it will be updated with the new information. The tag specified by the NoteFile will start being tracked.

• If the note file is a NoteFile::NoteId, the note is fetched from the node and stored in the client’s store. If the note is private or doesn’t exist, an error is returned.
• If the note file is a NoteFile::NoteDetails, a new note is created with the provided details and tag.
• If the note file is a NoteFile::NoteWithProof, the note is stored with the provided inclusion proof and metadata. The block header data is only fetched from the node if the note is committed in the past relative to the client.

Errors

• If an attempt is made to overwrite a note that is currently processing.

impl<R: FeltRng> Client<R>

Note retrieval methods.

pub async fn get_input_notes( &self, filter: NoteFilter, ) -> Result<Vec<InputNoteRecord>, ClientError>

Retrieves the input notes managed by the client from the store.

Errors

Returns a ClientError::StoreError if the filter is NoteFilter::Unique and there is no Note with the provided ID.

pub async fn get_consumable_notes( &self, account_id: Option<AccountId>, ) -> Result<Vec<(InputNoteRecord, Vec<NoteConsumability>)>, ClientError>

Returns the input notes and their consumability.

If account_id is None then all consumable input notes are returned.

pub async fn get_note_consumability( &self, note: InputNoteRecord, ) -> Result<Vec<NoteConsumability>, ClientError>

Returns the consumability of the provided note.

pub async fn get_input_note( &self, note_id: NoteId, ) -> Result<Option<InputNoteRecord>, ClientError>

Retrieves the input note given a NoteId. Returns None if the note is not found.

pub async fn get_output_notes( &self, filter: NoteFilter, ) -> Result<Vec<OutputNoteRecord>, ClientError>

Returns output notes managed by this client.

pub async fn get_output_note( &self, note_id: NoteId, ) -> Result<Option<OutputNoteRecord>, ClientError>

Retrieves the output note given a NoteId. Returns None if the note is not found.

pub fn compile_note_script( &self, note_script: &str, ) -> Result<NoteScript, ClientError>

Compiles the provided program into a NoteScript.

The assembler uses the debug mode if the client was instantiated with debug mode on.

impl<R: FeltRng> Client<R>

Network information management methods.

pub async fn get_epoch_block( &mut self, block_num: BlockNumber, ) -> Result<BlockHeader, ClientError>

Returns the epoch block for the specified block number.

If the epoch block header is not stored, it will be retrieved and stored.

pub async fn get_latest_epoch_block( &mut self, ) -> Result<BlockHeader, ClientError>

Returns the epoch block for the latest tracked block.

If the epoch block header is not stored, it will be retrieved and stored.

impl<R: FeltRng> Client<R>

Tag management methods

pub async fn get_note_tags(&self) -> Result<Vec<NoteTagRecord>, ClientError>

Returns the list of note tags tracked by the client along with their source.

When syncing the state with the node, these tags will be added to the sync request and note-related information will be retrieved for notes that have matching tags. The source of the tag indicates its origin. It helps distinguish between:

• Tags added manually by the user.
• Tags automatically added by the client to track notes.
• Tags added for accounts tracked by the client.

Note: Tags for accounts that are being tracked by the client are managed automatically by the client and don’t need to be added here. That is, notes for managed accounts will be retrieved automatically by the client when syncing.

pub async fn add_note_tag(&mut self, tag: NoteTag) -> Result<(), ClientError>

Adds a note tag for the client to track. This tag’s source will be marked as User.

pub async fn remove_note_tag(&mut self, tag: NoteTag) -> Result<(), ClientError>

Removes a note tag for the client to track. Only tags added by the user can be removed.

impl<R: FeltRng> Client<R>

Client syncronization methods.

pub async fn get_sync_height(&self) -> Result<BlockNumber, ClientError>

Returns the block number of the last state sync block.

pub async fn sync_state(&mut self) -> Result<SyncSummary, ClientError>

Syncs the client’s state with the current state of the Miden network. Returns the block number the client has been synced to.

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 off-chain 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.

impl<R: FeltRng> Client<R>

Transaction management methods

pub async fn get_transactions( &self, filter: TransactionFilter, ) -> Result<Vec<TransactionRecord>, ClientError>

Retrieves tracked transactions, filtered by TransactionFilter.

pub async fn new_transaction( &mut self, account_id: AccountId, transaction_request: TransactionRequest, ) -> Result<TransactionResult, ClientError>

Creates and executes a transaction specified by the request against the specified account, but doesn’t change the local database.

If the transaction utilizes foreign account data, there is a chance that the client doesn’t have the required block header in the local database. In these scenarios, a sync to the chain tip is performed, and the required block header is retrieved.

Errors

• Returns ClientError::MissingOutputNotes if the TransactionRequest ouput notes are not a subset of executor’s output notes.
• Returns a ClientError::TransactionExecutorError if the execution fails.
• Returns a ClientError::TransactionRequestError if the request is invalid.

pub async fn submit_transaction( &mut self, tx_result: TransactionResult, ) -> Result<(), ClientError>

Proves the specified transaction using a local prover, submits it to the network, and saves the transaction into the local database for tracking.

pub async fn submit_transaction_with_prover( &mut self, tx_result: TransactionResult, tx_prover: Arc<dyn TransactionProver>, ) -> Result<(), ClientError>

Proves the specified transaction using the provided prover, submits it to the network, and saves the transaction into the local database for tracking.

pub fn compile_tx_script<T>( &self, inputs: T, program: &str, ) -> Result<TransactionScript, ClientError>

where T: IntoIterator<Item = (Word, Vec<Felt>)>,

Compiles the provided transaction script source and inputs into a TransactionScript.

pub async fn validate_request( &self, account_id: AccountId, transaction_request: &TransactionRequest, ) -> Result<(), ClientError>

Validates that the specified transaction request can be executed by the specified account.

This function checks that the account has enough balance to cover the outgoing assets. This does’t guarantee that the transaction will succeed, but it’s useful to avoid submitting transactions that are guaranteed to fail.

impl<R: FeltRng> Client<R>

Construction and access methods.

pub fn new( rpc_api: Box<dyn NodeRpcClient + Send>, rng: R, store: Arc<dyn Store>, authenticator: Arc<dyn TransactionAuthenticator>, in_debug_mode: bool, ) -> Self

Returns a new instance of Client.

Arguments

• api: An instance of NodeRpcClient which provides a way for the client to connect to the Miden node.
• store: An instance of Store, which provides a way to write and read entities to provide persistence.
• executor_store: An instance of Store that provides a way for TransactionExecutor to retrieve relevant inputs at the moment of transaction execution. It should be the same store as the one for store, but it doesn’t have to be the same instance.
• authenticator: Defines the transaction authenticator that will be used by the transaction executor whenever a signature is requested from within the VM.
• in_debug_mode: Instantiates the transaction executor (and in turn, its compiler) in debug mode, which will enable debug logs for scripts compiled with this mode for easier MASM debugging.

Errors

Returns an error if the client couldn’t be instantiated.

pub fn is_in_debug_mode(&self) -> bool

Returns true if the client is in debug mode.

pub fn rng(&mut self) -> &mut R

Returns a reference to the client’s random number generator. This can be used to generate randomness for various purposes such as serial numbers, keys, etc.