Struct CantonClient 

pub struct CantonClient { /* private fields */ }

An async client for the Canton Ledger API over gRPC.

The client owns a lazily-connected Channel; cloning it is cheap and clones share the underlying connection pool, so it is safe to hand a clone to each task.

Implementations

impl CantonClient

pub fn connect_lazy(config: Config) -> Result<Self>

Build a lazily-connected client. Returns immediately; the TCP/TLS handshake happens on the first RPC.

Errors

Returns Error::InvalidRequest if the endpoint is not a valid URI.

pub async fn version(&self) -> Result<String>

Return the participant’s Ledger API version string (e.g. "3.5.7").

Errors

Returns an Error if the RPC fails.

pub async fn health_check(&self) -> Result<ServingStatus>

Probe the participant’s overall serving status via the standard grpc.health.v1.Health service (served on the Ledger API port).

Poll this to react to intermittent or permanent node failure: a healthy participant answers ServingStatus::Serving; an unreachable one surfaces a transport Error (see Error::is_retriable).

Errors

Returns an Error if the health RPC fails (e.g. the node is down).

pub async fn submit(&self, submit: Submit) -> Result<String>

Submit commands fire-and-forget (CommandSubmissionService.Submit): hand the commands to the participant and return promptly without waiting for the transaction. Returns the change-ID command_id used, so the caller can recover the outcome later with Self::await_completion (or the Self::completions stream).

A fresh UUID command_id is generated when the caller did not set one, so ledger-side de-duplication behaves correctly across retries.

Errors

Returns an Error if authentication fails or the participant rejects the submission synchronously (e.g. a preprocessing error).

pub fn submission(&self, submit: Submit) -> Submission

Fix a submission’s identity before sending it, returning a Submission that carries its ChangeId.

This is the handle to reach for when losing the outcome is not an option. A submission whose response is lost — a dropped connection, a timeout, a retry the participant de-duplicated — may well have committed, and the only way back to the answer is the change ID. If the SDK generated the command id inside the call that failed, there is no change ID to go back with.

use std::time::Duration;

// Where to start reading completions from, taken before submitting.
let offset = client.ledger_end().await?;
let submission = client.submission(submit);

if submission.submit_and_wait().await.is_err() {
    // Ambiguous: ask the ledger what actually happened.
    let completion = submission.recover(offset, Duration::from_secs(30)).await?;
    println!("committed after all: {}", completion.update_id);
}

pub async fn submit_and_wait( &self, submit: Submit, ) -> Result<SubmitAndWaitResponse>

Submit commands and wait for the result without fetching the transaction (CommandService.SubmitAndWait): blocks until the command commits (or is rejected) and returns the update_id and completion offset. Lighter than Self::submit_and_wait_for_transaction when the caller does not need the event payload.

Errors

Returns an Error if authentication fails or the command is rejected. The retry caveat on Self::submit_and_wait_for_transaction applies.

pub async fn submit_and_wait_for_transaction( &self, submit: Submit, ) -> Result<Transaction>

Submit commands and wait for the resulting transaction.

Fills the change ID’s command_id with a fresh UUID when the caller did not set one, so ledger-side de-duplication behaves correctly. The returned transaction is shaped as LEDGER_EFFECTS and filtered to the acting party (wildcard), so created events are visible in the response.

Errors

Returns an Error if authentication fails, the command is rejected, or the response contains no transaction.

Example

use canton_ledger::{Submit, create, identifier, record};

let tx = client
    .submit_and_wait_for_transaction(
        Submit::new(party)
            .add_command(create(identifier(pkg, "M", "T"), record(vec![]))),
    )
    .await?;
println!("committed {} at offset {}", tx.update_id, tx.offset);

Retry caveat (exactly-once)

With retry enabled (Config::with_retry), a submission that commits on the ledger but whose response is lost to a retriable error is re-sent with the same command_id and de-duplicated by the participant.

