> 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/beth/concepts-and-reference/compatibility-and-release-notes.md).

# Compatibility and release notes

[BETH environments and prerequisites](/beth/get-started/environments-and-prerequisites.md)

### Purpose

Use this reference to:

* Choose a known-good BETH 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 BETH 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                                                                           |
| ----------------------------------- | ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| `bitsafe-token-lib`                 | `v0.2.0`                                                          | Signed Git tag and GitHub release published 9 October 2026. The package manifest reports version `0.2.0`.                              | Repository baseline. Verify the target environment and support window.           |
| `canton-lib`                        | `v0.11.0`                                                         | `bitsafe-token-lib` `v0.2.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 `bitsafe-token-lib` `v0.2.0` package manifest.                                                                         | Wire-client baseline. Verify the approved participant range.                     |
| Canton participant                  | `3.6.1` for `bitsafe-token-lib` `v0.2.0`                          | The library uses the Canton `3.6.1` API client. Its active-contract requests use the `eventFormat` field that Canton `3.6.1` requires. | Verify the maintained support range before you use an older participant.         |
| BETH DAR package                    | Package bundled at `bitsafe-token-lib` `v0.2.0`: `beth-0.2.0.dar` | The `v0.2.0` DAR directory includes `beth-0.2.0.dar` and its package ID and SHA-256 checksum.                                          | Bundled candidate, not proof that every environment has deployed or approved it. |
| Utility and Splice DAR dependencies | Tagged manifest under `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              | `bitsafe-token-lib` | `canton-lib` | Canton participant              | BETH DAR                   | Utility and Splice release      | Last verified                       | Support status           |
| ------------------------ | ------------------- | ------------ | ------------------------------- | -------------------------- | ------------------------------- | ----------------------------------- | ------------------------ |
| Repository baseline only | `v0.2.0`            | `v0.11.0`    | Verify in the maintained matrix | Bundled candidate: `0.2.0` | Verify in the maintained matrix | 12 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 `bitsafe-token-lib`.** Use an immutable tag. Do not use a mutable `main` branch in production guidance.
3. **Use the matching `canton-lib` tag.** Read the `bitsafe-token-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, `dars/upload_dars.sh beth`, which uploads dependency DARs before BETH DARs. Confirm the environment manifest before running it.
6. **Run the DAR inventory check.** `ASSET=beth 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" %}
Release notes summarize public repository releases. They are not deployment announcements and do not prove that every environment supports the released files.
{% endhint %}

Each library publishes its release notes on GitHub:

* [`bitsafe-token-lib` releases](https://github.com/DLC-link/bitsafe-token-lib/releases)
* [`canton-lib` releases](https://github.com/DLC-link/canton-lib/releases)

### 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

* [`bitsafe-token-lib` release `v0.2.0`](https://github.com/DLC-link/bitsafe-token-lib/releases/tag/v0.2.0)
* [`bitsafe-token-lib` package manifest at `v0.2.0`](https://github.com/DLC-link/bitsafe-token-lib/blob/v0.2.0/Cargo.toml)
* [`bitsafe-token-lib` changelog at `v0.2.0`](https://github.com/DLC-link/bitsafe-token-lib/blob/v0.2.0/CHANGELOG.md)
* [`bitsafe-token-lib` release `v0.1.0`](https://github.com/DLC-link/bitsafe-token-lib/releases/tag/v0.1.0)
* [BETH DAR guidance at `v0.2.0`](https://github.com/DLC-link/bitsafe-token-lib/tree/v0.2.0/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

* [BETH environments and prerequisites](/beth/get-started/environments-and-prerequisites.md)
* [Install and validate BETH DARs](/beth/get-started/install-and-validate-dars.md)
* [BETH SDK, API, and integration reference](/beth/concepts-and-reference/sdk-api-and-integration-reference.md)
* [BETH errors, retries, and troubleshooting](/beth/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:** [BETH developer Quick Start](/beth/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/beth/concepts-and-reference/compatibility-and-release-notes.md?ask=<question>&goal=<user_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.