Ctrlk
Go to websiteTalk to BitSafe
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Compatibility and release notes

CBTC environments and prerequisites

Purpose

Use this reference to:

  • Choose a known-good CBTC component set.

  • Check what changed between repository releases.

  • Identify required migration work.

  • Determine whether a reported problem is a documented issue or an unconfirmed compatibility gap.

Before you upgrade

  • Pin every library and package to an immutable release tag or approved manifest.

  • Confirm the target environment before installing CBTC DAR packages.

  • Do not infer production support from files bundled in a repository tag.

  • Test the complete workflow in the target environment before production use.

  • Keep rollback instructions and the previously approved component set available.

Compatibility at a glance

The table below records the repository baseline. Verify the complete component row against the maintained compatibility matrix before deployment.

Component
Repository baseline
Evidence
Status

cbtc-lib

v0.6.4

Signed Git tag and GitHub release published 6 July 2026. The package manifest reports version 0.6.4.

Repository baseline. Verify the target environment and support window.

canton-lib

v0.6.1

cbtc-lib v0.6.4 pins the ledger, keycloak, registry, and common crates to this tag.

Direct dependency of the working baseline.

canton-api-client

3.6.0-0.1.0

Declared by the cbtc-lib v0.6.4 package manifest.

Wire-client baseline. Verify the approved participant range.

Canton participant

3.6.x for cbtc-lib v0.6.0

The v0.6.0 release notes state that older 3.4.x and 3.5.x participants reject requests sent by that release.

Verify the maintained support range before applying this requirement to later releases.

CBTC DAR package

Latest package bundled at cbtc-lib v0.6.4: cbtc-1.2.1.dar

The signed tag message says “New CBTC DAR v1.2.1,” and the tagged DAR directory includes versions 1.0.0 through 1.2.1.

Bundled candidate, not proof that every environment has deployed or approved it.

Utility and Splice DAR dependencies

Tagged manifest under cbtc-dars/dars/dependencies

The repository includes the dependency files used by its upload and validation tooling.

Verify the environment-specific dependency set and vetting status.

Compatibility matrix format

Use the maintained machine-readable matrix for mutable version and support information.

Environment

cbtc-lib

canton-lib

Canton participant

CBTC DAR

Utility and Splice release

Last verified

Support status

Repository baseline only

v0.6.4

v0.6.1

Verify in the maintained matrix

Latest bundled candidate: 1.2.1

Verify in the maintained matrix

9 August 2026, source review only

Repository baseline only

Use these support labels consistently:

  • Supported: Engineering has validated the complete row and owns its support window.

  • Maintenance: Security and critical fixes only, with an announced end date.

  • Deprecated: A replacement and migration path exist, and removal is scheduled.

  • Unsupported: No compatibility or operational support is provided.

Select and verify a component set

  1. Choose the target environment. Use the maintained environment reference. Do not copy party identifiers, endpoints, or package IDs from another environment.

  2. Pin cbtc-lib. Use an immutable tag. Do not use a mutable main branch in production guidance.

  3. Use the matching canton-lib tag. Read the cbtc-lib package manifest for the exact dependency pin.

  4. Confirm the Canton participant version. Check the approved matrix before building or submitting commands.

  5. Install the approved DAR set. The repository recommends the gRPC upload script, which uploads dependency DARs before CBTC DARs. Confirm the environment manifest before running it.

  6. Run the DAR inventory check. cargo run --example check_dars compares the tagged DAR files with packages installed on the participant. A pass confirms package presence only. It does not prove environment compatibility, package vetting, permissions, or a working mint or redemption flow.

  7. Run a read-only check. Authenticate, select the intended party, and run a balance or contract query.

  8. Run the environment acceptance test. Complete the approved operation, verify the ledger and application result, and record the tested versions and date.

  9. Keep rollback evidence. Record the previously supported matrix row and the conditions for reverting.

Release notes

These entries summarize public repository releases. They are not deployment announcements and do not prove that every environment supports the released files.

6 July 2026: cbtc-lib v0.6.4