Self::submit can answer that on its own: a duplicate rejection of a retry it made itself means its earlier attempt was accepted, which is success, so it reports success. This method cannot. Its result is the committed transaction, and a de-duplicated retry does not carry one — so the duplicate rejection reaches the caller, and the transaction has to be read back rather than invented.

Take a Submission from Self::submission before submitting, and on any error recover the outcome with Submission::recover — it knows the change ID, which is the only way back to a command whose response was lost. See the recover_a_submission example.

pub async fn connected_synchronizers( &self, party: &str, ) -> Result<Vec<ConnectedSynchronizer>>

The synchronizers this participant is connected to for party.

Allocating an external party and preparing a submission both name a synchronizer, and a caller has no other way to discover one — so this is what turns “which synchronizer?” from configuration into a question the participant answers.

Errors

Returns an Error if the RPC fails.

pub async fn prepare_submission(&self, prepare: Prepare) -> Result<Prepared>

Interpret a submission without authorizing it, returning the transaction and the hash to sign.

The first half of interactive submission: the participant works out what the commands do, and hands back a hash for the party’s key — which it does not hold — to sign. See crate::interactive for the flow, and for how long a prepared transaction stays executable.

Retried like any other read: preparation commits nothing.

Errors

As any gRPC call, plus Error::UnexpectedResponse if the participant returns no hash — which would leave nothing to sign.

pub async fn execute_submission(&self, executable: Executable) -> Result<()>

Submit a signed prepared transaction and return once the participant has accepted it for processing.

Acceptance is not commitment: the outcome arrives on the completion stream. Use execute_submission_and_wait to wait for it.

Retry caveat

With retry enabled, an attempt whose response was lost is retried under a fresh submission id and the same change id, and the participant answers ALREADY_EXISTS: that is the earlier attempt having landed, and it is reported as success here, as on submit. An Ok still means only accepted; whether it committed is a completion, reachable by await_completion with the Executable::change_id taken before the call.

Errors

As any gRPC call. A missing or wrong signature is a rejection from the participant, not a local error.

pub async fn execute_submission_and_wait( &self, executable: Executable, ) -> Result<ExecuteSubmissionAndWaitResponse>

Submit a signed prepared transaction and wait for it to commit.

The response carries the update id and the completion offset — the offset a follow-up completion or update read starts from, which is why it is returned whole rather than as the id alone.

Retry caveat

As execute_submission: a retried attempt that the participant de-duplicates is reported as the rejection it answers with, so on an ambiguous outcome recover through await_completion with the change id taken before the call.

Errors

As any gRPC call, plus a rejection if the transaction fails.

pub async fn execute_submission_and_wait_for_transaction( &self, executable: Executable, ) -> Result<Transaction>

Submit a signed prepared transaction and wait for the committed transaction itself.

The events it carries follow Executable::with_transaction_shape.

Errors

As any gRPC call, plus Error::UnexpectedResponse if the participant reports success without a transaction.

pub async fn completions( &self, parties: Vec<String>, begin_offset: i64, ) -> Result<impl Stream<Item = Result<Completion>> + Send + use<>>

Subscribe to the command-completion stream for parties, starting after begin_offset (exclusive). Offset checkpoints are filtered out, so the stream yields only pb::Completions.

Errors

Returns an Error if authentication or opening the stream fails.

pub async fn completions_with( &self, request: CompletionsRequest, ) -> Result<impl Stream<Item = Result<Completion>> + Send + use<>>

Like Self::completions, with the full request surface: a CompletionsRequest additionally selects the user_id whose command completions to stream (pair it with Submit::with_user_id).

Errors

Returns an Error if authentication or opening the stream fails.

pub async fn await_completion( &self, change_id: &ChangeId, begin_offset: i64, timeout: Duration, ) -> Result<Completion>

Recover the completion for a specific command by scanning the completion stream from begin_offset, up to timeout.

This is the command-recovery path: after a crash, lost connection, or timeout, the outcome of a pending command is read back from the completion endpoint instead of blindly re-submitting. If the command’s completion reports a non-OK status, this returns Error::CommandRejected.

