> 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/developers/sdk-setup-and-installation.md). # 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 | | **Minter credential** | Only required to **mint or burn** CBTC. Issued to your party by the CBTC registrar; request one via . 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](https://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`: ```toml [dependencies] cbtc = { git = "ssh://git@github.com/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](https://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`: ```toml [dependencies] keycloak = { git = "ssh://git@github.com/DLC-link/canton-lib.git", tag = "v0.6.1" } ledger = { git = "ssh://git@github.com/DLC-link/canton-lib.git", tag = "v0.6.1" } registry = { git = "ssh://git@github.com/DLC-link/canton-lib.git", tag = "v0.6.1" } common = { git = "ssh://git@github.com/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): ```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:** [github.com/DLC-link/cbtc-lib/tree/v0.6.4/cbtc-dars](https://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](https://docs.digitalasset.com/canton) 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](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/) | | `BITSAFE_API_URL` | [`https://api.devnet.bitsafe.finance`](https://api.devnet.bitsafe.finance) | [`https://api.testnet.bitsafe.finance`](https://api.testnet.bitsafe.finance) | [`https://api.mainnet.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 ```bash # 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: ```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**](https://docs.bitsafe.finance/developers/cbtc-quick-start) - Mint your first wrapped Bitcoin in 15 minutes * [**CBTC Minting and Burning**](https://docs.bitsafe.finance/developers/cbtc-minting-and-burning) - The mint and burn lifecycle in depth, with error handling and recovery patterns * [**API Reference**](https://docs.bitsafe.finance/developers/cbtc-api-reference) - Full Canton Ledger API endpoint documentation * [**Instrument ID Management**](https://docs.bitsafe.finance/developers/instrument-id-management) - How to fetch and poll for the latest CBTC Instrument IDs * [**Authentication Guide**](https://docs.bitsafe.finance/developers/cbtc-authentication) - Detailed Keycloak setup and Auth0 community example * [**Testnet Guide**](https://docs.bitsafe.finance/developers/cbtc-testnet-guide) - Get testnet CBTC from the faucet and test before going live *** --- # 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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.bitsafe.finance/developers/sdk-setup-and-installation.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.