SDK Setup and Installation

⚠️ 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.

---

This page is your single reference for installing and configuring everything you need to build with CBTC. If you've already completed setup, head straight to the Quick Start to mint your first wrapped Bitcoin.

---

System Requirements

Requirement	Details
Rust toolchain	Latest stable. Install via rustup.rs
Canton participant node	Running and connected to devnet, testnet, or mainnet. See Canton documentation
DA Registry Utility	Installed and configured. See Digital Asset Utilities docs
Keycloak credentials	Host, realm, client ID, username, and password for your environment
Party ID	Your Canton Party ID, obtained during onboarding
Minter credential	Only required to mint or burn CBTC. Issued to your party by the CBTC registrar; request one via [e-mail]. Holding, sending, and receiving CBTC do not require it.

---

Install cbtc-lib (Rust)

cbtc-lib is BitSafe's primary SDK for CBTC operations: minting, burning, transferring, UTXO management, and balance queries. It wraps the Canton Ledger API with type-safe Rust functions.

• Repository: github.com/DLC-link/cbtc-lib

• Current version: v0.6.4

• Licence: Check repository

Add to your project

Add cbtc-lib to your Cargo.toml:

[dependencies]
cbtc = { git = "ssh://[e-mail]/DLC-link/cbtc-lib.git", tag = "v0.6.4" }

📌 Pin your version. Always reference a specific tag (e.g. v0.6.4) rather than main. The library is under active development and main may contain breaking changes between releases.

Key modules

Module	Purpose
cbtc::mint_redeem::mint	Create deposit accounts, get Bitcoin deposit addresses
cbtc::mint_redeem::redeem	Create withdraw accounts, burn CBTC and withdraw to BTC
cbtc::transfer	Send CBTC to another party (creates transfer offer)
cbtc::accept	Accept incoming CBTC transfer offers
cbtc::active_contracts	Query current CBTC holdings for a party
cbtc::consolidate	Merge multiple UTXO holdings into fewer contracts
cbtc::split	Split a single holding into multiple UTXOs
cbtc::batch	Batch operations for sending to multiple recipients
cbtc::distribute	Distribute CBTC across multiple parties
cbtc::cancel_offers	Cancel pending outgoing transfer offers
cbtc::credentials	List and accept Minter credentials (required to mint or burn)
cbtc::allocation	Allocate CBTC into DvP settlement legs (delivery-versus-payment)

---

Install canton-lib

canton-lib is now a Rust workspace containing multiple crates that cbtc depends on. It handles Canton Ledger API communication, authentication, and Daml contract interactions.

• Repository: github.com/DLC-link/canton-lib

• Crates: keycloak, ledger, registry, common (all at v0.6.1)

Add to your project

Add the canton-lib crates you need to your Cargo.toml:

[dependencies]
keycloak = { git = "ssh://[e-mail]/DLC-link/canton-lib.git", tag = "v0.6.1" }
ledger = { git = "ssh://[e-mail]/DLC-link/canton-lib.git", tag = "v0.6.1" }
registry = { git = "ssh://[e-mail]/DLC-link/canton-lib.git", tag = "v0.6.1" }
common = { git = "ssh://[e-mail]/DLC-link/canton-lib.git", tag = "v0.6.1" }

📌 Match the tag cbtc-lib depends on. cbtc-lib v0.6.4 pins canton-lib v0.6.1. If you add these crates at a different tag than the one cbtc-lib uses, Cargo will resolve two incompatible copies of the same types and your build will fail with confusing mismatched-type errors.

The keycloak crate provides authentication helpers used across all CBTC operations.

Password-grant authentication (for user-facing flows):

use keycloak::login::{password, password_url, PasswordParams};

let auth = password(PasswordParams {
 client_id: keycloak_client_id.clone(),
 username: keycloak_username.clone(),
 password: keycloak_password.clone(),
 url: password_url(&keycloak_host, &keycloak_realm),
}).await?;

let access_token = auth.access_token;

Client credentials authentication (for service-to-service / backend flows):

use keycloak::login::{client_credentials, client_credentials_url, ClientCredentialsParams};

