Struct GrpcClient 

pub struct GrpcClient { /* private fields */ }

Available on crate feature tonic only.

Client for the Node RPC API using gRPC.

If the tonic feature is enabled, this client will use a tonic::transport::Channel to communicate with the node. In this case the connection will be established lazily when the first request is made. If the web-tonic feature is enabled, this client will use a tonic_web_wasm_client::Client to communicate with the node.

In both cases, the GrpcClient depends on the types inside the generated module, which are generated by the build script and also depend on the target architecture.

Implementations

impl GrpcClient

pub fn new(endpoint: &Endpoint, timeout_ms: u64) -> GrpcClient

Returns a new instance of GrpcClient that’ll do calls to the provided Endpoint with the given timeout in milliseconds.

pub fn with_max_retries(self, max_retries: u32) -> Self

Sets the maximum number of retry attempts for rate-limited or transiently unavailable requests. Defaults to 4.

pub fn with_retry_interval_ms(self, retry_interval_ms: u64) -> Self

Sets the fallback retry interval in milliseconds, used when the server does not provide a retry-after header. Defaults to 100 ms.

pub fn with_bearer_auth(self, token: String) -> Self

Attaches a authorization: Bearer <token> header to every outbound gRPC call made by this client, alongside the standard accept header.

Intended for connecting to a Miden node through an authenticating gateway (e.g. miden-testnet.eu-central-8.gateway.fm) that rate-limits unauthenticated traffic. Without an auth mechanism on the client side, callers would have no way to supply the token the gateway requires.

Calling this method twice overwrites the earlier token.

Validation of the token against AsciiMetadataValue is deferred to connection time (printable ASCII plus tab only — HeaderValue::from_str semantics): invalid tokens surface as RpcError::ConnectionError on the first request, so CR/LF header-injection attempts are rejected.

Example

let endpoint = Endpoint::new("https".into(), "node.example".into(), Some(443));
let client = GrpcClient::new(&endpoint, 10_000).with_bearer_auth("<api-key>".into());

pub async fn get_status_unversioned(&self) -> Result<RpcStatusInfo, RpcError>

Fetches RPC status without injecting an Accept header.

This instantiates a separate API client without the Accept interceptor, so it does not reuse the primary gRPC client. Any caller-supplied with_bearer_auth token is still forwarded so gateway authentication keeps working.

Trait Implementations

impl NodeRpcClient for GrpcClient

fn has_genesis_commitment(&self) -> Option<Word>

Sets the genesis commitment for the client. If the client is already connected, it will be updated to use the new commitment on subsequent requests. If the client is not connected, the commitment will be stored and used when the client connects. If the genesis commitment is already set, this method does nothing.

