Canton Network docsLanguage Bindings
Ledger Client Standard
Updated 12-11-2026
This page captures the Ledger Client Standard functionality that should be provided by fully conformant library implementations. It is written for developers who build Canton ledger client libraries.
The Functionality Requirement column marks each capability as one of the following:
This standard reflects Canton 3.5.
- Required marks capabilities expected today.
- Upcoming marks capabilities expected for upcoming iterations once the Ledger API provides the underlying functionality.
Codegen and bindings
Code generation and bindings convert Daml types into native types in the target language and connect them to Ledger API JSON and gRPC requests and to PQS.| Domain | Additional info | Functionality Requirement |
|---|---|---|
| Daml representation | Implementation contains a code-generating tool that is able to convert Daml types into the native representation in the target language. It must support - all serializable Daml types - interfaces - contract keys - dependencies | Required |
| JSON Codec | The tool extends the code-generated objects in the native language with methods to serialize and deserialize to JSON format required in the Ledger API JSON requests and responses | Required |
| gRPC Codec | The tool extends the code-generated objects in the native language with methods to serialize and deserialize to proto format required in the Ledger API gRPC requests and responses | Required |
| JSON Bindings | The library provides utility wrappers in the host languages that facilitate construction and bridge the interaction between the classes generated from Ledger API OpenAPI definitions and the classes code-generated from Daml | Required |
| gRPC Bindings | The library provides utility wrappers in the host languages that facilitate construction and bridge the interaction between the classes generated from Ledger API proto definitions and the classes code-generated from Daml | Required |
| PQS bindings | The library provides mechanisms that bridge the interaction between the table functions in PQS and the classes code-generated from Daml | Required |
Basic infrastructure
Basic infrastructure covers the connection security, authorization, error handling, observability, retry, signing, and health-monitoring services that a library provides for every Ledger API call.| Domain | Additional info | Functionality Requirement |
|---|---|---|
| TLS | The library utilizes secure HTTP and gRPC connections using TLS. It supports mutual and server-side TLS. | Required |
| Authorization | The library supports client credential workflow to obtain and refresh OAuth tokens. It has the capability to inject the JWT tokens into the call context | Required |
| Error parsing and handling | The library has the ability to parse and process all types of errors returned by Ledger API. It supports - classification of errors into retriable and non-retriable - JSON and gRPC errors - extraction of the error code, message, request info, error info and other structured details such as contract ids, packages, party names etc. | Required |
| Tracing | The library handles tracing according to the OpenTelemetry standard and OTLP servers. It supports - creation and injection of trace ids into the headers of the requests - extraction of trace ids from the response - support JSON and gRPC requests - report the spans to the OpenTelemetry compatible OTLP server | Required |
| Retry logic | The library handles seamlessly the retry logic for Ledger API calls. It supports - retries on retriable errors only - timeouts - maximum number of retries | Required |
| Logging | The library is able to log using a standard library adequate for the host language. It supports - logging requests and responses - utilizes trace-ids - verbose logging of Ledger API errors - configurable log level sensitivity - configurable log destination - configurable log format | Required |
| Metrics | The library handles metrics according to OpenTelemetry standard It supports - sending metrics to the OTLP server - reporting vitals of the communication: number of requests and responses - breakdown by error and success - breakdown by endpoint | Required |
| Signing | The library supports signing algorithms that are needed in the externally signed Ledger API endpoints. It supports - KMS systems - keys provided in a file - all algorithms supported by Canton | Required |
| Node Health | The library supports monitoring node’s health letting the client applications respond to the intermittent and permanent failure situations. | Required |
Commands
Command capabilities cover constructing and submitting Daml commands over the Ledger API, including internal and externally signed submission, deduplication, explicit disclosure, recovery, and batching.| Domain | Additional info | Functionality Requirement |
|---|---|---|
| JSON | The library facilitates construction and submission of Daml commands over the Ledger API JSON endpoint. It supports - create commands - exercise commands | Required |
| gRPC | The library facilitates construction and submission of Daml commands over the Ledger API gRPC endpoint. It supports - create commands - exercise commands | Required |
| Internal commands | The library uses the internal command submission endpoints. It supports - submit method - submitAndWait in all its forms | Required |
| External commands | The library uses externally signed command submission endpoints It supports - prepare method - execute method - executeAndWait in all its forms | Required |
| Deduplication | The library contains logic that allows client applications to send commands in a reliable fashion utilizing the built-in deduplicating provisions of the Ledger API. It supports - error handling - retries | Required |
| Command recovery | The library is capable of recovering pending command state after the crash utilizing command completion endpoint. It supports - recovery from participant crash - recovery from client crash - recovery from lost connection - recovery from a timeout | Required |
| Batching | The library is capable of creating batched Ledger API commands. For externally signed (interactive) submission, batches are currently limited to a single root command/node. | Required |
| Contract keys | The library uses Ledger API command submission provisions for contract keys. It supports - exercising choices by contract keys - prefetching of contract keys for accelerated execution | Required |
| Explicit disclosure | The library uses explicit disclosure to augment the submitted commands with additional contracts that the submitting party is not privy to. | Required |
| Pending set | The library keeps track of the contracts that are being operated on in a pending data set. It supports - keeping track of consuming exercises - keeping track of creates - keeping track of non-consuming exercises | Required |
| Package selection | The library allows selecting a particular package version preference for command submission in the package_id_selection_preference field. | Required |
| HA | The library supports command deduplication across multiple participants that host the same submitting parties. | Upcoming |
Streams
Stream capabilities cover querying and subscribing to the Active Contract Set (ACS) and update streams, and recovering those streams after an interruption.| Domain | Additional info | Functionality Requirement |
|---|---|---|
| JSON | The library facilitates query construction and subscription to ACS and Update streams over the Ledger API JSON endpoint. | Required |
| gRPC | The library facilitates query construction and subscription to ACS and Update streams over the Ledger API gRPC endpoint. | Required |
| ACS streaming | The library uses streaming endpoints to retrieve the ACS for given parties and templates. It utilizes streaming endpoints in gRPC and websocket endpoints in JSON. | Required |
| ACS paging | The library uses paging endpoints to retrieve the ACS for given parties and templates. It utilizes paging in gRPC and JSON. | Required |
| Updates streaming | The library uses streaming endpoints to retrieve the updates for given parties and templates. It utilizes streaming endpoints in gRPC and websocket endpoints in JSON. | Required |
| Updates paging | The library uses paging endpoints to retrieve the updates for given parties and templates. It utilizes paging in gRPC and JSON. | Required |
| Reverse order | The library can serve data in reverse order utilizing appropriate Ledger API provisions. | Required |
| Interfaces | The library subscribes to and processes interface views | Required |
| Topology events | The library subscribes to and processes topology events | Required |
| In memory ACS | The library contains a component that keeps an in-memory copy of the Active Contract Set. It supports - parameterization by set of parties and templates - filters to limit the ACS to contracts with specific attributes - initiates from an ACS query and keeps current view by subscribing to update stream - interface views | Required |
| Resilient streams | The library can recover a stream after an interrupt from the last known location. It supports - recovery from the last offset - recovery from the last record time vector - recovery from the continuation token | Required |
| HA | The library can recover a stream transmission after a switch-over to a secondary participant. It supports - record time vectors - paging restarts | Upcoming |
Parties
Party capabilities cover listing, creating, and modifying local, external, and decentralized parties through the Ledger API party management endpoints.| Domain | Additional info | Functionality Requirement |
|---|---|---|
| JSON | The library utilizes party management functionality of the Ledger API using JSON endpoints. | Required |
| gRPC | The library utilizes party management functionality of the Ledger API using gRPC endpoints. | Required |
| List parties | The library supports listing parties on the node using various filtering criteria. | Required |
| Local parties creation | The library can create parties local to the participant node. It takes advantage of self administration mode where party is automatically assigned to the requesting user. | Required |
| External parties creation | The library can create external parties. It supports - generate method - signing - allocate method - self administration mode | Required |
| Local parties modification | The library can change aspects of the party topology definition. In particular it supports - changing mapping of parties to participants - changing participant permission levels | Required |
| External parties modification | The library can change aspects of the party topology definition. In particular it supports - changing mapping of parties to participants - changing participant permission levels - changing keys responsible for transaction signing - change the signature threshold | Required |
| Decentralized party creation | The library can manage decentralized parties. In particular it supports - create a decentralized namespace - modify a decentralized namespace - changing participant permission levels - changing keys responsible for transaction signing - change the signature threshold | Required |
Packages
Package capabilities cover uploading, validating, vetting, listing, and describing DAR packages, and selecting preferred packages for command submission.| Domain | Additional info | Functionality Requirement |
|---|---|---|
| JSON | The library utilizes package management functionality of the Ledger API using JSON endpoints. | Required |
| gRPC | The library utilizes package management functionality of the Ledger API using gRPC endpoints. | Required |
| Upload | The library facilitates the upload of the DAR packages to the participant using the Ledger API endpoints | Required |
| Validation | The library facilitates the validation of the DAR packages to the participant using the Ledger API endpoints | Required |
| Vetting | The library facilitates vetting of the required packages on the target participants and synchronizers. It is capable of computing the required vetting action from the current vetting state and the desired outcome. | Required |
| Listing | The library facilitates listing the packages on the participant using various criteria such as package names, ids, participants and synchronizers | Required |
| Package preference | Library facilitates the selection of the preferred packages for a command submission. It makes sure the preference conforms with the existing vetting state. | Required |
| Description | The library uses the Daml description service to request the descriptors of the Daml package and types from the participants | Required |
Topology
Topology capabilities cover listing, constructing, signing, and submitting topology mappings such as namespace delegations, party-to-participant mappings, and vetted packages.| Domain | Additional info | Functionality Requirement |
|---|---|---|
| List mappings | The library enables the retrieval and inspection of current topology mappings. Users can apply precise list parameters to restrict search results based on specific mapping types or attributes. | Required |
| Mapping presentation | The library supports rendering of the topology mapping in a format idiomatic to the target programming language. | Required |
| Mapping construction | The library facilitates creation of new topology mappings by abstracting the underlying complexity of calculating state modifications relative to prior values. | Required |
| Mapping signing | The library supports signing of topology transactions. | Required |
| Mapping submission | The library facilitates submission of the signed topology transactions. It supports synchronous and asynchronous semantics. | Required |
| Namespace delegations | The library supports managing namespace delegations of all shapes | Required |
| Decentralized namespaces | The library supports managing decentralized namespace delegations of all shapes | Required |
| Owner to key mapping | The library supports managing owner to key mappings of all shapes | Required |
| Party to participant | The library supports managing party to participant mappings of all shapes | Required |
| Party to key mapping | The library supports managing party to key mappings of all shapes | Required |
| Vetted packages | The library supports managing vetted package mappings of all shapes | Required |
Admin API and Ledger API support
Topology functionality is available today through the Admin API, with Ledger API support expected in an upcoming iteration.| Domain | Additional info | Functionality Requirement |
|---|---|---|
| Admin API | The library supports topology functionality exposed through the Admin API | Required |
| Ledger API | The library supports topology functionality exposed through the Ledger API | Upcoming |
User
User capabilities let users inspect their own user record and administer the parties attached to their account.| Domain | Additional info | Functionality Requirement |
|---|---|---|
| Self-inspect | The library allows the users to pull own record to check permissions and other settings. | Required |
| Self-admin | The library allows the users to add and modify the parties attached to the user account. | Required |
Traffic
Traffic capabilities cover estimating transaction traffic costs and listing, inspecting, selecting, and topping up the traffic accounts debited during command submission.| Domain | Additional info | Functionality Requirement |
|---|---|---|
| Traffic computation | The library processes the traffic cost estimations produced by the prepare transactions. It facilitates setting limits on transaction cost. It can convert the traffic cost expressed in the synchronizer units to local units of the validator | Required |
| Traffic account listing and inspecting | The library supports listing traffic accounts available to the user and inspecting the account balance | Required |
| Traffic account selection | The library facilitates selecting a traffic account to be debited during the command submission | Upcoming |
| Traffic top-up | The library facilitates the top up operation replenishing the traffic accounts with fresh credits | Required |
Multi-synchronizer
Multi-synchronizer capabilities extend party, package, command, and stream handling to participants connected to more than one synchronizer.| Domain | Additional info | Functionality Requirement |
|---|---|---|
| Listing | The library lists connected synchronizers for the participant in general and for a party in particular | Required |
| Parties | The library allows managing party allocations and changing topology configurations across multiple synchronizers. | Required |
| Packages | The library allows users to maintain package vetting where the set of package versions vetted on each synchronizer is separately tailored for the needs of the application workflows. | Required |
| Commands | The library allows the clients to select the target synchronizer. It keeps track of it during command retries and in the completion processing. | Required |
| Streams | The library keeps track of the current synchronizer of the contract. It handles the out of order assign and unassign events putting them back in order distilling the most up to date contract state. | Required |
Token Standard
Token Standard capabilities cover transfers, pre-approvals, allocations, and instrument inspection for templates and interfaces written to Token Standard V1 and V2.| Domain | Additional info | Functionality Requirement |
|---|---|---|
| One step transfers | The library supports workflows with one step transfers | Required |
| Pre-approvals | The library supports pre-approvals | Required |
| Allocate | The library supports trade allocations | Required |
| Transfer | The library supports asset transfers | Required |
| Instrument inspection | The library supports instrument inspection | Required |
| V1 | The library supports interactions with interfaces and templates written according to Token Standard V1 | Required |
| V2 | The library supports interactions with interfaces and templates written according to Token Standard V2 | Required |
Documentation
Documentation requirements define the user manual, tutorials, examples, and reference material that a conformant library ships with.| Domain | Additional info | Functionality Requirement |
|---|---|---|
| User manual | The library is shipped with the comprehensive user manual that covers all functionality offered by the library. It must explain how to use each capability in this standard in the library’s language. | Required |
| Tutorials | The library is shipped with tutorials that demonstrate key interactions: - building applications - configuration - connecting to ledger - creating and managing users, parties - uploading and vetting packages - submitting commands using internal and external signing - maintaining ACS - interacting with PQS - managing traffic credits | Required |
| Examples | The library is shipped with example application(s) that showcases the capabilities and can be used as a blueprint for developers | Required |
| Reference | The library is shipped with a complete reference material where each class, method and function is explained. | Required |