Matching is on the whole ChangeId — user, acting parties and command id — because that is what identifies a command to Canton. A command id on its own is not unique across the users of a participant, and answering with somebody else’s completion is worse than answering with none.

The completion stream is a live subscription that does not self-terminate, so timeout bounds how long to wait for the target completion.

Errors

Returns Error::Timeout if the completion is not seen within timeout, Error::CommandRejected if the ledger rejected the command, or another Error if the stream fails.

pub async fn ledger_end(&self) -> Result<i64>

Return the current ledger end offset as seen by the participant.

A value of 0 means the participant’s view of the ledger is empty. This is an authenticated endpoint.

Errors

Returns an Error if authentication or the RPC fails.

pub async fn events_by_contract_id( &self, contract_id: impl Into<String>, parties: Vec<String>, ) -> Result<GetEventsByContractIdResponse>

Fetch the created and/or archived events for a contract by id (EventQueryService.GetEventsByContractId), with verbose records and no created-event blob. To obtain a contract’s created_event_blob (for disclosure), use a template-filtered Self::active_contracts_with read with ActiveContractsRequest::with_created_event_blobs.

Errors

Returns an Error if authentication or the RPC fails.

pub async fn latest_pruned_offsets(&self) -> Result<PrunedOffsets>

How far the participant has pruned (StateService.GetLatestPrunedOffsets).

A read that starts at or below participant_pruned_up_to_inclusive is refused; Error::pruned_earliest_offset says the same thing after the fact, on the error such a read returns.

Errors

Returns an Error if authentication or the RPC fails.

pub async fn update_by_offset( &self, offset: i64, parties: Vec<String>, ) -> Result<Option<Update>>

The update at offset, as parties see it (UpdateService.GetUpdateByOffset), in the default format of UpdatesRequest::new.

Reading back a stored offset without scanning a stream to it. Ok(None) when there is no update at that offset visible to parties.

Errors

Returns an Error if authentication or the RPC fails.

pub async fn update_by_offset_with( &self, offset: i64, format: &UpdatesRequest, ) -> Result<Option<Update>>

Like Self::update_by_offset, in the format an UpdatesRequest describes (parties, template or interface filters, transaction shape, created-event blobs, reassignments, topology events, verbosity). Its offsets are not used.

Errors

Returns an Error if the request names no party, or authentication or the RPC fails.

pub async fn update_by_id( &self, update_id: impl Into<String>, parties: Vec<String>, ) -> Result<Option<Update>>

The update with id update_id, as parties see it (UpdateService.GetUpdateById), in the default format of UpdatesRequest::new.

The id is what a submission’s completion and its transaction carry, so this reads back the outcome of a command without scanning for it. Ok(None) when no update with that id is visible to parties.

Errors

Returns an Error if authentication or the RPC fails.

pub async fn update_by_id_with( &self, update_id: impl Into<String>, format: &UpdatesRequest, ) -> Result<Option<Update>>

Like Self::update_by_id, in the format an UpdatesRequest describes. Its offsets are not used.

Errors

Returns an Error if the request names no party, or authentication or the RPC fails.

pub async fn active_contracts_page( &self, parties: Vec<String>, active_at_offset: i64, max_page_size: i32, page_token: Option<Vec<u8>>, ) -> Result<(Vec<ActiveContract>, Option<Vec<u8>>)>

Fetch one page of the Active Contract Set for parties as of active_at_offset. Returns the page’s active contracts and the next page token (None once the last page has been read); pass the token back in to fetch the following page.

Errors

Returns an Error if authentication or the RPC fails.

pub async fn active_contracts_page_with( &self, request: &ActiveContractsRequest, max_page_size: i32, page_token: Option<Vec<u8>>, ) -> Result<(Vec<ActiveContract>, Option<Vec<u8>>)>

Like Self::active_contracts_page, with the full request surface of an ActiveContractsRequest (template/interface filters, created-event blobs, non-verbose records).

