Capability standard for Canton Ledger Client Libraries, including existing and upcoming functionality.
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.
This standard reflects Canton 3.5.
The Functionality Requirement column marks each capability as one of the following:
Required marks capabilities expected today.
Upcoming marks capabilities expected for upcoming iterations once the Ledger API provides the underlying functionality.
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
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.
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.
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
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
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
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
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
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.
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
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.