fn get_account<'life0, 'async_trait>( &'life0 self, account_id: AccountId, request: GetAccountRequest, ) -> Pin<Box<dyn Future<Output = Result<(BlockNumber, AccountProof), RpcError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Sends a GetAccount request to the Miden node, and extracts the AccountProof from the response, as well as the block number that it was retrieved for.

Errors

This function will return an error if:

• The requested Account isn’t returned by the node.
• There was an error sending the request to the node.
• The answer had a None for one of the expected fields.
• There is an error during storage deserialization.

fn sync_notes<'life0, 'life1, 'async_trait>( &'life0 self, block_from: BlockNumber, block_to: BlockNumber, note_tags: &'life1 BTreeSet<NoteTag>, ) -> Pin<Box<dyn Future<Output = Result<Vec<NoteSyncBlock>, RpcError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Sends one or more SyncNoteRequests to the node and merges the responses into a list of NoteSyncBlocks.

Chunks note_tags by RpcLimits::note_tags_limit and paginates each chunk across the requested block range.

fn sync_transactions<'life0, 'async_trait>( &'life0 self, block_from: BlockNumber, block_to: BlockNumber, account_ids: Vec<AccountId>, ) -> Pin<Box<dyn Future<Output = Result<Vec<TransactionRecord>, RpcError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Sends one or more SyncTransactions requests to the node and concatenates the responses into a flat list of TransactionRecords.

Chunks account_ids by RpcLimits::account_ids_limit and paginates each chunk across the requested block range.

fn set_genesis_commitment<'life0, 'async_trait>( &'life0 self, commitment: Word, ) -> Pin<Box<dyn Future<Output = Result<(), RpcError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Sets the genesis commitment for the client and reconnects to the node providing the genesis commitment in the request headers. If the genesis commitment is already set, this method does nothing.

fn submit_proven_transaction<'life0, 'async_trait>( &'life0 self, proven_transaction: ProvenTransaction, transaction_inputs: TransactionInputs, ) -> Pin<Box<dyn Future<Output = Result<BlockNumber, RpcError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Given a Proven Transaction, send it to the node for it to be included in a future block using the /SubmitProvenTransaction RPC endpoint.

fn submit_proven_batch<'life0, 'async_trait>( &'life0 self, proven_batch: ProvenBatch, proposed_batch: ProposedBatch, transaction_inputs: Vec<TransactionInputs>, ) -> Pin<Box<dyn Future<Output = Result<BlockNumber, RpcError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Given a Proven Batch together with the corresponding ProposedBatch and the list of TransactionInputs (one per transaction, matching the ordering of the batch), sends the batch to the node for inclusion in a future block using the /SubmitProvenBatch RPC endpoint. All transactions in the batch must build on the current mempool state following normal transaction submission rules.

fn get_block_header_by_number<'life0, 'async_trait>( &'life0 self, block_num: Option<BlockNumber>, include_mmr_proof: bool, ) -> Pin<Box<dyn Future<Output = Result<(BlockHeader, Option<MmrProof>), RpcError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Given a block number, fetches the block header corresponding to that height from the node using the /GetBlockHeaderByNumber endpoint. If include_mmr_proof is set to true and the function returns an Ok, the second value of the return tuple should always be Some(MmrProof).

fn get_notes_by_id<'life0, 'life1, 'async_trait>( &'life0 self, note_ids: &'life1 [NoteId], ) -> Pin<Box<dyn Future<Output = Result<Vec<FetchedNote>, RpcError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Fetches note-related data for a list of NoteId using the /GetNotesById RPC endpoint.

fn sync_chain_mmr<'life0, 'async_trait>( &'life0 self, current_block_height: BlockNumber, upper_bound: SyncTarget, ) -> Pin<Box<dyn Future<Output = Result<ChainMmrInfo, RpcError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Fetches the MMR delta for a given block range using the /SyncChainMmr RPC endpoint.

fn sync_nullifiers<'life0, 'life1, 'async_trait>( &'life0 self, prefixes: &'life1 [u16], block_from: BlockNumber, block_to: BlockNumber, ) -> Pin<Box<dyn Future<Output = Result<Vec<NullifierUpdate>, RpcError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Fetches the nullifiers corresponding to a list of prefixes using the /SyncNullifiers RPC endpoint.

fn get_block_by_number<'life0, 'async_trait>( &'life0 self, block_num: BlockNumber, include_proof: bool, ) -> Pin<Box<dyn Future<Output = Result<ProvenBlock, RpcError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Given a block number, fetches the block corresponding to that height from the node using the /GetBlockByNumber RPC endpoint.

fn get_note_script_by_root<'life0, 'async_trait>( &'life0 self, root: Word, ) -> Pin<Box<dyn Future<Output = Result<Option<NoteScript>, RpcError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Fetches the note script with the specified root, returning None if the node has no script registered for that root.

fn sync_storage_maps<'life0, 'async_trait>( &'life0 self, block_from: BlockNumber, block_to: BlockNumber, account_id: AccountId, ) -> Pin<Box<dyn Future<Output = Result<StorageMapInfo, RpcError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Fetches storage map updates for specified account and storage slots within a block range, using the /SyncStorageMaps RPC endpoint.

fn sync_account_vault<'life0, 'async_trait>( &'life0 self, block_from: BlockNumber, block_to: BlockNumber, account_id: AccountId, ) -> Pin<Box<dyn Future<Output = Result<AccountVaultInfo, RpcError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Fetches account vault updates for specified account within a block range, using the /SyncAccountVault RPC endpoint.

fn get_network_id<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<NetworkId, RpcError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Fetches the network ID of the node. Errors:

fn get_rpc_limits<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<RpcLimits, RpcError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Fetches the RPC limits configured on the node.

fn has_rpc_limits(&self) -> Option<RpcLimits>

Returns the RPC limits if they have been set, without fetching from the node.

fn set_rpc_limits<'life0, 'async_trait>( &'life0 self, limits: RpcLimits, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Sets the RPC limits internally to be used by the client.

fn get_status_unversioned<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<RpcStatusInfo, RpcError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Fetches the RPC status without requiring Accept header validation.

fn get_network_note_status<'life0, 'async_trait>( &'life0 self, note_id: NoteId, ) -> Pin<Box<dyn Future<Output = Result<NetworkNoteStatusInfo, RpcError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Fetches the status of a specific network note ID.

fn get_account_details<'life0, 'async_trait>( &'life0 self, account_id: AccountId, ) -> Pin<Box<dyn Future<Output = Result<Option<Account>, RpcError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Fetches the full state of a public account from the node using the /GetAccount endpoint, and then resolves oversized vault and storage map entries via the SyncVault and SyncStorageMap endpoints when needed.

fn sync_notes_with_details<'life0, 'life1, 'async_trait>( &'life0 self, block_from: BlockNumber, block_to: BlockNumber, note_tags: &'life1 BTreeSet<NoteTag>, ) -> Pin<Box<dyn Future<Output = Result<(Vec<NoteSyncBlock>, BTreeMap<NoteId, SyncedNoteDetails>), RpcError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Calls NodeRpcClient::sync_notes for the requested range, then makes a single NodeRpcClient::get_notes_by_id call to fetch full note bodies (scripts, assets, recipient) for public notes and attachment content for private notes that carry attachments.

fn resolve_oversize_vault<'life0, 'life1, 'async_trait>( &'life0 self, account_id: AccountId, block_to: BlockNumber, details: &'life1 mut AccountDetails, ) -> Pin<Box<dyn Future<Output = Result<(), RpcError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Fills in the asset list when the vault came back flagged too_many_assets, by querying NodeRpcClient::sync_account_vault over [GENESIS, block_to]. No-op when the flag isn’t set.

fn resolve_oversize_storage_maps<'life0, 'life1, 'async_trait>( &'life0 self, account_id: AccountId, block_to: BlockNumber, details: &'life1 mut AccountDetails, ) -> Pin<Box<dyn Future<Output = Result<(), RpcError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Fills in the entries of any storage map flagged too_many_entries, by querying NodeRpcClient::sync_storage_maps over [GENESIS, block_to]. No-op when no map has the flag set.

fn get_nullifier_commit_heights<'life0, 'async_trait>( &'life0 self, requested_nullifiers: BTreeSet<Nullifier>, block_from: BlockNumber, ) -> Pin<Box<dyn Future<Output = Result<BTreeMap<Nullifier, Option<BlockNumber>>, RpcError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Fetches the commit height where the nullifier was consumed. If the nullifier isn’t found, then None is returned. The block_num parameter is the block number to start the search from (inclusive).

fn get_public_note_records<'life0, 'life1, 'async_trait>( &'life0 self, note_ids: &'life1 [NoteId], current_timestamp: Option<u64>, ) -> Pin<Box<dyn Future<Output = Result<Vec<InputNoteRecord>, RpcError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Fetches public note-related data for a list of NoteId and builds InputNoteRecords with it. If a note is not found or it’s private, it is ignored and will not be included in the returned list.

fn get_block_header_with_proof<'life0, 'async_trait>( &'life0 self, block_num: BlockNumber, ) -> Pin<Box<dyn Future<Output = Result<(BlockHeader, MmrProof), RpcError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Given a block number, fetches the block header corresponding to that height from the node along with the MMR proof.

fn get_note_by_id<'life0, 'async_trait>( &'life0 self, note_id: NoteId, ) -> Pin<Box<dyn Future<Output = Result<FetchedNote, RpcError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Fetches the note with the specified ID.