Errors

Returns an Error if authentication or the RPC fails.

pub async fn acs_page( &self, parties: Vec<String>, active_at_offset: i64, max_page_size: i32, page_token: Option<Vec<u8>>, ) -> Result<(Vec<AcsEntry>, Option<Vec<u8>>)>

One page of the Active Contract Set for parties, losslessly: every entry the participant sent, active or incomplete (see AcsEntry).

Errors

Returns an Error if authentication or the RPC fails.

pub async fn acs_page_with( &self, request: &ActiveContractsRequest, max_page_size: i32, page_token: Option<Vec<u8>>, ) -> Result<(Vec<AcsEntry>, Option<Vec<u8>>)>

Like Self::acs_page, with the full request surface of an ActiveContractsRequest.

Errors

Returns an Error if authentication or the RPC fails.

pub async fn updates_page( &self, parties: Vec<String>, begin_offset_exclusive: i64, end_offset_inclusive: i64, max_page_size: i32, descending: bool, page_token: Option<Vec<u8>>, ) -> Result<(Vec<GetUpdateResponse>, Option<Vec<u8>>)>

Fetch one page of updates in the offset range (begin_offset_exclusive, end_offset_inclusive], optionally in reverse (descending) order. Returns the page items and the next page token (None once the last page has been read).

Errors

Returns an Error if authentication or the RPC fails.

pub async fn updates_page_with( &self, request: &UpdatesRequest, max_page_size: i32, page_token: Option<Vec<u8>>, ) -> Result<(Vec<GetUpdateResponse>, Option<Vec<u8>>)>

Like Self::updates_page, with the full request surface of an UpdatesRequest (template/interface filters, transaction shape, descending order, created-event blobs, topology events, non-verbose records). The request’s bounds supply the page range, so UpdatesRequest::until is required here — the paged read is inherently bounded.

Errors

Returns Error::InvalidRequest if the request has no end offset, or another Error if authentication or the RPC fails.

pub async fn active_contracts( &self, parties: Vec<String>, active_at_offset: i64, ) -> Result<impl Stream<Item = Result<ActiveContract>> + Send + use<>>

Stream the Active Contract Set for parties as of active_at_offset (typically the current ledger end). Yields the active contracts, wildcard-filtered to the given parties.

Errors

Returns an Error if authentication or opening the stream fails.

pub async fn active_contracts_with( &self, request: ActiveContractsRequest, ) -> Result<impl Stream<Item = Result<ActiveContract>> + Send + use<>>

Like Self::active_contracts, with the full request surface: an ActiveContractsRequest additionally filters by template or interface, includes created-event blobs, and drops record labels.

Errors

Returns an Error if authentication or opening the stream fails.

pub async fn acs_entries( &self, parties: Vec<String>, active_at_offset: i64, ) -> Result<impl Stream<Item = Result<AcsEntry>> + Send + use<>>

Stream the Active Contract Set for parties losslessly: every entry the participant sends, active or incomplete (see AcsEntry).

Errors

Returns an Error if authentication or opening the stream fails.

pub async fn acs_entries_with( &self, request: ActiveContractsRequest, ) -> Result<impl Stream<Item = Result<AcsEntry>> + Send + use<>>

Like Self::acs_entries, with the full request surface of an ActiveContractsRequest.

Errors

Returns an Error if authentication or opening the stream fails.

pub fn active_contracts_resumable( &self, parties: Vec<String>, active_at_offset: i64, max_page_size: i32, ) -> impl Stream<Item = Result<ActiveContract>> + Send + use<>

Like Self::active_contracts, but resumable: reads the ACS snapshot page-by-page (continuation tokens), retrying a failed page on retriable errors from the last token instead of restarting the snapshot from zero. max_page_size bounds each page RPC.

pub fn active_contracts_resumable_with( &self, request: ActiveContractsRequest, max_page_size: i32, ) -> impl Stream<Item = Result<ActiveContract>> + Send + use<>

