> 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.9.0` | Signed Git tag and GitHub release published 8 October 2026. The package manifest reports version `0.9.0`. | Repository baseline. Verify the target environment and support window. | | `canton-lib` | `v0.11.0` | `cbtc-lib` `v0.9.0` pins the `token`, `ledger`, `keycloak`, `registry`, and `common` crates to this tag. | Direct dependency of the working baseline. | | `canton-api-client` | `3.6.1-0.1.0` | Declared by the `cbtc-lib` `v0.9.0` package manifest. | Wire-client baseline. Verify the approved participant range. | | Canton participant | `3.6.1` for `cbtc-lib` `v0.9.0` | The `v0.9.0` release notes state that the release is tested on Canton `3.6.1` only, on devnet. Canton `3.6.1` rejects the active-contract requests of `cbtc-lib` `v0.8.0` and earlier. | Verify the maintained support range before you use an older participant. | | CBTC DAR package | Latest package bundled at `cbtc-lib` `v0.9.0`: `cbtc-1.2.1.dar` | The `v0.6.4` tag message says β€œNew CBTC DAR v1.2.1.” The `v0.9.0` DAR directory still 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.9.0` | `v0.11.0` | Verify in the maintained matrix | Latest bundled candidate: `1.2.1` | Verify in the maintained matrix | 8 October 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 %} #### 8 October 2026: `cbtc-lib` `v0.9.0` **Changed** * Pinned the shared `canton-lib` crates to `v0.11.0`. Active-contract queries now send `eventFormat` in place of the top-level `filter` and `verbose` fields. * Updated `canton-api-client` from `3.6.0-0.1.0` to `3.6.1-0.1.0`. * Changed websocket queries to return the Ledger API error. Earlier releases returned an empty result when the participant rejected the request. **Compatibility and migration** * The release is tested on Canton `3.6.1` only, on devnet. * Canton `3.6.1` rejects the active-contract requests of `cbtc-lib` `v0.8.0` and earlier. On that participant, an older balance query can report 0, and mint and redeem fail. * Consumers that also pin `canton-lib` must move to `v0.11.0`. Consumers of `canton-api-client` must move to `3.6.1-0.1.0`. **Action for integrators** * Upgrade before or with the move to a Canton `3.6.1` participant. * Confirm that `Cargo.lock` holds one `common` package. #### 1 October 2026: `cbtc-lib` `v0.8.0` **Added** * Added examples for rejecting a transfer, withdrawing an allocation, and four Token Standard V2 operations. **Changed** * Pinned the shared `canton-lib` crates to `v0.9.0`. * `transfer::submit` and `transfer::v2::submit` return a `TransferReceipt`. The registry creates an offer, or it settles the transfer on submission. * `allocation::allocate` returns the created allocation. Batch submission from CSV returns the per-transfer results. **Action for integrators** * Read the transfer receipt to learn whether the receiver must accept an offer. * Read the batch `failed_count`. An `Ok` result means that the batch ran, not that every transfer succeeded. #### 24 September 2026: `cbtc-lib` `v0.7.0` **Added** * Re-exported the `canton-lib` `token` crate for every Token Standard operation. `mint_redeem` stays in `cbtc-lib`. * Added Token Standard V2 entry points in `v2` submodules, `cbtc::TokenClient`, and `cbtc::Network`. **Changed** * Every operation takes the instrument from the caller. Holding and offer filters match the instrument ID and admin exactly. * Authentication uses `keycloak::login::token_url`, which omits the `/auth` prefix. * `.env.example` uses one `ENVIRONMENT` key. `DECENTRALIZED_PARTY_ID`, `REGISTRY_URL`, and `BITSAFE_API_URL` stay available as overrides. * Four registry routes retry a request that does not reach the host. An unreachable registry fails after approximately 90 seconds. **Action for integrators** * Add `instrument_id` to the changed parameter structs, and compare whole `InstrumentId` values. * Set any caller timeout above 90 seconds for registry calls. #### 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.11.0`, 8 October 2026 * Updated the generated API client to Canton `3.6.1`. * Required callers of the re-exported `ledger::models` types to move to client `3.6.1`. #### `canton-lib` `v0.10.1`, 7 October 2026 * Changed the websocket active-contract and update functions to return the Ledger API error. Earlier releases returned an empty result. #### `canton-lib` `v0.10.0`, 6 October 2026 * Replaced the top-level `filter` and `verbose` request fields with `eventFormat` or `updateFormat`. Canton `3.6.1` rejects the old fields. * Replaced `common::TransactionFilter` with `common::EventFormat`. * Removed `wait_for_transaction_tree`. #### `canton-lib` `v0.9.0`, 1 October 2026 * Accepted a transfer that settles on submission. Earlier releases reported it as a failure. * Changed `transfer::submit`, `allocation::allocate`, and `batch::submit_from_csv` to return their results. #### `canton-lib` `v0.8.0`, 16 September 2026 * Moved `InstrumentId` to `common::instrument`. * Changed `Holding.instrument_id` from the ticker string to an `InstrumentId` that includes the admin. #### `canton-lib` `v0.7.0`, 9 September 2026 * Added Token Standard V2 entry points and `TokenClientConfig.version`. * Added retries for four registry routes when a request does not reach the host. #### `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. | Removed in `canton-lib` `v0.10.0`. Canton `3.6.1` disables the endpoint. | | 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.9.0`](https://github.com/DLC-link/cbtc-lib/releases/tag/v0.9.0) * [`cbtc-lib` package manifest at `v0.9.0`](https://github.com/DLC-link/cbtc-lib/blob/v0.9.0/Cargo.toml) * [`cbtc-lib` changelog at `v0.9.0`](https://github.com/DLC-link/cbtc-lib/blob/v0.9.0/CHANGELOG.md) * [`cbtc-lib` release `v0.6.4`](https://github.com/DLC-link/cbtc-lib/releases/tag/v0.6.4) * [`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.9.0`](https://github.com/DLC-link/cbtc-lib/tree/v0.9.0/cbtc-dars) * [`canton-lib` changelog at `v0.11.0`](https://github.com/DLC-link/canton-lib/blob/v0.11.0/CHANGELOG.md) * [`canton-lib` package manifest at `v0.11.0`](https://github.com/DLC-link/canton-lib/blob/v0.11.0/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 by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` 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 what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. 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.