> For the complete documentation index, see [llms.txt](https://docs.bitsafe.finance/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bitsafe.finance/cbtc/concepts-and-reference/compatibility-and-release-notes.md). # Compatibility and release notes [CBTC environments and prerequisites](/cbtc/get-started/environments-and-prerequisites.md) ### 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 {% hint style="info" %} These entries summarize public repository releases. They are not deployment announcements and do not prove that every environment supports the released files. {% endhint %} #### 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 * [`cbtc-lib` release `v0.6.4`](https://github.com/DLC-link/cbtc-lib/releases/tag/v0.6.4) * [`cbtc-lib` package manifest at `v0.6.4`](https://github.com/DLC-link/cbtc-lib/blob/v0.6.4/Cargo.toml) * [`cbtc-lib` release `v0.6.3`](https://github.com/DLC-link/cbtc-lib/releases/tag/v0.6.3) * [`cbtc-lib` release `v0.6.2`](https://github.com/DLC-link/cbtc-lib/releases/tag/v0.6.2) * [`cbtc-lib` release `v0.6.0`](https://github.com/DLC-link/cbtc-lib/releases/tag/v0.6.0) * [CBTC DAR guidance at `v0.6.4`](https://github.com/DLC-link/cbtc-lib/tree/v0.6.4/cbtc-dars) * [`canton-lib` changelog at `v0.6.1`](https://github.com/DLC-link/canton-lib/blob/v0.6.1/CHANGELOG.md) * [`canton-lib` package manifest at `v0.6.1`](https://github.com/DLC-link/canton-lib/blob/v0.6.1/Cargo.toml) ### Related pages * [CBTC environments and prerequisites](/cbtc/get-started/environments-and-prerequisites.md) * [Install and validate CBTC DARs](/cbtc/get-started/install-and-validate-dars.md) * [CBTC SDK, API, and integration reference](/cbtc/concepts-and-reference/sdk-api-and-integration-reference.md) * [CBTC errors, retries, and troubleshooting](/cbtc/concepts-and-reference/errors-retries-and-troubleshooting.md) * [Support and developer resources](https://docs.bitsafe.finance/support-and-developer-resources/) ### Next step πŸ‘‰ **Use a supported path:** [CBTC developer Quick Start](/cbtc/get-started/developer-quick-start.md). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.bitsafe.finance/cbtc/concepts-and-reference/compatibility-and-release-notes.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.