canton-ledger-api

---
name: canton-ledger-api
description: The gRPC Ledger API — the primary interface to a validant's participant node. Covers command submission (CommandService submit-and-wait, CommandSubmissionService async submit), the update/transaction stream (UpdateService), state queries (StateService active-contracts, ledger-end), party/user/package admin services, interactive submission (prepare/execute) for external parties, TLS + JWT auth, and that types are addressed by (entity, module, package-hash). Use for high-throughput backends.
license: Apache-2.0
---

# Canton Ledger API (gRPC)

## Overview
The **Ledger API** is the primary interface for submitting commands and reading transactions, exposed by a validator's **participant node** over **gRPC** (and mirrored by the JSON API, which translates to it). It's the high-throughput choice for production backends because it avoids JSON serialization overhead.

## What it provides
| Capability | Service(s) |
| --- | --- |
| **Command submission** | `CommandService` (submit-and-wait variants), `CommandSubmissionService` (async submit) |
| **Update / transaction stream** | `UpdateService` (`GetUpdates`, by-offset/by-id) |
| **Active Contract Set / state** | `StateService` (`GetActiveContracts`, `GetLedgerEnd`, connected synchronizers) |
| **Command completions** | `CommandCompletionService` (`CompletionStream`) |
| **Events** | `EventQueryService` (events by contract id) |
| **Interactive submission** | `InteractiveSubmissionService` (`prepare`/`execute`) — for external parties |
| **Admin** | `PartyManagementService`, `UserManagementService`, `PackageManagementService`, `IdentityProviderConfigService`, `ParticipantPruningService` |

## Submitting commands
You act **as a party** hosted on the participant. Commands are `CreateCommand`, `ExerciseCommand`, `CreateAndExerciseCommand`, `ExerciseByKeyCommand`.
- **`CommandService.SubmitAndWait*`** — submit and block until commit; returns the transaction/update. Simplest for request/response backends.
- **`CommandSubmissionService.Submit`** — fire-and-forget; track outcomes via the **completion** stream. Higher throughput.

Use a stable **command ID** per logical command for **deduplication** (see `appdev/deep-dives/command-deduplication.mdx`). Commands carry `actAs`/`readAs` party sets and a `userId`.

## Reading state
- **Transaction/update stream** (`UpdateService.GetUpdates`) — subscribe from an **offset** to receive committed transactions for your parties; drive your read model from it.
- **ACS** (`StateService.GetActiveContracts`) — snapshot of active contracts at an offset; bootstrap then follow the stream. Get the current offset from `GetLedgerEnd`.
- Filters use party + **template/interface** filters (e.g. an `InterfaceFilter` with `includeInterfaceView`/`includeCreatedEventBlob`) — the same filter shapes the JSON API uses.

## Type identifiers
Over the Ledger API every type is addressed by the triple **`(entity name, module name, package hash)`** (e.g. `<hash>:Main:Asset`). Your client must know the package hashes it targets — generate bindings from the DAR so this is type-safe (see `canton-language-bindings`).

## External parties: prepare / execute
For **external parties** (keys held off-validator), you don't submit directly. You **`prepare`** a submission on the participant, sign the resulting hash with the party's key, then **`execute`** it. See `canton-external-signing`.

## Auth & transport
Production uses **TLS + JWT** bearer tokens (scopes like `daml_ledger_api`); on LocalNet auth can run through Keycloak or be disabled for fast iteration. The Admin API (gRPC) handles node administration, party allocation, and DAR upload.

## Source docs
- [`sdks-tools/api-reference/ledger-api.mdx`](../canton-docs/sdks-tools/api-reference/ledger-api.mdx), [`ledger-api-services.mdx`](../canton-docs/sdks-tools/api-reference/ledger-api-services.mdx)
- [`appdev/modules/m4-sdks-apis.mdx`](../canton-docs/appdev/modules/m4-sdks-apis.mdx), [`m4-backend-dev.mdx`](../canton-docs/appdev/modules/m4-backend-dev.mdx)
- [`appdev/deep-dives/command-deduplication.mdx`](../canton-docs/appdev/deep-dives/command-deduplication.mdx), [`values-in-the-ledger-api.mdx`](../canton-docs/appdev/deep-dives/values-in-the-ledger-api.mdx)
- Related skills: `canton-json-api`, `canton-language-bindings`, `canton-external-signing`, `canton-app-architecture`.

## AI Agent Prompt
> "Implement a backend against the gRPC Ledger API: submit creates/exercises via `CommandService.SubmitAndWait` (with a dedup command ID), bootstrap state from `StateService.GetActiveContracts` at the current ledger-end, then follow `UpdateService.GetUpdates` to maintain a read model. Address templates by their (entity, module, package-hash) triple and authenticate with a JWT."