canton_ledger/
lib.rs

1//! Async Canton Ledger API client (gRPC + JSON).
2//!
3//! [`CantonClient`] speaks the gRPC Ledger API v2: command submission
4//! (fire-and-forget [`CantonClient::submit`] and
5//! [`CantonClient::submit_and_wait_for_transaction`]) with change-ID
6//! de-duplication and completion-based recovery, ACS + update streaming
7//! (paging, reverse-order, event query, and offset-**resumable** streams), a
8//! node health check, and an opt-in retry pipeline. [`JsonClient`] mirrors the
9//! core surface over the HTTP JSON Ledger API (submit + bounded reads, plus
10//! WebSocket streaming behind the `ws` feature). Both share the
11//! [`canton_core`] connection kernel (endpoint, [`Auth`],
12//! TLS, retry) and error model.
13//!
14//! ```no_run
15//! # async fn run() -> canton_ledger::Result<()> {
16//! use canton_ledger::{CantonClient, Config};
17//!
18//! let client = CantonClient::connect_lazy(Config::new("http://localhost:3901"))?;
19//! println!("ledger api version: {}", client.version().await?);
20//! # Ok(())
21//! # }
22//! ```
23// `doc(cfg)` marks the `ws`-gated items on docs.rs, and that attribute is
24// nightly-only. docs.rs builds with `--cfg docsrs`, so without this the
25// attributes below are a hard error there and the crate documents as failed —
26// while a plain `cargo doc`, which never sets `docsrs`, stays green.
27#![cfg_attr(docsrs, feature(doc_cfg))]
28
29mod client;
30mod command;
31mod json;
32pub mod request;
33mod submission;
34#[cfg(feature = "ws")]
35mod ws;
36
37pub use canton_core::{
38    Auth, Config, Error, ErrorCategory, ErrorInfo, ResourceInfo, Result, RetryConfig, TlsConfig,
39};
40pub use canton_proto::grpc::health::v1::health_check_response::ServingStatus;
41pub use client::{AcsEntry, CantonClient};
42pub use command::{ChangeId, Submit, create, exercise, identifier, record, value};
43pub use json::{
44    JsonClient, JsonCommands, JsonSubmitAndWaitResponse, JsonSubmitResponse, JsonTransaction,
45};
46pub use request::{ActiveContractsRequest, CompletionsRequest, TransactionShape, UpdatesRequest};
47pub use submission::{JsonSubmission, Submission};
48
49/// The generated Ledger API v2 protobuf types, for the **dynamic** (untyped)
50/// command path. For typed payloads generated from a DAR, see `canton-codegen`
51/// and the `canton-daml` runtime.
52///
53/// **Stability:** these wire types are *protocol-stable*, not SemVer-stable —
54/// they track the vendored protos pinned to a Canton release and are exempt
55/// from this crate's SemVer guarantees (see the `canton-proto` stability
56/// policy). The hand-written SDK surface carries the SemVer promise.
57pub use canton_proto::com::daml::ledger::api::v2 as proto;
canton_ledger/lib.rs

canton_ledger/
lib.rs
