canton-admin 0.3.2

# Canton Rust SDK

A production-grade, async **Rust SDK for the [Canton Network](https://www.canton.network/)** Ledger API — the Rust member of Canton's language-binding set, funded by Canton dev-fund proposal [#407](https://github.com/canton-foundation/canton-dev-fund/pull/407). Apache-2.0.

Built on `tonic`/`prost`/`tokio`. Talks the **Ledger API v2** over gRPC (primary) and JSON (HTTP + WebSocket), with correct change-ID de-duplication, command recovery, resilient/resumable streaming, TLS/mTLS on every transport, JWT/OIDC auth, and built-in telemetry.

> **Status:** 0.3.2 is on crates.io: the Ledger API client, the type-safe DAR codegen, the token standard in both versions (CIP-56 and CIP-0112), interactive submission with a pluggable `Signer`, and a typed PQS client. Everything here is verified against a Canton **3.5.7** participant — hermetic tests plus the live suites (submit, streaming, recovery, TLS/mTLS, auth, external signing, PQS against **Scribe 3.5.4**), an end-to-end typed loop over gRPC and JSON, and the five token-standard examples against a live registry — and the token-standard examples were also run on the Canton Network DevNet (Canton 3.5.17 and 3.6.3), with the output on record under [`docs/verification/`](docs/verification/token-standard-live-runs.md). CI holds the whole workspace to `-D warnings` on every feature combination.

## Crates

| Crate | What it is |
|---|---|
| `canton` | The SDK entry point: a thin facade re-exporting the whole family (`canton::ledger`, `canton::auth`, `canton::admin`, `canton::daml`, `canton::signer`, `canton::token`, `canton::pqs` + the shared `Config`/`Error` at the root) with the `ws`/`otel`/`pqs-tls` features forwarded. `cargo add canton` gets everything below as one version-locked set. |
| `canton-core` | Shared foundation: the `Error`/`Result` model (retriable classification, structured `ErrorInfo` details), the connection kernel (`Config`, `Auth`/`TokenSource`, `TlsConfig`, jittered retry with per-attempt timeouts), and telemetry (`tracing` spans + `metrics`, optional OTLP via `otel`). |
| `canton-proto` | Generated gRPC types + client stubs from vendored protos (Ledger API v2, Canton admin API topology read, gRPC health), pinned to a Canton release. Internal. |
| `canton-auth` | JWT/OIDC authentication: client-credentials `TokenProvider` with caching + refresh + bounded fetch, and Keycloak/Auth0/Okta presets that each produce their provider's normal token request (Auth0's `audience`, Okta's HTTP Basic credentials). |
| `canton-ledger` | The async Ledger API client, with the **same operations on both transports**. gRPC: `submit` / `submitAndWait` / `submitAndWaitForTransaction`, completions and change-ID recovery, ACS/update streaming (+ paging, reverse-order, event query, checkpoint-resumable), a lossless ACS read (`AcsEntry`, incomplete reassignments included), request builders (bounded/filtered/shaped streams, completion `user_id`), node health. JSON: the same submission set including fire-and-forget and recovery, event query, bounded reads, package and party management (`/v2/packages`, `/v2/parties`) for JSON-only deployments, and WebSocket streaming — updates, completions and a resumable ACS — behind the `ws` feature. |
| `canton-admin` | Admin surface: party allocation/management, user self-inspect, packages read, and topology read (party→participant mappings, namespace delegations, vetted packages) over the Canton admin API. |
| `canton-pqs` | Typed read client for the Participant Query Store (PQS/Scribe): typed predicates compiled to parameterized JSONB queries — no hand-written SQL on that path, and no interpolation of values or field paths anywhere. `Sql::raw` is the documented escape hatch for PQS functions the crate does not model; it still binds its parameters. |
| `canton-token` | Token-standard workflows: the registry's off-ledger API, choice contexts with their disclosed contracts, transfers and allocations. CIP-56 at the root, CIP-0112 under `v2` — same function names, so the path says which standard you meant. Workflow only — the types are generated, not re-declared. |
| `canton-signer` | Pluggable transaction signing for interactive submission: an object-safe async `Signer` trait (HSM/KMS-compatible) plus an in-memory Ed25519 key behind a feature flag. |
| `canton-daml` | The runtime under generated bindings: Daml primitive types (`Party`, `ContractId<T>`, `Numeric`, `Timestamp`, …), `Template`/`Interface`/`Choice` traits, command builders, and the JSON + gRPC value codecs. |
| `canton-codegen` / `canton-codegen-cli` | DAR → typed Rust. The CLI (`dpm-codegen-rust`, also `dpm codegen-rust`) writes a complete crate from any DAR; the library is the IR + emitter behind it. |
| `canton-lf` | Daml-LF archive reader/decoder (the codegen front-end), built on the official `daml-lf-archive` schema and held to the official JVM reader by a conformance oracle. Internal. |
| `canton-splice-amulet`, `canton-splice-wallet`, `canton-splice-wallet-payments` | Pre-built typed bindings for the Splice protocol DARs, regenerated per release ("DAR as a crate"). |
| `canton-splice-api-token-*` (V1 and V2), `canton-splice-api-featured-app-v1` | The token-standard and featured-app packages, one crate each — CIP-56 (`-v1`) and CIP-0112 (`-v2`). The crates above reference these rather than copying them, so a `Holding` is the same Rust type whichever crate you reach it through. |
| `canton-daml-stdlib` | The Daml standard library (`daml-stdlib`, `daml-prim`, `ghc-stdlib`), which every DAR carries and no DAR ships. Every bindings crate references it, so a `RelTime` is one type rather than one per crate. |
| `canton-conformance` | The Ledger Client Standard, one test per capability, with a guard asserting the suite and the published capability list agree in both directions. **Not published.** |
| `canton-quickstart-licensing` | The same, for the cn-quickstart licensing DAR. **Not published** — it backs the reference app and the end-to-end tests; generate your own with the CLI. |

## Compatibility

The full picture — toolchain, platform, Canton, Daml-LF, token-standard version,
and what CI can and cannot check — is in
[docs/compatibility-matrix.md](docs/compatibility-matrix.md).

| SDK version | Canton version | Ledger API | Rust (MSRV) |
|---|---|---|---|
| 0.3.x (current release) | 3.5.7 (pinned protos); token examples also run on 3.5.17 (DevNet) | v2 | 1.88 |
| 0.2.x | 3.5.7 (pinned protos) | v2 | 1.88 |
| 0.1.x | 3.5.7 (pinned protos) | v2 | 1.88 |

The vendored `.proto` files are pinned to the Canton release above; moving the
supported Canton range re-vendors them in a new SDK minor (see the stability
policy in [`canton-proto`](crates/canton-proto/src/lib.rs) and
[ADR-0002](docs/adr/0002-proto-types-are-protocol-stable.md)). All `canton-*`
crates release in **lockstep** — mix only equal versions
([ADR-0005](docs/adr/0005-lockstep-versioning.md)).

## Feature flags

| Feature | Crate | What it adds |
|---|---|---|
| `ws` | `canton-ledger` | WebSocket streaming for the JSON transport (`ws_updates`, `ws_active_contracts`, `ws_completions`, `ws_updates_resumable`), TLS-aware. |
| `otel` | `canton-core`, `canton-ledger` | OTLP span export (`telemetry::otel::otlp_tracer`) and automatic W3C trace-context injection into outgoing gRPC metadata + JSON headers. |
| `ed25519` | `canton-signer` | The in-memory Ed25519 key (`Ed25519Key`), on `ring`. **On by default via the facade.** An HSM/KMS deployment that must not link `ring` or an in-memory private key takes `canton = { default-features = false }` and implements `Signer` itself; the trait, the wire types and their validation are unconditional. |
| `tls` | `canton-pqs` | Connecting to a PQS store over TLS (`PqsClient::connect_tls`), with the platform's root certificates. |

The `canton` facade forwards all of them — the PQS one as `pqs-tls`, since the facade's own namespace has to say which crate a `tls` belongs to: `canton = { version = "0.3", features = ["ws", "otel", "pqs-tls"] }`. `ed25519` is on by default, so turning it off is `default-features = false`.

Telemetry follows the standard Rust model: the SDK **emits** (`tracing` spans, `metrics` counters labelled by method + transport); the application installs the subscriber/recorder of its choice.

## Quickstart

```sh
cargo add canton            # the whole SDK, one crate
# or pick pieces: cargo add canton-ledger canton-auth
```

```rust,ignore
use canton::ledger::{CantonClient, Config};

#[tokio::main]
async fn main() -> canton::Result<()> {
    let client = CantonClient::connect_lazy(Config::new("http://localhost:3901"))?;
    println!("ledger api version: {}", client.version().await?);
    println!("node health:        {:?}", client.health_check().await?);
    Ok(())
}
```

With OIDC auth and a command:

```rust,ignore
use canton::auth::{OidcConfig, TokenProvider};
use canton::ledger::{CantonClient, Config, Submit, create, identifier, record, value};

async fn submit(party: &str, pkg: &str) -> canton::Result<()> {
    let auth = TokenProvider::new(OidcConfig::keycloak(
        "http://keycloak.localhost:8082", "AppProvider", "client-id", "client-secret",
    ));
    let client = CantonClient::connect_lazy(
        Config::new("http://localhost:3901").with_oidc(auth),
    )?;

    let tx = client
        .submit_and_wait_for_transaction(
            Submit::new(party).add_command(create(
                identifier(pkg, "Licensing.AppInstall", "AppInstallRequest"),
                record(vec![
                    ("provider", value::party(party)),
                    ("user", value::party(party)),
                    ("meta", value::record(record(vec![("values", value::empty_text_map())]))),
                ]),
            )),
        )
        .await?;
    println!("committed {} at offset {}", tx.update_id, tx.offset);
    Ok(())
}
```

Runnable examples: [`version_and_health`](crates/canton-ledger/examples/version_and_health.rs) (no auth, defaults to `http://localhost:3901`) and [`submit_and_read`](crates/canton-ledger/examples/submit_and_read.rs) (OIDC auth + a create). Both read the same `CANTON_TEST_*` variables as the live tests below, so one export set runs everything:

```sh
cargo run -p canton-ledger --example version_and_health
cargo run -p canton-ledger --example submit_and_read
```

**When the outcome must not be lost.** A submission whose response never
arrives may still have committed, and the way back to it is the command's
identity — so take the identity *before* sending rather than from a call that
may fail:

```rust,ignore
use std::time::Duration;

// An offset from before the submission, to read completions from.
let offset = client.ledger_end().await?;
let submission = client.submission(Submit::new(party).add_command(command));

if submission.submit_and_wait().await.is_err() {
    // Ambiguous — ask the ledger what actually happened. The match is on the
    // whole change ID (user, acting parties, command id), not the command id
    // alone, which is not unique across a participant's users.
    let completion = submission.recover(offset, Duration::from_secs(30)).await?;
    println!("committed after all: {}", completion.update_id);
}
```

`JsonClient::submission` is the same handle on the JSON transport, recovering
over the WebSocket.

See also the integration tests in [`crates/canton-ledger/tests/`](crates/canton-ledger/tests/) and [`crates/canton-admin/tests/`](crates/canton-admin/tests/).

## A local network, with no configuration in your program

[canton-devkit](https://github.com/bitdynamics-ab/canton-devkit) runs a Splice
LocalNet — two participants and a super-validator — and exports it into the
environment. The SDK reads that export directly, so nothing in the program names
a host, a port, or a credential:

```sh
canton-devkit localnet up demo            # or: dpm localnet up demo
eval "$(canton-devkit localnet env demo)"
```

```rust,ignore
use canton::ledger::{CantonClient, JsonClient};
use canton::{Config, localnet};

let grpc = CantonClient::connect_lazy(Config::from_env()?)?;   // app-provider
let json = JsonClient::from_env()?;                            // same network
let user = Config::from_env_for("app-user")?;                  // the other participant
let party = localnet::party("app-provider");                   // the id for `act_as`
```

Runnable: [`localnet`](crates/canton-ledger/examples/localnet.rs).

```sh
cargo run -p canton-ledger --example localnet
```

Two details this handles for you, both of which otherwise fail late and
unhelpfully. The exported gRPC URL has **no scheme** (`host:port` is what a gRPC
client dials) — passed to a client unchanged it produced an unexplained
transport error at the first RPC. And the URLs are nginx **virtual-host names**
(`grpc-ledger-api.app-provider.demo.localhost`), so the name has to reach the
`:authority` / `Host` header rather than be resolved away; substituting
`127.0.0.1` reaches the port and is refused by the vhost. `*.localhost` resolves
to loopback on macOS and on Linux with systemd-resolved — elsewhere, add an
`/etc/hosts` entry.

Nothing here is devkit-specific beyond the variable names, and `CANTON_ENDPOINT`
/ `CANTON_TOKEN` override them for an environment that is not a LocalNet. The
full contract is in [`canton_core::localnet`](crates/canton-core/src/localnet.rs).

Verified against a live Canton 3.5.7 participant reached through those exported
shapes — scheme-less gRPC URL, vhost hostnames, ready-made bearer token — on
both transports. What that does *not* yet cover is a `localnet up` of our own:
the contract is read and exercised, the orchestration around it is the devkit
project's to vouch for.

## Typed bindings from your DAR (codegen)

Turn any DAR into a typed crate — templates become structs, choices become
typed exercise impls, with JSON and gRPC codecs on everything:

```sh
cargo install canton-codegen-cli          # provides `dpm-codegen-rust`
dpm-codegen-rust --dar path/to/my-app-0.1.0.dar --out my-app-bindings
```

The output is a self-contained crate (`Cargo.toml` + `src/lib.rs`). **Commit it**
and depend on it by path — that is how the `canton-splice-*` crates in this
repository are built, and it keeps the generated code reviewable in a diff:

```toml
my-app-bindings = { path = "my-app-bindings" }
```

To keep it in step with the DAR, regenerate in CI and fail on a diff, rather
than generating during the build:

```sh
dpm-codegen-rust --dar dars/my-app-0.1.0.dar --out my-app-bindings
git diff --exit-code my-app-bindings
```

No `--force` is needed to regenerate over the tool's own output; it is there to
overwrite files this tool did **not** write, which is a thing to do on purpose
and not a flag to carry around.

Generating from a **build script** does not work, and it is worth saying why
rather than leaving it to be discovered: Cargo resolves path dependencies before
it runs build scripts, so on a clean checkout `my-app-bindings` does not exist
yet and the build fails before the script that would create it has run. The
`prost-build` arrangement — write into `OUT_DIR`, `include!` it — does not apply
either: the emitted tree spans several packages and refers between them by
`crate::`-qualified paths, which resolve to the *including* crate's root rather
than the module they were placed in.

`canton_codegen::generate` is a library call for exactly the CI step above, and
for tooling that produces a crate directory.

Then submit typed commands:

```rust,ignore
use my_app_bindings::my_app::My_Module::{Asset, Asset_Transfer};
use canton_daml as rt;
use rt::Template as _;

let payload = Asset { owner: rt::Party::new(party), name: "gem".into() };
let create = rt::create_command(&payload);                       // gRPC command
let created: Asset = Asset::from_created_event(&event)?;         // typed read
let exercise = rt::exercise_command(&contract_id, &Asset_Transfer {
    new_owner: rt::Party::new(other),
});
```

Template ids use the upgrade-friendly `#package-name` form, so the participant
resolves the version vetted under Smart Contract Upgrade (the pinned package id
is also available as `Asset::PACKAGE_ID`). For the Splice DARs, skip codegen and
use the pre-built `canton-splice-*` crates. The full Daml-LF → Rust type mapping
is documented in [docs/daml-lf-type-mapping.md](docs/daml-lf-type-mapping.md);
regeneration on a DAR version bump in
[docs/scu-regeneration.md](docs/scu-regeneration.md). A complete runnable flow
(typed create → read back → exercise, on gRPC and JSON) is
[`crates/canton-sample`](crates/canton-sample/src/main.rs).

## Testing

**No-node tests** — unit tests, in-process gRPC/WebSocket mock servers, TLS
handshakes, wire-shape assertions. Nothing to install or configure:

```sh
cargo test --workspace --all-features
```

**Live integration tests** run against a real participant when the variables
below are set, and skip otherwise (so the command above stays green without a
node). Every name is prefixed `CANTON_TEST_`:

A skipped test and a passing one are the same line in cargo's output, so set
**`CANTON_TEST_REQUIRE_LIVE=1`** whenever a run is meant to prove something:
each test that would step aside for a missing variable fails instead. That is
what makes "38 live tests passed" a claim about a participant rather than about
an empty environment.

| Variable | What it gates | Example (LocalNet App Provider) |
|---|---|---|
| `CANTON_TEST_ENDPOINT` | all gRPC live tests | `http://localhost:3901` |
| `CANTON_TEST_JSON_ENDPOINT` | the JSON-transport and WebSocket tests | `http://localhost:3975` |
| `CANTON_TEST_TOKEN_URL` | authenticated tests (OIDC client-credentials) | `http://keycloak.localhost:8082/realms/AppProvider/protocol/openid-connect/token` |
| `CANTON_TEST_CLIENT_ID`, `CANTON_TEST_CLIENT_SECRET` | ditto | `app-provider-backend`, … |
| `CANTON_TEST_PARTY` | command submission and read-back | `app_provider_quickstart-…::1220…` |
| `CANTON_TEST_LICENSING_PKG` | ditto — the package the test commands instantiate | `#quickstart-licensing` |
| `CANTON_TEST_ADMIN_ENDPOINT` | `canton-admin` topology reads | `http://localhost:3902` |
| `CANTON_TEST_ADMIN_CLIENT_ID`, `CANTON_TEST_ADMIN_CLIENT_SECRET` | party-admin RPCs (need the `ParticipantAdmin` right) | `app-provider-validator`, … |
| `CANTON_TEST_SYNC_ID` | optional: also assert vetted packages in the synchronizer store | |
| `CANTON_TEST_REQUIRE_LIVE` | turns every skip into a failure — set it on any run whose result is being reported | `1` |

```sh
export CANTON_TEST_ENDPOINT=http://localhost:3901
export CANTON_TEST_JSON_ENDPOINT=http://localhost:3975
export CANTON_TEST_TOKEN_URL=http://keycloak.localhost:8082/realms/AppProvider/protocol/openid-connect/token
export CANTON_TEST_CLIENT_ID=app-provider-backend CANTON_TEST_CLIENT_SECRET=…
export CANTON_TEST_PARTY='app_provider_quickstart-…::1220…'
export CANTON_TEST_LICENSING_PKG='#quickstart-licensing'
export CANTON_TEST_REQUIRE_LIVE=1   # skipping is now a failure, not a pass
cargo test -p canton-ledger --all-features --test live -- --nocapture
```

**Credentials.** The suite takes whichever the environment offers: the OIDC
client-credentials flow where there is an issuer (`CANTON_TEST_TOKEN_URL` and
friends), otherwise a ready-made bearer token — which is what a Splice LocalNet
exports, having no issuer to exchange credentials with. Two tests genuinely need
an issuer (`ledger_end_with_oidc_auth`, and party management, which needs a
token carrying `ParticipantAdmin`); those say so when they step aside. The rest
run either way.

**Bringing up a node.** Any Canton 3.5 participant works; four paths, least
setup first:

- [canton-devkit](https://github.com/bitdynamics-ab/canton-devkit) — one binary:
  `canton-devkit localnet up demo`, then `eval "$(canton-devkit localnet env
  demo)"` exports endpoints, tokens and party ids under the names
  [`canton_core::localnet`](crates/canton-core/src/localnet.rs) reads, so the
  suite needs no `CANTON_TEST_*` at all. It allocates its own ports, so pass
  `--port-base` or read the exported values rather than assuming `3901`.
  Authentication is Splice's `unsafe-jwt-hmac-256`, so the two issuer-dependent
  tests skip; `localnet dar upload` supplies a package for the rest.
- [Canton Builder Tool](https://canton-network-devs.github.io/Canton-Builder-Tool/#part-builder)
  — the least to install: `canton builder start` brings up a LocalNet (its guide
  says about five minutes the first time, faster after), and
  `canton builder status` prints the port reference. Its App Provider
  participant is on `3901`/`3902`/`3975` like the others, and
  `canton builder deploy <dar>` uploads a DAR to both participants, which is how
  you get `CANTON_TEST_LICENSING_PKG` without cn-quickstart.
- [Splice LocalNet](https://docs.sync.global/app_dev/testing/localnet.html) —
  plain Docker Compose. Its App Provider participant is on the ports used above
  (`3901` gRPC, `3902` admin, `3975` JSON), so `CANTON_TEST_ENDPOINT` and
  `CANTON_TEST_JSON_ENDPOINT` need no changes. It runs **unauthenticated** by
  default — its only other profile is `unsafe-jwt-hmac-256`, an HMAC secret you
  sign tokens with yourself — so there is no OIDC token endpoint. Set the token
  you signed as `CANTON_TOKEN` and everything except the two issuer-dependent
  tests runs; the command-submission ones additionally want a package, which is
  what `cn-quickstart` supplies.
- [`cn-quickstart`](https://github.com/digital-asset/cn-quickstart)
  (`make setup && make build && make start`) — the same LocalNet plus the
  licensing sample app, which is where `CANTON_TEST_LICENSING_PKG` /
  `#quickstart-licensing` comes from; needed for the tests that submit commands.

More LocalNet tooling is catalogued on the
[Canton Dev Hub](https://dev-hub.canton.foundation/).

**Token standard, external signing and PQS** have live suites of their own,
each gated on one more variable:

| Variable | What it gates | Example (cn-quickstart) |
|---|---|---|
| `CANTON_TOKEN_REGISTRY_URL` | `canton-token`'s live suite and the five examples: the token-standard registry (a Splice **Scan**) | `http://scan.localhost:4000` on a Splice LocalNet or Canton Builder Tool; `http://localhost:5012` on cn-quickstart — see below |
| `CANTON_TOKEN_SENDER`, `CANTON_TOKEN_RECEIVER`, `CANTON_TOKEN_EXECUTOR`, `CANTON_TOKEN_INSTRUMENT`, `CANTON_TOKEN_AMOUNT` | the examples: who transfers what to whom | `app_provider_…::1220…`, `app_user_…::1220…`, `sv::1220…`, `Amulet`, `1.0` |
| `CANTON_TOKEN` | a ready-made bearer token, instead of the OIDC variables | on Canton Builder Tool: `$(canton builder token --validator app-provider)`, whose user carries `ParticipantAdmin` as well |
| `CANTON_TEST_AUDIENCE` | the OIDC `audience`, where the issuer wants one (Auth0, some Keycloak realms) | |
| `CANTON_TEST_ADMIN_CLIENT_ID`, `CANTON_TEST_ADMIN_CLIENT_SECRET` | `canton-ledger`'s `interactive_live` suite: onboarding an external party needs `ParticipantAdmin` | `app-provider-validator`, … |
| `CANTON_PQS_URL` | `canton-pqs`'s live suite: a Scribe store following the party's participant | `postgres://pqs:pqs@localhost:5433/pqs` from [`tools/pqs/compose.yaml`](tools/pqs/compose.yaml); cn-quickstart's own is `postgres://cnadmin:…@localhost:5432/pqs-app-provider` |

The **registry** is the super-validator's Scan, which serves the standard's
off-ledger API. A Splice LocalNet (and Canton Builder Tool, which runs one)
publishes it at `http://scan.localhost:4000`, the `/registry/…` paths
included, so nothing needs forwarding there. cn-quickstart runs the same Scan
when started with `SV_PROFILE=on`, on port `5012` of its `splice` container,
unpublished to the host. Forward it:

```sh
docker run -d --name canton-rs-scan-forward \
  --network "$(docker network ls --filter name=quickstart --format '{{.Name}}' | head -1)" \
  -p 5012:5012 alpine/socat TCP-LISTEN:5012,fork,reuseaddr TCP:splice:5012
curl -s http://localhost:5012/registry/metadata/v1/info   # {"adminId":"DSO::…","supportedApis":…}
```

Then the examples, in the order a wallet would run them:

```sh
export CANTON_TOKEN_REGISTRY_URL=http://localhost:5012
export CANTON_TOKEN_SENDER='app_provider_…::1220…' CANTON_TOKEN_RECEIVER='app_user_…::1220…'
export CANTON_TOKEN_EXECUTOR='sv::1220…' CANTON_TOKEN_INSTRUMENT=Amulet CANTON_TOKEN_AMOUNT=1.0
cargo run -p canton-token --example v1_transfer            # CIP-56
cargo run -p canton-token --example v2_transfer            # CIP-0112, over accounts
cargo run -p canton-token --example v2_allocate            # reserve for a settlement
cargo run -p canton-token --example v2_settle              # the executor settles the batch
cargo run -p canton-token --example v2_withdraw_allocation # or the sender takes it back
```

A **party with Canton Coin** is the other prerequisite: on a Splice LocalNet
open the App Provider wallet (`http://wallet.localhost:3000`, log in as
`app-provider`), tap, and copy the party id from the header (Canton Builder
Tool also prints it under `canton builder env`). With a single
party set `CANTON_TOKEN_RECEIVER` and `CANTON_TOKEN_EXECUTOR` to the sender:
the registry answers `kind: self`, which needs neither a pre-approval nor an
`accept`, and the settlement can be executed by the same token. With the App
User party as receiver the transfer is an `offer` to accept in that wallet
(`http://wallet.localhost:2000`).

Each example prints the registry's answer (`kind: self`, `direct` or `offer`,
the contracts it named for disclosure) and the committed update id and offset;
`CANTON_TOKEN_DRY_RUN=1` builds the command against the registry and stops
before submitting. Settling needs both sides of a leg authorised — the
receiver's own `ReceiverSide` allocation — which is why `v2_settle` is run
with the sender as receiver and executor when only one party is at hand.

On the **Canton Network DevNet** the same examples run against any validator
you hold a token for, with the public Scan of a super-validator as the
registry (`https://scan.sv-1.dev.global.canton.network.sync.global`,
unauthenticated). The run on record, update ids included, is in
[`docs/verification/token-standard-live-runs.md`](docs/verification/token-standard-live-runs.md).

```sh
# external signing: on an unauthenticated LocalNet nothing beyond the endpoint;
# cn-quickstart also wants the ParticipantAdmin client
export CANTON_TEST_ADMIN_CLIENT_ID=app-provider-validator CANTON_TEST_ADMIN_CLIENT_SECRET=…
cargo test -p canton-ledger --all-features --test interactive_live -- --nocapture   # 3 tests, one of them a refusal

# PQS: a Scribe store following the participant — this compose runs one
# (add SCRIBE_SOURCE_LEDGER_AUTH=OAuth CANTON_TOKEN=… where the participant wants a token)
docker compose -f tools/pqs/compose.yaml up -d
tools/pqs/wait-ready.sh      # Scribe applies its schema before the store answers
export CANTON_PQS_URL='postgres://pqs:pqs@localhost:5433/pqs'
cargo test -p canton-pqs --all-features --test live -- --nocapture                   # 9 tests; the store must hold Amulet, so tap first

# the registry, on its own
export CANTON_TOKEN_REGISTRY_URL=http://scan.localhost:4000
cargo test -p canton-token --test live -- --nocapture                                 # 5 tests against the registry
```

CI enforces `rustfmt`, `clippy -D warnings` (all features), the full test suite on Linux/macOS/Windows, rustdoc `-D warnings`, `cargo-deny`, and the MSRV build.

## MSRV

Rust **1.88** (bounded by `tonic` 0.14). Policy: the MSRV tracks what our
pinned major dependencies require; a bump is a minor (not breaking) change,
announced in the [CHANGELOG](CHANGELOG.md), and CI always builds the declared
MSRV.

## Roadmap

**Shipped:** the async Ledger API client (gRPC + JSON + WebSocket, auth, TLS,
retry, telemetry) and type-safe code generation from DAR packages — SCU-aware,
with a `dpm codegen-rust` component and prebuilt `canton-splice-*` crates. The
LF decoder is native Rust rather than a JVM wrapper around `daml-lf-archive`
([ADR-0008](docs/adr/0008-native-lf-decoder.md)); its output is held to the
official JVM reader by a conformance oracle.

Token-standard support (CIP-56 V1 + CIP-0112 V2), interactive submission with a
pluggable signer, a typed PQS client and the Ledger-Client-Standard conformance
suite have since landed on top of that.

## Contributing & security

See [CONTRIBUTING.md](CONTRIBUTING.md) for the development workflow and
[SECURITY.md](SECURITY.md) for private vulnerability reporting. Notable
changes are tracked in [CHANGELOG.md](CHANGELOG.md).

## Acknowledgements

Built on the Ledger API and Daml-LF work of the
[Canton](https://github.com/digital-asset/canton) and
[Splice](https://github.com/canton-network/splice) teams.

The local-development path reads the environment
[canton-devkit](https://github.com/bitdynamics-ab/canton-devkit) exports, and
reading its DAR container taught us that a per-entry decompression cap bounds
nothing on its own — an archive is now bounded in total as well.

[Equilibrium](https://equilibrium.co) reviewed the released M1 client from an
independent engineering perspective and reported a credential leak privately
before anything else. Their findings are closed in 0.2.0 and listed in the
[changelog](CHANGELOG.md); several are the kind that only a reader who does not
already know what the code meant to do would find.

## License

Apache-2.0. See [LICENSE](LICENSE).