let auth = client_credentials(ClientCredentialsParams {
 url: client_credentials_url("https://your-keycloak-host", "your-realm"),
 client_id: "your-client-id".to_string(),
 client_secret: "your-client-secret".to_string(),
}).await?;

let access_token = auth.access_token;

---

Install CBTC DAR Files

DAR (Daml Archive) files contain the smart contract templates that power CBTC on Canton. They must be installed on your participant node before you can interact with CBTC.

Download: github.com/DLC-link/cbtc-lib/tree/v0.6.4/cbtc-dars

The latest CBTC DAR is cbtc-1.2.1, shipped in cbtc-lib v0.6.4. DAR versions and crate versions are numbered independently.

Install the DAR files on your Canton participant node using the Canton console or your deployment tooling. The specific installation method depends on your Canton setup. Refer to the Canton documentation for details.

💡 Install every DAR version, not just the newest. The repository ships all released DARs (cbtc-1.0.0 through cbtc-1.2.1). Older versions are required to interact with contracts still live on the network from earlier releases. You can verify what your participant is missing with the cbtc::dar_check module.

💡 DAR version and Instrument IDs are linked. When DAR files are upgraded on the network, Instrument IDs may change. Always fetch Instrument IDs dynamically from the metadata endpoint rather than hardcoding them. See the Instrument ID Management page for the polling pattern.

---

Environment Configuration

Set these variables before running any CBTC commands or code. Values differ per environment.

Variable	Devnet	Testnet	Mainnet
REGISTRY_URL	https://api.utilities.digitalasset-dev.com	https://api.utilities.digitalasset-staging.com	https://api.utilities.digitalasset.com
BITSAFE_API_URL	https://api.devnet.bitsafe.finance	https://api.testnet.bitsafe.finance	https://api.mainnet.bitsafe.finance
DECENTRALIZED_PARTY_ID	Provided during onboarding	Provided during onboarding	Provided during onboarding

💡 BITSAFE_API_URL is the BitSafe API gateway, which serves the /cbtc/v1/* endpoints behind deposit accounts, deposit addresses, and withdrawals. cbtc-lib reads it and passes it as the api_url parameter to get_account_contract_rules, get_bitcoin_address, and submit_withdraw. An Attestor or Coordinator host will not work in its place.

Example.env file

# Environment (choose one: devnet, testnet, mainnet)
REGISTRY_URL="https://api.utilities.digitalasset-staging.com"
BITSAFE_API_URL="https://api.testnet.bitsafe.finance"
CANTON_NETWORK="canton-testnet"
PARTY_ID="your-party-id"

# Authentication (Keycloak)
KEYCLOAK_HOST="https://your-keycloak-host"
KEYCLOAK_REALM="your-realm"
KEYCLOAK_CLIENT_ID="your-client-id"
KEYCLOAK_USERNAME="your-username"
KEYCLOAK_PASSWORD="your-password"

# Canton participant
LEDGER_HOST="https://your-ledger-host"

---

Verify Your Installation

Run this minimal check to confirm everything is wired up:

use keycloak::login::{password, password_url, PasswordParams};
use cbtc::active_contracts;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
 // 1. Authenticate
 let auth = password(PasswordParams {
 client_id: std::env::var("KEYCLOAK_CLIENT_ID")?,
 username: std::env::var("KEYCLOAK_USERNAME")?,
 password: std::env::var("KEYCLOAK_PASSWORD")?,
 url: password_url(
 &std::env::var("KEYCLOAK_HOST")?,
 &std::env::var("KEYCLOAK_REALM")?,
 ),
 }).await?;

 println!("✅ Authenticated successfully");

 // 2. Query holdings (should return empty if no CBTC yet)
 let holdings = active_contracts::get(active_contracts::Params {
 ledger_host: std::env::var("LEDGER_HOST")?,
 party: std::env::var("PARTY_ID")?,
 access_token: auth.access_token,
 }).await?;

 println!("✅ Connected to Canton. Current CBTC holdings: {}", holdings.len());
 Ok(())
}

If both checks pass, you're ready. Head to the Quick Start to mint your first CBTC.

---

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

---