Struct Client 

pub struct Client<AUTH> { /* 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<AUTH> Client<AUTH>

This section of the Client contains methods for:

• Account creation: Use the AccountBuilder to construct new accounts, specifying account visibility (AccountType::Public / AccountType::Private) and attaching necessary components (e.g., basic wallet or fungible faucet). Prefer AccountBuilderSchemaCommitmentExt::build_with_schema_commitment so the account includes merged storage schema commitment metadata; use plain AccountBuilder::build only when you need to opt out. After creation, accounts 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.

• Account registration: On a network that enforces an account allowlist, Client::register_account binds an invitation code to a new account before its first transaction creates it on chain, and Client::is_account_allowed asks whether the network accepts the creation of an account.

• Data retrieval: The module also provides methods to fetch account-related data.

pub async fn add_account( &mut self, account: &Account, 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. Newly created accounts must embed their seed (account.seed() must return Some(_)).

Errors

• If the account is new but it does not contain the seed.
• 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 commitment doesn’t match the network’s account commitment.

pub async fn register_account( &self, account_id: AccountId, invitation_code: &str, ) -> Result<(), ClientError>

Binds an invitation code to a tracked account on the network allowlist.

A network that enforces an account allowlist creates an account on chain only when the account is registered. The first transaction of an account is what creates it, so the account must be registered before that transaction is submitted. Client::submit_new_transaction and BatchBuilder::submit ask the node first, and fail with ClientError::AccountNotAllowlisted for an account the network does not accept. Only account creation is gated: an account that already exists on chain is never checked, and network accounts are exempt.

The account must be tracked by the client, must not be deployed on chain yet, and must not be a network account. The invitation code must exist on the node and must not be bound to another account. A registration consumes the code, so the client asks the node first and does not send the code for an account the node already allows.

When the network operator runs a funding service, the node pays the registered account a public P2ID note with the native asset. The node answers once the funding service queues the note, before the note is committed. The note is not part of the response, and the client does not see it until a Client::sync_state runs after the note is committed. The client tracks the note tag of every account it owns, so that sync imports the note and Client::get_consumable_notes lists it. Sync again until the note arrives. The account then consumes the note in its first transaction. That transaction creates the account on chain and pays its fee out of the received funds.

Errors

• ClientError::AccountDataNotFound if the client does not track the account.
• ClientError::AccountIsNotNew if the account already exists on chain.
• ClientError::AccountIsNetworkAccount if the account is a network account. The node admits network accounts without a code.
• ClientError::AccountAlreadyAllowed if the node already allows the account, because it is registered or because the network does not enforce an allowlist. The code is not sent.
• ClientError::RpcError carrying a RegisterAccountError if the node rejects the code or the account, or an Unavailable status if the funding failed. In the second case the account stays registered, so a retry fails with ClientError::AccountAlreadyAllowed and the account has to be funded another way.

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

Returns whether the network lets account_id be created on chain.

The node answers true when it does not enforce an account allowlist, or when the account is registered. See Client::register_account for how an account gets registered.

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

Imports an account from the network to the client’s store. The account needs to be public and be tracked by the network, it will be fetched by its ID. If the account was already being tracked by the client, its state will be overwritten.

To import an account as watched (state-tracking only, no note sync), use Self::import_watched_account_by_id instead. Switching an already-tracked account between Native and Watched is not supported.

Errors

• If the account is not found on the network.
• If the account is private.
• If the account is already tracked as watched.
• There was an error sending the request to the network.

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

Starts watching an on-chain account (ClientAccountType::Watched).

Like Self::import_account_by_id, the account is fetched from the network by its ID. Unlike import_account_by_id, the account is added without registering its derived note tag: sync_state will keep the account’s commitment, nonce and storage up to date but will not pull notes targeted at it.

If the account is already being tracked as watched its state is overwritten. Switching an already-tracked native account to watched is not supported.

Errors

• If the account is not found on the network.
• If the account is private.
• If the account is already tracked as native.
• There was an error sending the request to the network.

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

Registers an account whose account witness Client::sync_chain keeps up to date, so that transactions using it as a foreign account resolve the witness locally. This trades one request per transaction for one per sync.

A ForeignAccount::Private needs nothing else, since the caller supplies the account data. A ForeignAccount::Public additionally has to be tracked by this client, so that its code, storage and vault come from the store as well; registering an untracked public account costs a request per sync and saves none.

The witness is fetched by the next sync, not by this call. Transactions assume that a sync ran after the account was registered.

The account is not validated against the network here. The sync fails while a registered account has no witness that the node can return, so an account that is not in the account tree blocks the sync until it is unregistered.

Registering an already registered account is a no-op and keeps any cached witness.

Returns true if the account was not registered before this call.

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

Stops keeping the account’s witness up to date and drops the cached one.

Returns true if the account was registered. Transactions using it keep working, falling back to fetching the witness from the node.

pub async fn tracked_account_witnesses( &self, ) -> Result<Vec<AccountId>, ClientError>

Returns the IDs of every account registered via Client::track_account_witness.

pub async fn fetch_remote_token_metadata( &self, faucet_id: AccountId, ) -> Result<Option<FaucetMetadata>, ClientError>

Fetches a public faucet’s display metadata from the network.

Uses get_account with a minimal request so that the node does not return vault data. The faucet’s token config lives in a single value slot, which is always present in the returned storage header.

Returns:

• Ok(Some(_)) — the account is public and its token config storage slot decoded.
• Ok(None) — the account is private, not on chain, or the storage slot does not parse as a token config. Caller should fall back to a raw display.
• Err(_) — transport-level RPC error.

pub async fn add_address( &mut self, address: Address, account_id: AccountId, ) -> Result<(), ClientError>

Adds an Address to the associated AccountId, alongside its derived NoteTag. If the account is tracked as watched, the note tag is not registered.

Errors

• If the account is not found on the network.
• If the address is already being tracked.

pub async fn remove_address( &mut self, address: Address, account_id: AccountId, ) -> Result<bool, ClientError>

Removes an Address from the associated AccountId, alongside its derived NoteTag.

Returns true if the address was tracked. If it wasn’t, this is a no-op: the derived tag is left in place, since it may have been registered by something other than this address.

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

Retrieves the asset vault for a specific account.

To check the balance for a single asset, use Client::account_reader instead.

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

Retrieves the whole account storage for a specific account.

To only load a specific slot, use Client::account_reader instead.

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

Retrieves the account code for a specific account.

Returns None if the account is not found.

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

Returns the AccountHeader of the account with the specified ID along with its status, or None if the account isn’t tracked by the client.

Said account’s state is the state after the last performed sync.

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

Retrieves the full Account object from the store, returning None if not found.

This method loads the complete account state including vault, storage, and code — including building the vault’s Merkle tree. For lazy access that fetches only the data you need (existence checks, single fields, storage items), use Client::account_reader instead.

pub fn account_reader(&self, account_id: AccountId) -> AccountReader

Creates an AccountReader for lazy access to account data.

The AccountReader provides lazy access to account state - each method call fetches fresh data from storage, ensuring you always see the current state.

For loading the full Account object, use Client::get_account instead.

Example

let reader = client.account_reader(account_id);

// Each call fetches fresh data
let nonce = reader.nonce().await?;
let balance = reader.get_balance(faucet_id).await?;

// Storage access is integrated
let value = reader.get_storage_item("my_slot").await?;
let (map_value, witness) = reader.get_storage_map_witness("balances", key).await?;

pub async fn prune_account_history( &self, account_id: AccountId, up_to_nonce: Felt, ) -> Result<usize, ClientError>

Prunes historical account states for the specified account up to the given nonce.

Deletes all historical entries with replaced_at_nonce <= up_to_nonce and any orphaned account code.

Returns the total number of rows deleted, including historical entries and orphaned account code.

impl<AUTH> Client<AUTH>

where AUTH: TransactionAuthenticator + Sync + 'static,

Note importing methods.

pub async fn import_notes( &mut self, note_files: &[NoteFile], ) -> Result<Vec<NoteDetailsCommitment>, ClientError>

Imports a batch of new input notes into the client’s store. The information stored depends on the type of note files provided. If the notes existed previously, it will be updated with the new information. The tags specified by the NoteFiles will start being tracked. Returns the details commitments of notes that were successfully imported or updated. The details commitment is used (rather than the note ID) because notes imported without metadata — e.g. from NoteFile::ExpectedNote in an Expected state — have no note ID yet, whereas the details commitment is always available.

• If the note files are NoteFile::NoteId, the notes are 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 files are NoteFile::ExpectedNote, new notes are created with the provided details and tags.
• If the note files are NoteFile::Committed, the notes are 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.

Note: This operation is atomic. If any note file is invalid or any existing note is in the processing state, the entire operation fails and no notes are imported.

impl<AUTH> Client<AUTH>

where AUTH: TransactionAuthenticator + Sync,

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. Assuming the notes will be consumed by a normal consume transaction. If account_id is None then all consumable input notes are returned.

The note screener runs a series of checks to determine whether the note can be executed as part of a transaction for a specific account. If the specific account ID can consume it (ie, if it’s compatible with the account), it will be returned as part of the result list.

Performance

This call screens every committed note tracked by the client on each invocation, without retaining verdicts between calls. When account_id is None the notes are screened against every account tracked by the client; when it is Some, only against that account. For notes whose consumability cannot be determined statically, the screener runs one trial transaction in the VM per (account, note) pair, so the cost grows with the number of screened accounts multiplied by the number of committed notes.

Consider cheaper alternatives when calling this function for accounts that accumulate committed-unconsumed notes, especially when used in polling loops:

• Query and filter the notes directly with Self::get_input_notes and NoteFilter::Committed if note consumability verdict is not needed.
• Wait for a specific note to commit with Self::get_input_note and InputNoteRecord::is_committed, instead of polling for it in the screened results.
• Screen a narrower set of notes with NoteScreener::get_batch_consumability or NoteScreener::get_batch_consumability_for_account, reached through Self::note_screener.

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

Returns the consumability conditions for the provided note.

The note screener runs a series of checks to determine whether the note can be executed as part of a transaction for a specific account. If the specific account ID can consume it (ie, if it’s compatible with the account), it will be returned as part of the result list.

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 input_note_reader(&self, consumer: AccountId) -> InputNoteReader

Returns an InputNoteReader that lazily iterates over consumed input notes for the given consumer account.

The consumer is required because ordering is only guaranteed among notes consumed by the same account.

Example

let mut reader = client.input_note_reader(account_id);

while let Some(note) = reader.next().await? {
    process(note);
}

impl<AUTH> Client<AUTH>

Client note transport methods.

pub const MAX_NOTE_TAGS_PER_TRANSPORT_REQUEST: usize = MAX_NOTE_TAGS_PER_TRANSPORT_REQUEST

Maximum number of note tags in one transport fetch request.

pub const MAX_ACCOUNT_TAGS: usize = Self::MAX_NOTE_TAGS_PER_TRANSPORT_REQUEST

👎Deprecated since 0.17.1:

use MAX_NOTE_TAGS_PER_TRANSPORT_REQUEST; account tags are no longer limited

Legacy name for Self::MAX_NOTE_TAGS_PER_TRANSPORT_REQUEST.

This value is not a limit on the number of account tags that the client can track.

pub fn is_note_transport_enabled(&self) -> bool

Check if note transport connection is configured

pub async fn send_private_note_with_proof( &mut self, note: Note, address: &Address, inclusion_proof: NoteInclusionProof, ) -> Result<(), ClientError>

Send a note through the note transport network together with its inclusion proof.

The note will be end-to-end encrypted (unimplemented, currently plaintext) using the provided recipient’s address details. The recipient will be able to retrieve this note through the note’s NoteTag.

The transport carries the proof through NoteTransportClient::send_note_with_proof. The network verifies inclusion_proof against its node before it stores the note and relays the exact commitment block to the recipient. The proof exists once the transaction that created the note is committed and the sender has synced past it; see OutputNoteRecord::inclusion_proof.

Failures. The client does not keep the note for a later attempt, and no sync sends it again. An error means that the note did not reach the network or that the result is not known. A send is idempotent by note id: the network stores a note only once, and the recipient imports it only once. The caller can therefore send the same note again, now or later. For a note that this client created, the output note record keeps the note and its inclusion proof, so a later attempt can read both from the store.

impl<AUTH> Client<AUTH>

where AUTH: TransactionAuthenticator + Sync + 'static,

pub const MAX_BACKFILL_TAGS_PER_SYNC: usize = 64

👎Deprecated since 0.17.1:

note transport no longer performs per-tag backfills

Legacy per-sync cap for tag backfills.

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

Fetch notes for tracked note tags.

The client queries the configured note transport node for all tracked tags. To list tracked tags, use Client::get_note_tags. To add a user-source tag, use Client::add_note_tag. Fetched notes are stored in the client store.

An internal pagination mechanism starts each request from the lowest cursor of its tags. Tags without a stored cursor start from the first retained note. The service can deliver a note again after a tag is added or removed; the import drops these duplicates.

A failed request returns an error after successful pages are imported and their cursors are saved. Histories that exceed the page budget continue on the next call.

impl<AUTH> Client<AUTH>

pub async fn seed_protocol_config( &self, config: ProtocolConfig, ) -> Result<(), ClientError>

Available on crate feature testing only.

Stores a protocol configuration for transaction execution and note screening, skipping the sync that normally delivers it.

A client that reaches a node gets its configurations from Client::sync_state. This is for a client that cannot sync, such as one backed by a mock chain.

pub async fn get_protocol_config( &self, commitment: Word, ) -> Result<ProtocolConfig, ClientError>

Returns the stored protocol configuration for the specified commitment.

impl<AUTH: TransactionAuthenticator + Sync + 'static> Client<AUTH>

pub async fn pswap_lineages( &self, ) -> Result<Vec<PswapLineageRecord>, ClientError>

Returns every PSWAP lineage tracked by this client.

pub async fn pswap_lineages_for( &self, creator: AccountId, ) -> Result<Vec<PswapLineageRecord>, ClientError>

Returns lineages created by a specific local account.

pub async fn pswap_active_lineages( &self, ) -> Result<Vec<PswapLineageRecord>, ClientError>

Returns the still-open PSWAP lineages — orders that are neither fully filled nor reclaimed (i.e. the creator’s live, reclaimable orders).

pub async fn pswap_lineage( &self, order_id: Felt, ) -> Result<Option<PswapLineageRecord>, ClientError>

Returns the lineage for one order, or None if not tracked.

pub async fn build_pswap_cancel_by_order( &self, order_id: Felt, ) -> Result<TransactionRequest, ClientError>

Builds a tx reclaiming the unfilled offered asset on the current tip of an Active lineage. See PswapLineageError for failure modes.

impl<AUTH> Client<AUTH>

This section of the Client contains methods for:

• Settings accessors: Methods to get, set, and delete setting values from the store.
• Default account ID: Methods to get, set, and delete the default account ID. This is a wrapper around a specific setting value.

pub async fn set_setting<T: Serializable>( &self, key: String, value: T, ) -> Result<(), ClientError>

Sets a setting value in the store. It can then be retrieved using get_setting.

pub async fn get_setting<T: Deserializable>( &self, key: String, ) -> Result<Option<T>, ClientError>

Retrieves the value for key, or None if it hasn’t been set.

pub async fn remove_setting(&self, key: String) -> Result<bool, ClientError>

Deletes the setting value from the store. Returns true if key had a value set.

pub async fn list_setting_keys(&self) -> Result<Vec<String>, ClientError>

Returns all the setting keys from the store.

impl<AUTH> Client<AUTH>

Network information management methods.

pub async fn get_block_header_by_num( &self, block_num: BlockNumber, ) -> Result<Option<(BlockHeader, BlockRelevance)>, ClientError>

Retrieves a block header by its block number from the store.

Returns None if the block header is not found in the store.

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

Retrieves the block header at the current sync height from the store.

pub async fn get_validator_config(&self) -> Result<ValidatorConfig, ClientError>

Retrieves the validator configuration committed by the block header at the current sync height.

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

Ensures that the genesis block is available. If the genesis commitment is already cached in the RPC client, returns early. Otherwise, fetches the genesis block from the node, stores it, and sets the commitment in the RPC client.

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

Available on crate feature testing only.

Seeds local state for offline account creation and debugging without a real node.

Applies default RPC limits, then either aligns the RPC genesis with an existing stored genesis, or replaces the RPC client with MockRpcApi and runs Self::ensure_genesis_in_place so genesis comes from the mock chain.

pub async fn get_current_partial_mmr(&self) -> Result<PartialMmr, ClientError>

Returns the cached PartialMmr if in-memory caching is enabled and its fingerprint matches the current store state, otherwise rebuilds from the store.

impl<AUTH> Client<AUTH>

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<bool, ClientError>

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

Returns true if the tag was added, and false if it was already being tracked.

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

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

Returns true if the tag was removed, and false if it was not being tracked.

impl<AUTH> Client<AUTH>

where AUTH: TransactionAuthenticator + Sync + 'static,

Client synchronization 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_chain(&mut self) -> Result<SyncSummary, ClientError>

Syncs the client’s on-chain state with the current state of the Miden network and returns a SyncSummary corresponding to the local state update.

Does not fetch private notes from the Note Transport Layer. Use Client::sync_state for the combined sync, or call Client::sync_note_transport separately.

Fetches everything from the node first (Client::fetch_chain_updates and StateSync::fetch_nullifiers), then applies the result with Client::apply_chain_updates, which also caches the partial MMR and prunes irrelevant blocks according to the configured cadence.

pub async fn fetch_chain_updates( &self, state_sync: &StateSync, ) -> Result<ChainSyncData, ClientError>

Fetches the node’s view of everything that changed since the client’s chain tip, without storing anything or modifying the partial MMR.

Builds the default sync input and runs StateSync::fetch_state, then adds the account witnesses the registered accounts still need. The state updates must be derived with StateSync::derive_state_updates. The nullifier check is not part of this: run StateSync::fetch_nullifiers on the result before applying it, so it can also cover transport-delivered notes another sync path fetched in the same call.

pub async fn apply_chain_updates( &mut self, state_sync: &StateSync, chain_sync_data: ChainSyncData, ) -> Result<SyncSummary, ClientError>

Verifies fetched chain data against the client’s partial MMR and saves the resulting update to the store.

StateSync::derive_state_updates and StateSync::fetch_nullifiers must have run on the data first. Also caches the partial MMR and prunes irrelevant blocks.

Errors

Returns an error if the client no longer starts where the data was fetched from, which means another sync advanced the store in between and the data is stale.

pub async fn sync_note_transport(&mut self) -> Result<Vec<NoteId>, ClientError>

Fetches private notes from the Note Transport Layer for the tracked note tags.

Returns the IDs of notes imported in this call. No-op (returns an empty vec) if note transport is disabled. A failed request returns an error after successful pages and their cursors are saved.

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

Runs the full client sync: private notes from the Note Transport Layer and the client’s on-chain state with the Miden node.

The NTL and the node are fetched concurrently, and everything that writes runs sequentially afterwards:

1. Concurrently: the note transport fetch and Client::fetch_chain_updates. Only node and NTL calls happen here, which is all that benefits from overlapping.
2. The transport writes, when its fetch succeeded, whose records are then tracked in the chain sync’s note updates.
3. StateSync::derive_state_updates, which screens the node’s notes against the store — hence after step 2, so a transport-delivered note is recognised rather than discarded — and applies a commitment reported this sync to those records.
4. StateSync::fetch_nullifiers, covering the tracked notes and the transport-delivered ones, so a note delivered and consumed in the same window is reported as consumed by this call.
5. The chain update, written last: a nullified transport-delivered note is saved as an update to the row step 2 inserts.

A transport failure is logged and the chain sync continues. Successful transport pages are imported and their cursors are saved. Failed requests keep their previous positions for retry. The sync sends no notes to the transport.

pub async fn build_sync_input(&self) -> Result<StateSyncInput, ClientError>

Builds a default StateSyncInput from the current client state.

This includes all tracked account headers, all unique note tags, all unspent input and output notes, and all uncommitted transactions.

pub async fn apply_state_sync( &mut self, update: StateSyncUpdate, ) -> Result<(), ClientError>

Applies the state sync update to the store and prunes irrelevant blocks according to the configured cadence.

See crate::Store::apply_state_sync() for what the update implies.

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

Ensures that the RPC limits are set in the RPC client. If not already cached, fetches them from the node and persists them in the store.

impl<AUTH> Client<AUTH>

where AUTH: TransactionAuthenticator + Sync + 'static,

pub fn new_transaction_batch(&mut self) -> BatchBuilder<'_, AUTH>

Open a new BatchBuilder for accumulating transactions across one or more local accounts.

See the module-level docs for usage and constraints.

pub async fn retry_proven_batch( &mut self, submission: &ProvenBatchSubmission, ) -> Result<BlockNumber, ClientError>

Resubmits an already-proven batch and returns the node’s chain tip upon mempool admission.

This is the retry entry point for a submission whose outcome was never confirmed: pass back the ProvenBatchSubmission carried by BatchBuilderError::BatchSubmissionOutcomeUnknown and the batch goes out again without being executed or proven a second time. The batch id is fixed, so resending it cannot duplicate its effects, but the node rejects it as a conflict if the original did land.

That error is the only source of a ProvenBatchSubmission: the type has no public constructor, and assembling and proving a batch goes through BatchBuilder.

A retry the node accepts records the batch the way the first send would have, so the transactions reach the store no matter which attempt landed. A retry the node rejects records nothing, and neither will a later sync: syncing updates records the client already holds and never inserts missing ones.

Errors

Returns BatchBuilderError::BatchSubmissionOutcomeUnknown when the submission comes back without a definite answer. Every other failure is a rejection the node issued deliberately.

impl<AUTH> Client<AUTH>

where AUTH: TransactionAuthenticator + Sync + 'static,

Transaction management methods

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

Retrieves tracked transactions, filtered by TransactionFilter.

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

Executes a transaction specified by the request against the specified account, proves it, submits it to the network, and updates the local database.

Uses the client’s default prover (configured via crate::builder::ClientBuilder::prover).

pub async fn submit_new_transaction_with_prover( &mut self, account_id: AccountId, transaction_request: TransactionRequest, tx_prover: Arc<dyn TransactionProver>, ) -> Result<TransactionId, ClientError>

Executes a transaction specified by the request against the specified account, proves it with the provided prover, submits it to the network, and updates the local database.

This is useful for falling back to a different prover (e.g., local) when the default prover (e.g., remote) fails with a ClientError::TransactionProvingError.

pub async fn execute_transaction( &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.

Errors

• Returns ClientError::MissingOutputRecipients if the TransactionRequest output 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 execute_transaction_at( &mut self, account_id: AccountId, transaction_request: TransactionRequest, anchor: ChainAnchor, ) -> Result<TransactionResult, ClientError>

Creates and executes a transaction specified by the request against the specified account, using the provided ChainAnchor as the reference block instead of the current sync height. Like Self::execute_transaction, it doesn’t change the local database.

Since protocol 0.16 the signed transaction summary binds the reference block commitment, so signatures collected over a summary only authorize an execution whose reference block is the one the summary was built at. This method makes such an execution reproducible on any client, regardless of its sync height: the anchor supplies the reference block header and a consistent PartialBlockchain, typically captured by the transaction’s original proposer via Self::chain_anchor_for_request and shipped alongside the signed data.

The anchor pins the reference block only. The mode each input note is consumed in also enters the summary, so a request shared across clients should pin it through TransactionRequestBuilder::explicit_input_notes. Otherwise each client classifies the notes from its own store, and two clients can commit to different input notes.

Callers holding an anchor from an untrusted source should first compare ChainAnchor::block_commitment against an independently trusted value (e.g. the block commitment bound into the signed transaction summary).

Foreign accounts are fetched at the anchor’s block unless declared as ForeignAccount::Prefetched, so a node that no longer serves account state at that block only affects accounts that are not prefetched.

Errors

In addition to the Self::execute_transaction errors:

• Returns ClientError::ChainAnchorError if an authenticated input note’s creation block is not tracked by the anchor.
• Returns a ClientError::TransactionExecutorError if an input note was created after the anchored reference block.
• Returns ChainAnchorError::AnchoredTransactionExpired if the executed transaction’s expiration block has already been reached, which the network would reject.

pub async fn chain_anchor_for_request( &self, transaction_request: &TransactionRequest, ) -> Result<ChainAnchor, ClientError>

Captures a ChainAnchor at the client’s current sync height. The anchor tracks the blocks declared through TransactionRequestBuilder::block_numbers and the creation blocks of the request’s authenticated input notes. This covers notes the store holds as authenticated and notes pinned as authenticated through TransactionRequestBuilder::explicit_input_notes.

This is the capture entry point for flows that never see a successful execution result at capture time — e.g. multisig proposal flows, where execution intentionally fails with TransactionExecutorError::Unauthorized to surface the transaction summary for signing. Capture the anchor first, execute the request with Self::execute_transaction_at, and ship the anchor alongside the summary; the same anchor then reproduces the summary during later verification and execution.

Errors

• Returns ClientError::StoreError if a header for the sync height or a tracked block is not present in the store.
• Returns ChainAnchorError::TooManyTrackedBlocks if the request needs more tracked blocks than an anchor permits.

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

Available on crate feature dap only.

Executes transaction_request (e.g. consuming a note) through the DAP program executor, so a DAP client can attach and step through the whole transaction — kernel, note scripts, and account code — instead of only a standalone transaction script.

This is a debugging entry point: it runs the transaction interactively under the debug adapter and does not prove, submit, or apply the result. The listen address (and optional replay-snapshot path) are taken from the globally installed DapConfig.

Errors

This applies the same request preparation and output-recipient validation as Self::execute_transaction, and returns the corresponding ClientError on failure.

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

Proves the specified transaction using the prover configured for this client.

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

Proves the specified transaction using the provided prover.

Errors

• Returns a ClientError::TransactionProvingError if the prover fails to produce a proof.
• Returns a ClientError::MismatchedProvenTransaction if the prover returns a proof of a transaction other than the requested one.

pub async fn submit_proven_transaction( &mut self, proven_transaction: ProvenTransaction, transaction_inputs: impl Into<TransactionInputs>, ) -> Result<BlockNumber, ClientError>

Submits a previously proven transaction to the RPC endpoint and returns the node’s chain tip upon mempool admission.

Errors

Returns ClientError::SubmissionOutcomeUnknown when the submission came back without a definite answer. It carries the proven transaction and the inputs it was submitted with, so a retry does not have to execute or prove again. Every other failure is a rejection the node issued deliberately.

pub async fn seed_transaction_encryption_key( &self, key: TransactionEncryptionKey, ) -> Result<(), ClientError>

Available on crate feature testing only.

Installs the transaction encryption key that submission seals against, skipping the fetch and its attestation check.

pub async fn get_transaction_store_update( &self, tx_result: &TransactionResult, submission_height: BlockNumber, ) -> Result<TransactionStoreUpdate, TransactionStoreUpdateError>

Builds a TransactionStoreUpdate for the provided transaction result at the specified submission height.

pub async fn apply_transaction( &self, tx_result: &TransactionResult, submission_height: BlockNumber, ) -> Result<(), ClientError>

Persists the effects of a submitted transaction into the local store, updating account data, note metadata, and future note tracking.

pub async fn apply_transaction_update( &self, tx_update: TransactionStoreUpdate, ) -> Result<(), ClientError>

pub async fn execute_program( &self, account_id: AccountId, tx_script: TransactionScript, advice_inputs: AdviceInputs, foreign_accounts: BTreeMap<AccountId, ForeignAccount>, ) -> Result<[Felt; 16], ClientError>

Executes the provided transaction script against the specified account, and returns the resulting stack. Advice inputs and foreign accounts can be provided for the execution.

The transaction will use the current sync height as the block reference.

pub async fn execute_program_with_dap( &self, account_id: AccountId, tx_script: TransactionScript, advice_inputs: AdviceInputs, foreign_accounts: BTreeMap<AccountId, ForeignAccount>, ) -> Result<[Felt; 16], ClientError>

Available on crate feature dap only.

Executes the provided transaction script with a DAP debug adapter listening for connections, allowing interactive debugging via any DAP-compatible client.

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 does’t guarantee that the transaction will succeed, but it’s useful to avoid submitting transactions that are guaranteed to fail. Some of the validations include:

• That the account has enough balance to cover the outgoing assets.
• That the client is not too far behind the chain tip.

pub async fn ensure_ntx_scripts_registered( &mut self, account_id: AccountId, scripts: &[NoteScript], tx_prover: Arc<dyn TransactionProver>, ) -> Result<(), ClientError>

Checks whether the node’s note_scripts registry already has each of the expected NTX scripts. For any script that is missing, creates and submits a registration transaction that produces a public note carrying that script.

account_id is the account that will execute the registration transaction.

Standard note scripts are skipped — the NTX builder resolves those directly, so they never need registering. A missing non-standard script is registered, not an error.

This method is called automatically by Self::submit_new_transaction_with_prover when the TransactionRequest contains expected NTX scripts. It can also be called directly if you want to register scripts ahead of time.

pub async fn get_foreign_account_inputs( &self, foreign_accounts: impl IntoIterator<Item = ForeignAccount>, block_num: BlockNumber, ) -> Result<Vec<AccountInputs>, ClientError>

Returns foreign account inputs for the required foreign accounts specified by the transaction request, with proofs anchored at block_num — the transaction’s reference block, so that the fetched state is consistent with the block the transaction executes against.

For any ForeignAccount::Public in foreign_accounts, these pieces of data are retrieved from the network. For any ForeignAccount::Private account, inner data is used and only a proof of the account’s existence on the network is fetched. A ForeignAccount::Prefetched account is returned as is.

Each witness opens against the account tree of block_num, so the results are valid only for a transaction whose reference block is exactly block_num. Declared as ForeignAccount::Prefetched, they are served from the request instead of being fetched. Under Self::execute_transaction_at the reference block is the anchor’s block; otherwise it is the sync height at execution time, so do not sync between fetching and executing. Only the given accounts are fetched; this method does not discover the accounts a transaction loads, such as faucets whose asset callbacks it triggers.

Errors

Returns an error if account data cannot be fetched or converted to transaction inputs.

impl<AUTH> Client<AUTH>

where AUTH: BuilderAuthenticator,

Constructors.

pub fn builder() -> ClientBuilder<AUTH>

Returns a new ClientBuilder for constructing a client.

This is a convenience method equivalent to calling ClientBuilder::new().

Example

let client = Client::builder()
    .rpc(rpc_client)
    .store(store)
    .authenticator(Arc::new(keystore))
    .build()
    .await?;

impl<AUTH> Client<AUTH>

where AUTH: TransactionAuthenticator,

Access methods.

pub fn code_builder(&self) -> CodeBuilder

Returns an instance of the CodeBuilder

pub fn note_screener(&self) -> NoteScreener

Returns an instance of note::NoteScreener configured for this client.

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

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.

pub fn prover(&self) -> Arc<dyn TransactionProver + Send + Sync>

pub fn authenticator(&self) -> Option<&Arc<AUTH>>

pub fn source_manager(&self) -> Arc<dyn SourceManagerSync>

Returns the shared source manager used to retain MASM source information for assembled programs.

impl<AUTH> Client<AUTH>

pub fn store_identifier(&self) -> &str

Returns the identifier of the underlying store (e.g. IndexedDB database name, SQLite file path).

pub fn with_transaction_observer( &mut self, observer: Arc<dyn TransactionObserver>, )

Registers a transaction::TransactionObserver. Per-observer failures are logged.

pub async fn network_id(&self) -> Result<NetworkId, ClientError>

Returns the network ID of the node the client is connected to.

pub fn test_rpc_api(&mut self) -> &mut Arc<dyn NodeRpcClient>

Available on crate features testing only.

pub fn test_store(&mut self) -> &mut Arc<dyn Store>

Available on crate features testing only.

pub fn test_has_cached_partial_mmr(&self) -> bool

Available on crate features testing only.

Trait Implementations

impl From<Client<FilesystemKeyStore>> for TestClient

Available on crate features std and testing only.

fn from(client: Client<FilesystemKeyStore>) -> Self

Converts to this type from the input type.