Like Self::active_contracts_resumable, with the full request surface of an ActiveContractsRequest.

pub fn acs_entries_resumable( &self, parties: Vec<String>, active_at_offset: i64, max_page_size: i32, ) -> impl Stream<Item = Result<AcsEntry>> + Send + use<>

Like Self::acs_entries, but resumable and page-based: reads the snapshot page by page and retries a failed page from the last continuation token instead of restarting from zero. Every entry the participant sent is yielded (see AcsEntry).

pub fn acs_entries_resumable_with( &self, request: ActiveContractsRequest, max_page_size: i32, ) -> impl Stream<Item = Result<AcsEntry>> + Send + use<>

Like Self::acs_entries_resumable, with the full request surface of an ActiveContractsRequest.

pub async fn updates( &self, parties: Vec<String>, begin_offset: i64, ) -> Result<impl Stream<Item = Result<Update>> + Send + use<>>

Stream ledger updates — transactions and reassignments — for parties, starting after begin_offset (exclusive). Offset checkpoints are filtered out. Reassignments are surfaced as their own case (each carrying the distinct Unassigned/Assigned events). Topology events are not included; ask for them with UpdatesRequest::with_topology_events on Self::updates_with.

Errors

Returns an Error if authentication or opening the stream fails.

pub async fn updates_with( &self, request: UpdatesRequest, ) -> Result<impl Stream<Item = Result<Update>> + Send + use<>>

Like Self::updates, with the full request surface: an UpdatesRequest additionally bounds the stream at an end offset (until — the catch-up/sync form, after which the stream terminates), filters by template or interface, selects the ACS-delta shape, includes created-event blobs or topology events, and drops reassignments or record labels.

Errors

Returns an Error if authentication or opening the stream fails.

pub async fn updates_typed_with( &self, request: UpdatesRequest, ) -> Result<impl Stream<Item = Result<Update>> + Send + use<>>

Like Self::updates_with, as the SDK’s own Update: the type JsonClient::updates_typed_with returns too, so code that reads updates depends on neither the transport nor the vendored protos (ADR-0010 §4). Checkpoints are dropped, as Self::updates_with drops them.

Errors

Returns an Error if authentication or opening the stream fails; the stream yields one for a malformed update.

pub fn updates_resumable( &self, parties: Vec<String>, begin_offset: i64, ) -> impl Stream<Item = Result<Update>> + Send + use<>

Like Self::updates, but resumable: on a retriable stream error it reconnects from the last offset it observed (rather than restarting from begin_offset or losing position), with a short backoff and a bounded number of consecutive reconnects (see the client’s RetryConfig).

Observed includes the participant’s OffsetCheckpoint frames, which are filtered out of what this yields but are the only thing that advances the resume point on a stream where nothing is happening. Once the reconnect budget is spent the stream yields the failure that caused it — the participant’s status, details and retriable classification intact — rather than an error of the SDK’s own.

A resume point the participant has since pruned is not retried: the stream yields the refusal, and Error::pruned_earliest_offset names where readable data begins. Moving forward to it loses the pruned history, so that is the caller’s call, never the stream’s.

Example

use tokio_stream::StreamExt as _;

let stream = client.updates_resumable(vec![party], 0);
tokio::pin!(stream);
while let Some(update) = stream.next().await {
    println!("update: {:?}", update?);
}

pub fn updates_resumable_typed_with( &self, request: UpdatesRequest, ) -> impl Stream<Item = Result<Update>> + Send + use<>

Like Self::updates_resumable_with, as the SDK’s own Update.

pub fn updates_resumable_with( &self, request: UpdatesRequest, ) -> impl Stream<Item = Result<Update>> + Send + use<>

Like Self::updates_resumable, with the full request surface of an UpdatesRequest. A bounded request (until) makes this a resilient catch-up read: reconnects resume from the last observed offset, and the stream ends once the participant closes it at the end offset.

Trait Implementations

impl Clone for CantonClient

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for CantonClient

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.