Changed

  • Added the CBTC DAR v1.2.1 to the tagged release.

  • Set the cbtc package version to 0.6.4.

  • Continued to pin the shared canton-lib crates to v0.6.1.

Action for integrators

  • Confirm that the target environment has approved CBTC DAR v1.2.1 before installation or upgrade.

  • Run the DAR inventory check and the approved environment acceptance test.

24 June 2026: cbtc-lib v0.6.3

Added

  • Added the cbtc-tui interactive terminal interface for supported queries and commands.

  • Added Delivery-versus-Payment allocation client flows.

Changed

  • Pinned canton-lib to v0.6.1.

Action for integrators

  • Review terminal configuration and secret storage before operator use.

  • Validate allocation flows in the target environment before production use.

8 June 2026: cbtc-lib v0.6.2

Added

  • Added an example for listing withdrawal accounts.

  • Added CBTC brand assets.

Fixed

  • Corrected upgrade pinning in the withdrawal submission path.

Action for integrators

  • Re-test withdrawal-account discovery and withdrawal submission when upgrading from an earlier release.

19 May 2026: cbtc-lib v0.6.0

Changed

  • Updated the generated Canton API client from 3.3.0-0.1.0 to 3.6.0-0.1.0 through canton-lib v0.6.0.

  • Updated request and response handling for fields that became optional in the Canton 3.6.0 specification.

  • Changed ledger-end handling so a missing upstream offset returns an error instead of silently defaulting to zero.

Fixed

  • Updated the integration test so it selects current CBTC holdings rather than a legacy CBTCV0RC8 instrument during the split step.

Compatibility and migration

  • The release notes require a Canton 3.6.x participant for this release.

  • The upgrade path is v0.4.2 to v0.6.0. No cbtc-lib v0.5.0 release was published.

  • Callers that use ledger-end data must handle the missing-offset error explicitly.

Shared library changes that affect CBTC

canton-lib v0.6.1, 24 June 2026

  • Added Token Standard allocation client support for Delivery-versus-Payment workflows.

  • Added allocation domain types, registry calls, choice contexts, and submission variants.

canton-lib v0.6.0, 19 May 2026

  • Added token URL helpers for Keycloak 17 and later deployments that do not use the legacy /auth context root.

  • Updated the generated API client to Canton 3.6.0.

  • Preserved legacy Keycloak URL helpers for backwards compatibility.

  • Changed missing ledger-end offsets from an implicit zero to an explicit error.

canton-lib v0.5.0, 11 May 2026

  • Added wait_for_transaction for the flat POST /v2/commands/submit-and-wait-for-transaction endpoint.

  • Deprecated wait_for_transaction_tree.

  • Documented the required parser migration from transactionTree.eventsById to transaction.events.

canton-lib v0.4.0, 7 April 2026

  • Introduced DamlDecimal for Daml Decimal values.

  • Changed transfer amounts and decimal context values from strings or floating-point values to the validated decimal type.

  • Required source changes for consumers of the earlier decimal API.

Deprecations and migration actions

Deprecated behavior
Replacement
Migration action
Removal or compatibility note

ledger::submit::wait_for_transaction_tree

ledger::submit::wait_for_transaction

Update the function call. Replace transactionTree.eventsById parsing with iteration over transaction.events. Rename tree event variants to their flat equivalents.

The transaction-tree endpoint was removed in Canton 3.5.0.

Implicit zero when the ledger-end offset is missing

Explicit error handling

Handle Err("Ledger end response missing offset") and investigate the upstream response.

Behavior changed in canton-lib v0.6.0.

String or floating-point Daml decimal values in older canton-lib consumers

common::decimal::DamlDecimal

Parse validated decimal values and update affected transfer, context, and wallet fields.

Breaking change introduced in canton-lib v0.4.0.

Unpinned Git dependencies in examples or local projects

Immutable release tags from the approved matrix

Replace branch references with the exact approved tag before release.

Documentation safety rule, not a code-level deprecation.

Technical sources

Related pages

Next step

👉 Use a supported path: CBTC developer Quick Start.

PreviousErrors, retries, and troubleshooting

Last updated