SDK Setup and Installation

SDK setup and installation

Install and configure cbtc-lib v0.9.0 with its matching canton-lib v0.11.0 dependencies. Start with a read-only check before running any operation that changes ledger state.

⚠️ API Disclaimer. CBTC APIs have no formal versioning policy today. All SDK interfaces described in this guide are subject to change. Breaking changes are communicated via the changelog.

Requirements

Requirement	Details
Rust toolchain	A stable toolchain compatible with the tagged workspace and Rust edition 2024.
Canton participant	A Canton 3.6.1 participant connected to the intended environment. Engineering tested cbtc-lib v0.9.0 on Canton 3.6.1 only.
Registry Utility	Required components for token transfer operations.
Authentication	The environment’s approved host, realm, client identity, and credentials.
Party	A Canton party authorized for the intended operation.
Instrument	The exact instrument name and administrator for the selected environment.
Account	The intended account for V2 operations and account-scoped holding reads.
Minter credential	Required for minting or burning CBTC. Holding, sending, and receiving do not require this credential. Request onboarding through sales@bitsafe.finance.
Repository access	Authorized SSH access to the library repositories.

Install cbtc-lib

The repository is named cbtc-lib. Its Rust crate is named cbtc.

Add the pinned dependency to Cargo.toml:

[dependencies]
cbtc = { git = "ssh://git@github.com/DLC-link/cbtc-lib", tag = "v0.9.0" }

Use an immutable release tag rather than main.

Direct canton-lib dependencies

cbtc-lib v0.9.0 pins canton-lib v0.11.0. Add direct canton-lib dependencies only when the application needs those crates.

For example, an application using the Keycloak helper can add:

keycloak = { git = "ssh://git@github.com/DLC-link/canton-lib", tag = "v0.11.0" }

Use the same tag and source specification as cbtc-lib. Do not mix another tag or a revision specification with this pin.

Mismatched pins can build two common packages. Their shared types then differ, and the application fails to compile. An application that depends on canton-api-client must pin version 3.6.1-0.1.0, which cbtc-lib v0.9.0 uses.

cbtc re-exports InstrumentId, Account and DamlDecimal at the crate root. The cbtc::types module re-exports the parameter types. These exports often remove the need for a direct common dependency.

Key modules

Module	Purpose
`cbtc::mint_redeem::mint`	Create deposit accounts and obtain Bitcoin deposit addresses.
`cbtc::mint_redeem::redeem`	Create withdrawal accounts and submit CBTC redemption.
`cbtc::transfer`	Submit V1 transfers and read their receipts.
`cbtc::transfer::v2`	Submit account-aware V2 transfers.
`cbtc::accept`	Accept incoming offers.
`cbtc::reject`	Reject incoming offers.
`cbtc::active_contracts`	Query holdings for the party and configured account scope.
`cbtc::consolidate`	Consolidate holdings.
`cbtc::split`	Split holdings and report partial results on failure.
`cbtc::batch`	Distribute from CSV and return batch results.
`cbtc::distribute`	Distribute to an in-memory recipient list.
`cbtc::cancel_offers`	Cancel outgoing offers.
`cbtc::credentials`	Query and accept credentials.
`cbtc::allocation`	V1-only Delivery-versus-Payment allocation.
`cbtc::dar_check`	Compare repository DAR packages with installed packages.

Eight token operations have V2 submodules. Consult the token-standard model for the complete boundary.

Configure the repository examples

The repository examples load a local .env file. Copy the tagged template:

cp .env.example .env

Use this setup pattern, replacing every placeholder:

ENVIRONMENT=testnet
LEDGER_HOST=https://participant.example.com/api/json-api
PARTY_ID=your-party-id

KEYCLOAK_HOST=https://keycloak.example.com
KEYCLOAK_REALM=your-realm
KEYCLOAK_CLIENT_ID=your-client-id
KEYCLOAK_USERNAME=your-username
KEYCLOAK_PASSWORD=your-password

# Optional overrides for the selected environment:
# DECENTRALIZED_PARTY_ID=approved-administrator-party
# REGISTRY_URL=https://approved-registry.example.com
# BITSAFE_API_URL=https://approved-api.example.com

Accepted built-in environment values are devnet, testnet, and mainnet.

ENVIRONMENT resolves the Decentralized Party identifier, registry URL, and BitSafe API URL. Explicit non-empty overrides take precedence. Existing explicit configuration does not need a forced rewrite.

The ledger host, party, and authentication credentials remain explicit. LEDGER_HOST must include the JSON API path required by the participant. A bare host can return 404.

BITSAFE_API_URL identifies the BitSafe API gateway for mint and redemption. An Attestor or Coordinator host is not a replacement.

Do not commit .env files or credentials. Run local build and test checks in a clean shell without live credentials. Exported shell variables can take precedence over .env values.

Configuration in Rust applications

Setting ENVIRONMENT does not automatically configure arbitrary Rust library calls.

Use cbtc::Network to obtain built-in network values. Pass configuration explicitly to the relevant parameters or TokenClientConfig.

Set TokenClientConfig.version for version-dependent writes and holding reads. Its incoming and outgoing offer helpers are version-neutral.

Authentication

Use keycloak::login::token_url to construct the token endpoint.

Keycloak 17 removed /auth from its default URL path. The obsolete password_url helper adds that prefix and caused login failures in BitSafe deployments.

For password-grant authentication, the tagged examples use password(PasswordParams { ... }). For service-to-service authentication, use the approved client-credentials flow for the deployment.

Use these pinned examples for the exact imports and parameter construction:

Never embed real credentials in source code. Confirm that the token authorizes the intended party before submitting commands.

Install the approved DAR set

DAR files contain the Daml contract packages used by CBTC and its dependencies.

Install the Engineering-approved package set for the target environment. Do not install every bundled version merely because it appears in the repository.

Crate versions and DAR versions use independent numbering. A cbtc-lib version does not identify the approved DAR set.

The repository can contain packages ahead of an environment’s deployment. Confirm the environment manifest, dependencies, and vetting requirements before upload.

From the tagged repository, run:

cargo run --example check_dars

A pass confirms package presence only. It does not prove permissions, package vetting, or end-to-end compatibility. Investigate missing packages against the approved environment manifest before installing anything.

Obtain the instrument identifier through the supported configuration or discovery flow. Do not infer an instrument identifier from a DAR filename.

Verify the installation

Use the repository’s pinned read-only example instead of copying an older parameter signature.

Check out the approved v0.9.0 tag.
Complete the local configuration.
Build the workspace without live credentials:

cargo build --examples

In the approved test environment, run:

cargo run --example check_balance

The example authenticates and queries holdings with explicit instrument_id and account fields. It uses account: None to read the party’s holdings for the exact instrument.

An empty result can be valid when the party has no matching holdings. Confirm the party, administrator, instrument name, and account scope before concluding that assets are missing.

For an account-scoped V2 check, inspect and run the tagged read-only example:

cargo run --example token_client

This example reads one account. Holdings in another labelled account can appear in check_balance but not in this result.

Continue to a state-changing operation only after authentication, parsing, party identity, instrument identity, and account scope are correct.

Technical sources

Next Steps

Quick Start - Mint your first wrapped Bitcoin in 15 minutes
CBTC Minting and Burning - The mint and burn lifecycle in depth, with error handling and recovery patterns
API Reference - Full Canton Ledger API endpoint documentation
Instrument ID Management - How to fetch and poll for the latest CBTC Instrument IDs
Authentication Guide - Detailed Keycloak setup and Auth0 community example
Testnet Guide - Get testnet CBTC from the faucet and test before going live