# 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](https://docs.bitsafe.finance/developers/cbtc-quick-start) to mint your first wrapped Bitcoin. *** ## System Requirements | Requirement | Details | | --------------------------- | ------------------------------------------------------------------------------------------------------------------------ | | **Rust toolchain** | Latest stable. Install via [rustup.rs](https://rustup.rs/) | | **Canton participant node** | Running and connected to devnet, testnet, or mainnet. See [Canton documentation](https://docs.digitalasset.com/canton) | | **DA Registry Utility** | Installed and configured. See [Digital Asset Utilities docs](https://docs.digitalasset.com/utilities/mainnet/index.html) | | **Keycloak credentials** | Host, realm, client ID, username, and password for your environment | | **Party ID** | Your Canton Party ID, obtained during onboarding | *** ## 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](https://github.com/DLC-link/cbtc-lib) * **Current version:** v0.3.0 * **Licence:** *Check repository* ### Add to your project Add `cbtc-lib` to your `Cargo.toml`: ```toml [dependencies] cbtc = { git = "ssh://git@github.com/DLC-link/cbtc-lib.git", tag = "v0.3.0" } ``` > 📌 **Pin your version.** Always reference a specific tag (e.g. `v0.3.0`) 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 | *** ## 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](https://github.com/DLC-link/canton-lib) * **Crates:** `keycloak`, `ledger`, `registry`, `common` (all at v0.3.0) ### Add to your project Add the canton-lib crates you need to your `Cargo.toml`: ```toml [dependencies] keycloak = { git = "ssh://git@github.com/DLC-link/canton-lib.git", tag = "v0.3.0" } ledger = { git = "ssh://git@github.com/DLC-link/canton-lib.git", tag = "v0.3.0" } registry = { git = "ssh://git@github.com/DLC-link/canton-lib.git", tag = "v0.3.0" } common = { git = "ssh://git@github.com/DLC-link/canton-lib.git", tag = "v0.3.0" } ``` The `keycloak` crate provides authentication helpers used across all CBTC operations. **Password-grant authentication** (for user-facing flows): ```rust 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): ```rust 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 (v0.3.0):** [github.com/DLC-link/cbtc-lib/tree/v0.3.0/cbtc-dars](https://github.com/DLC-link/cbtc-lib/tree/v0.3.0/cbtc-dars) 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](https://docs.digitalasset.com/canton) for details. > 💡 **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](https://docs.bitsafe.finance/developers/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-dev.com/) | [`https://api.utilities.digitalasset-staging.com`](https://api.utilities.digitalasset-staging.com/) | [`https://api.utilities.digitalasset.com`](https://api.utilities.digitalasset.com/) | | `ATTESTOR_URL` | [`https://devnet.dlc.link/attestor-1`](https://devnet.dlc.link/attestor-1) | [`https://testnet.dlc.link/attestor-1`](https://testnet.dlc.link/attestor-1) | [`https://mainnet.dlc.link/attestor-1`](https://mainnet.dlc.link/attestor-1) | | `DECENTRALIZED_PARTY_ID` | *Provided during onboarding* | *Provided during onboarding* | *Provided during onboarding* | ### Example.env file ```bash # Environment (choose one: devnet, testnet, mainnet) REGISTRY_URL="https://api.utilities.digitalasset-staging.com" ATTESTOR_URL="https://testnet.dlc.link/attestor-1" 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" ``` *** ## Migration Guide: December 2025 Restructure In December 2025, `cbtc-lib` underwent a major restructure. If you were using an earlier version, you will need to update your imports and module paths. ### What changed * Module hierarchy was reorganised for clarity * Some function signatures were updated * `canton-lib` was extracted as a separate dependency ### How to migrate 1. Update your `Cargo.toml` to pin to `v0.3.0` 2. Update all `use` statements to match the new module paths (see the module table above) 3. Review the [cleanup PR](https://github.com/DLC-link/cbtc-lib/pull/11) for a full diff of changes > ⚠️ **Breaking change.** Code written against pre-restructure `cbtc-lib` will not compile against v0.3.0 without import updates. There are no runtime behaviour changes, only module paths and function signatures moved. *** ## Verify Your Installation Run this minimal check to confirm everything is wired up: ```rust use keycloak::login::{password, password_url, PasswordParams}; use cbtc::active_contracts; #[tokio::main] async fn main() -> Result<(), Box> { // 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](https://docs.bitsafe.finance/developers/cbtc-quick-start) to mint your first CBTC. *** ## Next Steps * **Quick Start:** Mint your first wrapped Bitcoin in 15 minutes * **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 *** --- # Agent Instructions: 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: ``` GET https://docs.bitsafe.finance/developers/sdk-setup-and-installation.md?ask= ``` The question should be specific, self-contained, and written in natural language. 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.