# BitSafe documentation, full text # Home URL: https://docs.bitsafe.finance/ ### Build and operate decentralized infrastructure on Canton Network BitSafe documentation helps institutions, developers, and node operators use and integrate BitSafe assets and Decentralization Manager. ### Explore products #### Assets Guides for minting, redeeming, transferring, and integrating BitSafe assets on Canton. * [CBTC: Bitcoin on Canton](https://docs.bitsafe.finance/cbtc) * [BETH: Ether on Canton](https://docs.bitsafe.finance/beth) * [CHYPE: HYPE on Canton](https://docs.bitsafe.finance/chype) * [Asset Faucet](https://faucet.bitsafe.finance/) The Asset Faucet lists the assets and networks available for test-token requests. #### Decentralization Manager Create and operate Decentralized Parties and governed applications across independent Canton nodes with BitSafe's open-source multi-sig framework. * [Decentralization Manager overview](https://docs.bitsafe.finance/decentralization-manager) * [Decentralization Manager architecture overview](https://docs.bitsafe.finance/decentralization-manager/concepts-and-development/architecture-overview) ### Trust and support * [Security and trust index](https://docs.bitsafe.finance/security-and-trust) * [BitSafe documentation glossary](https://docs.bitsafe.finance/glossary) * [Support and developer resources](https://docs.bitsafe.finance/support-and-developer-resources) ### Start here Choose by role or task: [Start here: choose a product or task](/start-here/). ### Building for institutions? Talk to BitSafe --- # Start here URL: https://docs.bitsafe.finance/start-here/ Start with the product or task that matches your immediate goal. Complete a read-only check before you submit a state-changing workflow. ### Choose by goal
I want toStart with
Understand CBTCHow CBTC works
Integrate CBTCCBTC developer Quick Start
Mint, redeem, or transfer CBTCChoose a CBTC path
Evaluate Decentralization ManagerDecentralization Manager overview
Prepare to run Decentralization ManagerDecentralization Manager prerequisites
Create a Decentralized PartyCreate a Decentralized Party
Review security and trust boundariesSecurity and trust index
### Choose by role | Role | Recommended path | | --------------------------- | -------------------------------------------------------------------------------------------------- | | Institution or trading firm | [Start here for institutions and trading firms](/start-here/institutions-and-trading-firms/) | | Application developer | [Start here for developers](/start-here/developers/) | | Node operator | [Start here for node operators](/start-here/node-operators/) | | Security reviewer | [Security and trust index](/security-and-trust/) | ### Evaluating an institutional use case? Talk to BitSafe ### Interested in operating infrastructure? Apply to join the BitSafe Node Operator Network ### Before you continue * Use a supported product release and environment. * Confirm authentication, party rights, and package compatibility. * Do not copy production credentials into commands, documentation, logs, or support requests. * Query authoritative state before you retry an interrupted operation. ### Next step → **Choose your role:** start with [Start here for institutions and trading firms](/start-here/institutions-and-trading-firms/), [Start here for developers](/start-here/developers/), or [Start here for node operators](/start-here/node-operators/). --- # Institutions and trading firms URL: https://docs.bitsafe.finance/start-here/institutions-and-trading-firms/ ### Start with the outcome CBTC is the primary path for institutions and trading firms that need Bitcoin on Canton. Decentralization Manager is the path for organizations that want to run governed and co-validated applications across independent Canton nodes. ### Evaluate CBTC 1. Read [CBTC overview](/cbtc/). 2. Understand mint, transfer, and redemption in [How CBTC works](/cbtc/how-cbtc-works/). 3. Review [CBTC security](/cbtc/concepts-and-reference/security/) and [CBTC Proof of Reserve](/cbtc/concepts-and-reference/proof-of-reserve/). 4. Choose transfer operations or an approved mint and redemption integration. ### Evaluate Decentralization Manager 1. Read [Decentralization Manager overview](/decentralization-manager/). 2. Review [Decentralization Manager architecture overview](/decentralization-manager/concepts-and-development/architecture-overview/) and [Decentralization Manager governance lifecycle](/decentralization-manager/concepts-and-development/governance-lifecycle/). 3. Choose the approved co-validation model that matches the application's control and hosting requirements. 4. Review [Decentralization Manager production deployment](/decentralization-manager/get-started/production-deployment/) and determine whether your team will self-host or use Decentralization Services. ### Before production Confirm counterparties, operating model, supported versions, access, recovery, support, and internal risk review. Use [CBTC compatibility and release notes](/cbtc/concepts-and-reference/compatibility-and-release-notes/), [Decentralization Manager compatibility, releases, and troubleshooting](/decentralization-manager/operations-and-reference/compatibility-releases-and-troubleshooting/), and the shared [Security and trust index](/security-and-trust/). This documentation describes infrastructure and is not legal, regulatory, or investment advice. ### Evaluating CBTC or a governed Canton application for your organization? ### Talk to BitSafe ### Next step → **Begin the evaluation:** [How CBTC works](/cbtc/how-cbtc-works/). --- # Developers URL: https://docs.bitsafe.finance/start-here/developers/ ### Choose a product Use this page as a developer route selector. Setup steps, commands, API schemas, and troubleshooting remain in the linked product pages. ### Build with CBTC 1. [CBTC environments and prerequisites](/cbtc/get-started/environments-and-prerequisites/). 2. [CBTC developer Quick Start](/developers/cbtc-quick-start/). 3. Choose mint, redeem, transfer, or API work from [Choose a CBTC path](/cbtc/choose-a-cbtc-path/). ### Build with Decentralization Manager 1. [Decentralization Manager prerequisites](/decentralization-manager/get-started/prerequisites/). 2. [Run Decentralization Manager locally](/decentralization-manager/get-started/run-locally/). 3. Continue to [Create a Decentralized Party](/decentralization-manager/get-started/create-a-decentralized-party/), [Decentralization Manager module selection and custom Daml](/decentralization-manager/concepts-and-development/module-selection-and-custom-daml/), or [Decentralization Manager API and workflow reference](/decentralization-manager/operations-and-reference/api-and-workflow-reference/). ### Source repositories * [CBTC library](https://github.com/DLC-link/cbtc-lib) * [Shared Canton library](https://github.com/DLC-link/canton-lib) * [Decentralization Manager](https://github.com/DLC-link/decentralization-manager) Use approved immutable tags or commits. Do not build production instructions from a mutable branch. ### Need institutional integration support? Talk to BitSafe ### Next step → **Pick the first build:** [CBTC developer Quick Start](/developers/cbtc-quick-start/) or [Decentralization Manager prerequisites](/decentralization-manager/get-started/prerequisites/). --- # Node operators URL: https://docs.bitsafe.finance/start-here/node-operators/ **Use this path if you operate Canton infrastructure and will host Decentralization Manager.** This page is a role-specific checklist; the linked guides own configuration and procedures. ### What you own * One independently operated Decentralization Manager instance. * Authenticated access to the Canton Admin and Ledger APIs. * Operator identity, local credentials, persistent state, and backups. * A verified peer-communication endpoint and trusted peer records. * Monitoring, incident response, and coordinated upgrades. ### Operator path
GoalCanonical guide
Evaluate in a controlled environmentRun Decentralization Manager with Docker
Deploy for productionDecentralization Manager production deployment
Configure accessDecentralization Manager authentication and operator roles
Connect independent operatorsConnect Decentralization Manager peers
Join the BitSafe Node Operator NetworkJoin the BitSafe Node Operator Network: Onboarding Guide
Operate packages and contractsDecentralization Manager package and contract operations
Recover or upgradeDecentralization Manager backup, recovery, and mesh upgrades
Review trust boundariesDecentralization Manager security architecture
### Join the BitSafe Node Operator Network Operators who want to be considered for Canton applications that need independent hosts can follow [Join the BitSafe Node Operator Network: Onboarding Guide](/decentralization-manager/get-started/join-the-bitsafe-node-operator-network/). The onboarding path covers: 1. Deploy Decentralization Manager on an existing Canton node. 2. Exchange peer and party details with BitSafe through an approved secure channel. 3. Validate the TestNet connection and basic operational readiness. 4. Repeat the approved peer exchange on MainNet. 5. Complete registry activation and become eligible for application matching. Commercial terms are agreed between each application and its participating operators. BitSafe may coordinate the operator group or act as application administrator. Operator earnings are not guaranteed. ### Want to join the operator network? Apply to join the BitSafe Node Operator Network ### Production readiness * [ ] Pin an approved release and immutable image digest. * [ ] Disable insecure mode and enforce operator roles. * [ ] Restrict Canton and peer network paths. * [ ] Preserve and protect the Noise identity, database, credentials, and DARs. * [ ] Verify peer records through an authenticated channel. * [ ] Test backup, restore, monitoring, incident response, and mesh upgrades. * [ ] Complete one low-risk workflow and verify the resulting Canton state. ### Scope boundary **Attestor** is a CBTC-specific role. This page covers Decentralization Manager instances, peers, packages, governance, and recovery. ### Ready to apply? Apply to join the BitSafe Node Operator Network ### Next step → **Prepare the production environment:** [Decentralization Manager production deployment ](/decentralization-manager/get-started/production-deployment/). --- # BitSafe Documentation URL: https://docs.bitsafe.finance/readme-1/ **Build with Bitcoin and decentralized applications on Canton Network.** BitSafe documentation has two core product paths: * **CBTC** for teams integrating Bitcoin into trading, custody, and application workflows on Canton Network * **Decentralization Manager** for builders creating Decentralized Parties and governed applications on Canton Network **Choose your path** * **Build with Decentralization Manager** Launch governed applications, configure operators, and manage Decentralized Parties * **Integrate CBTC** Mint, hold, transfer, and integrate CBTC into applications and services * **Trade CBTC** Explore venue access, onboarding, and trading workflows * **Understand the architecture** Learn how governance, privacy, and the security model fit together
Cover image
Decentralization ManagerGovern on-chain actions with Decentralized Parties. Architecture, setup, operations, and API reference.decentralization-managerDecMan.png
CBTCUnderstand CBTC's architecture, security model, operational guides, and user flows.cbtcCBTC.png
Trading FirmsEvaluate and onboard to CBTC. Strategies, venues, wallets, and compliance for trading firms.trading-firmsTrading.png
DevelopersBuild apps, wallets, and DeFi protocols with CBTC on Canton. API reference, SDKs, and guides.developersDev.png
*** ## Quick Links **Product Suite** * [System Overview](/product-suite/assets/cbtc/system-overview/cbtc-token-standard-info/) - How CBTC works on Canton * [Security Model](/product-suite/assets/cbtc/security-model/a-deep-dive-into-frost/) - FROST signatures and decentralized custody * [Operational Guides](/product-suite/assets/cbtc/operational-guides/) - Minting, price feeds, and swaps * [User Flow](/product-suite/assets/cbtc/user-flow/) - End-to-end transaction lifecycle **Trading Firms** * [Why CBTC for Trading Firms](/trading-firms/why-cbtc-for-trading-firms/) - Canton's edge for traders * [Prop Desk Playbook](/trading-firms/prop-desk-playbook/) - Rewards, strategies, and compliance * [Getting Started](/trading-firms/getting-started-venues-wallets-and-cbtc-acquisition/) - Venues, wallets, and CBTC acquisition * [Onboarding Checklist](/trading-firms/onboarding-checklist-from-signup-to-first-trade/) - From signup to first trade **Developers** * [Quick Start](/developers/cbtc-quick-start/) - Mint your first CBTC in 15 minutes * [API Reference](/developers/cbtc-api-reference/) - Canton Ledger API endpoints * [SDK Setup](/developers/sdk-setup-and-installation/) - Install cbtc-lib and configure your environment * [Minting and Burning](/developers/cbtc-minting-and-burning/) - Convert BTC to CBTC with code * [Decentralization Manager](/product-suite/decentralization-manager/) - Govern on-chain actions with Decentralized Parties * [CBTC Faucet](https://faucet.bitsafe.finance/) **Decentralization Manager** * [Architecture Overview](https://docs.bitsafe.finance/product-suite/decentralization-manager/architecture-overview) - System architecture, core concepts, and communication protocol * [User Guide](https://docs.bitsafe.finance/product-suite/decentralization-manager/user-guide) - Walkthrough of the web UI for day-to-day operations * [Custom DAML Templates](https://docs.bitsafe.finance/product-suite/decentralization-manager/custom-daml-templates) - Authoring and deploying your own governance templates * [Use Cases](https://docs.bitsafe.finance/product-suite/decentralization-manager/use-cases) - Vault governance, FAR rewards, multi-sig wallet, and utility service * [Contributing Guide](https://docs.bitsafe.finance/product-suite/decentralization-manager/contributing-guide) - Development setup, standards, and the PR process *** > **Not sure where to start?** Browse the [Product Suite](/product-suite/assets/cbtc/) for a high-level understanding of CBTC, or check the [FAQs](/faqs/) for quick answers. For trading firm enquiries, contact [sales@bitsafe.finance](mailto:sales@bitsafe.finance). --- # Product Suite URL: https://docs.bitsafe.finance/product-suite/ BitSafe builds infrastructure for institutions and developers operating on Canton Network. ## CBTC CBTC is a 1:1 wrapped Bitcoin token on Canton Network, enabling private, institutional-grade yield, trading, and settlement with decentralized management and transparent custody. ## Decentralization Manager Decentralization Manager is the open-source framework for creating and managing Decentralized Parties and governed applications. --- # Assets URL: https://docs.bitsafe.finance/product-suite/assets/ BitSafe develops decentralized assets for the Canton Network using threshold custody and a decentralized network of Attestor nodes. Each asset is a 1:1 wrapped token, issued by a decentralized party on Canton and held non-custodially by the user. * [CBTC](/developers/cbtc-overview/)**:** wrapped Bitcoin, secured by FROST threshold signatures. * [BETH](/product-suite/assets/beth/)**:** wrapped native ETH, backed by ETH held in a dedicated decentralized bridge. --- # CBTC URL: https://docs.bitsafe.finance/product-suite/assets/cbtc/ CBTC is a 1:1 wrapped Bitcoin token by BitSafe, designed for secure and decentralized bridging to the Canton Network. Each CBTC is CIP-56 compliant, and is fully backed by Bitcoin held in a secure, decentralized custody system powered by FROST (Flexible Round-Optimized Schnorr Threshold Signatures). The wrapped token is issued by a decentralized threshold of parties on Canton, and is held non-custodially by the user. This eliminates the risks associated with centralized custodians and traditional bridge architectures. ## How the Bitcoin Bridge works The reserve capital for CBTC is held in a network of secure Bitcoin wallets, co-controlled by a decentralized network of Attestor nodes. This is not a traditional multisig wallet, but rather a sophisticated threshold signature operation. Here's how it works: **Decentralized Custody:** Instead of a single entity holding the private keys, the authority to spend the Bitcoin is distributed among a network of trusted, institutional-grade Attestor nodes. Each node holds a share of the private key, but no single node ever has access to the full key. **Threshold Signatures with FROST:** To authorize a withdrawal, a threshold of Attestor nodes must collaboratively sign the transaction using the FROST protocol. This process generates a single, standard Schnorr signature that is indistinguishable from a regular Bitcoin transaction on-chain, enhancing privacy and reducing transaction fees. **Taproot Native:** Using Bitcoin's Taproot upgrade allows any Bitcoin wallet that can send to a Taproot address (P2TR) to be used to deposit BTC and mint CBTC. This model ensures that no single party - not even BitSafe - can unilaterally move the funds. The security of the system is based on the honest majority assumption of the Attestor network, which is composed of highly reputable and financially incentivized participants. ## Dual Network Security BitSafe Attestors don't just manage Bitcoin - they also validate transactions on Canton. This means both your Bitcoin deposits and CBTC token creation are protected by the same trusted network, creating seamless security across both blockchains. ## Why Canton? The CBTC-Canton integration advances institutional Bitcoin adoption by enabling scalable, privacy-preserving margin flows for structured products and derivatives. Canton has the following features: * Configurable on-chain privacy settings: Flows are visible only to the counterparties who need to see them * Built for lending, trading, and settlements ## Learn More **For Trading Firms:** Strategies, onboarding, venue selection, and reward mechanics - see the [Trading Firms](/trading-firms/) section. **For Developers:** API reference, SDK setup, minting/burning workflows, and security deep dive - see the [Developers](/developers/) section. **Security:** For a detailed look at FROST threshold signatures and the Attestor network, see [A Deep-dive into FROST](/product-suite/assets/cbtc/security-model/a-deep-dive-into-frost/) or the [Security Deep Dive](/developers/security-deep-dive/) in the Developers section. **FAQs:** Common questions are answered in the [Trading Firms FAQ](/trading-firms/faq-for-trading-firms/) and the [general FAQs](/faqs/). **Glossary and Resources:** See the [Trading Firms Glossary](/trading-firms/glossary/) and [Resources](/trading-firms/resources/), or the [Developer Resources](/developers/resources/). Help & feedback - reach us at [sales@bitsafe.finance](mailto:sales@bitsafe.finance) with questions. --- # System Overview URL: https://docs.bitsafe.finance/product-suite/assets/cbtc/system-overview/ ## Architecture at a Glance The CBTC system bridges the Bitcoin Layer‑1 UTXO model to Canton’s Daml‑based smart‑contract network. It operates through a coordinated, decentralized process to ensure every Bitcoin deposit is securely verified before minting CBTC The bridge architecture consists of: 1. **Bitcoin Layer** - Bitcoin transactions are monitored and verified with required confirmations (currently 6) 1. **Attestor Network** - A decentralized network of Attestors monitor and manage Bitcoin deposit/withdrawal transactions, and translate them via a governance module on Canton to validate and execute actions 1. **Canton Asset Layer** - Daml contracts that mint and burn CBTC tokens, but only after a threshold of Attestor nodes contribute their Canton signatures to the contract execution. No CBTC can be minted or burned without this decentralized approval process For the full technical specification, see the CBTC Token Standard Info ## Core Actors & Roles **Actor** **Responsibilities** **Coordinator** Executes periodic checks every 60-120 seconds, monitors deposit accounts, constructs Bitcoin transactions, and submits governance actions **Attestors** Independent nodes that verify deposits/withdrawals and submit confirmations via Canton's governance module. Every important action requires group approval **Minter** Create deposit accounts, send Bitcoin to generated addresses, initiate withdrawals, and hold CBTC tokens ## Trust & Threat Model The CBTC system relies on a decentralized network of Attestors who must coordinate via a governance module on Canton to validate and execute actions, and a group threshold signing process on the Bitcoin L1. Every important action requires group approval. This shared decision-making keeps CBTC decentralized, reliable, and secure Because Canton provides deterministic finalityarrow-up-right, once a mint or burn is executed its state transition is irrevocably committed, removing the roll‑back risk that probabilistic Layer‑1s face This ensures that no single party, including the Coordinator, can unilaterally mint CBTC or withdraw Bitcoin ## On-Ledger Governance Flow The CBTC system relies on a decentralized network of Attestors who must coordinate via a governance module on Canton to validate and execute actions. The governance process works as follows: * For actions like **ConfirmDepositAction** (for minting) or **ArchiveWithdrawRequest** (for withdrawal finalization), each Attestor must submit their confirmation signature independently * Each attestor member submits its signed confirmation message, and once a threshold of signatures has been reached on the contract, the Coordinator executes the action --- # CBTC Token Standard Info URL: https://docs.bitsafe.finance/product-suite/assets/cbtc/system-overview/cbtc-token-standard-info/ These values and the registry URLs are what allows any token standard compliant tool to integrate with CBTC. API Reference: Token Standard API Docs Requirements: CIP-56 compliant. No special requirements for holding CBTC. ## Devnet Coordinator URL: [https://devnet.dlc.link/attestor-2](https://devnet.dlc.link/attestor-2) ## Testnet Coordinator URL: [https://testnet.dlc.link/attestor-1](https://testnet.dlc.link/attestor-1) ## Mainnet Coordinator URL: [https://mainnet.dlc.link/attestor-1](https://mainnet.dlc.link/attestor-1) --- # User Flow URL: https://docs.bitsafe.finance/product-suite/assets/cbtc/user-flow/ User Flow Mint Flow (Deposit BTC → Mint CBTC) High‑Level Narrative Minting converts BTC into CBTC on Canton in six coordinated steps. From the user’s point of view the whole journey feels like a normal on‑chain deposit; the heavy lifting - vault creation, threshold signing, and contract issuance - happens behind the scenes. Step‑by‑Step Walk‑through 1. **Authentication** - Users start by logging into their Canton account, establishing their on-chain identity for the deposit 2. **Request deposit address** - The system generates a unique Bitcoin address tied to the user's account. Power users can request multiple addresses for operational convenience, though a single address works for unlimited deposits. 3. **Send Bitcoin** - Users initiate a Bitcoin transaction to the provided address using any standard wallet - no special software or complex procedures required. 4. **Automated monitoring** - The bridge continuously scans the Bitcoin network for incoming transactions. Once your deposit reaches 6 confirmations (roughly 60 minutes), it enters the verification queue. 5. **Decentralized verification** - Multiple independent Attestor nodes review the confirmed transaction, each submitting their approval through Canton's governance system. This distributed verification prevents any single party from controlling the minting process. 6. **CBTC issuance** - When a threshold of Attestor approvals are gathered, the next periodic system check (every 60-120 seconds) triggers the minting of equivalent CBTC via the decentralized party model and the governance model. Timing & Finality The minting and withdrawal processes are automated, requiring no manual coordination. Burn Flow (Redeem CBTC → BTC) High‑Level Narrative Redeeming CBTC reverses the bridging process, unlocking native Bitcoin that backs your CBTC token balance. From your perspective, it works like any crypto withdrawal - specify an amount and destination, then wait for Bitcoin to arrive in your wallet. The system handles the coordination between burning your CBTC tokens and releasing the underlying Bitcoin through decentralized Attestor approval. Step‑by‑Step Walk‑through 1. **Authentication** - Sign into your Canton account to initiate the withdrawal process 2. **Set up withdrawal destinations** - Configure one or multiple Bitcoin addresses where you want to receive funds - your hardware wallet, exchange account, or any Bitcoin address you control. These addresses are stored for future withdrawals, making repeat transactions one-click simple. 3. **Submit withdrawal request** - Select how much CBTC to redeem and choose your destination address. Your CBTC tokens are immediately burned on Canton, ensuring they can't be double-spent, while your withdrawal enters the processing queue. 4. **Automated processing** - The system detects your pending withdrawal and constructs a Bitcoin transaction to your specified address. Multiple Attestors independently review and approve the transaction through Canton's governance system to burn the CBTC on Canton once the required threshold is reached. 5. **Bitcoin delivery** - Once Attestor approvals also reach the required threshold on the BTC L1, the fully-signed transaction is broadcast to the Bitcoin network. After standard confirmations (typically 6), your Bitcoin arrives at the destination address. Reliability & Safeguards The withdrawal system includes multiple failure-resistant mechanisms: * **Automatic retry logic** - If a Bitcoin transaction fails to broadcast initially, the system automatically detects the failure during subsequent checks and rebroadcasts using stored transaction data * **Idempotent operations** - Each withdrawal generates a unique transaction ID that prevents accidental double-spending, even if network issues cause retry attempts * **Distributed verification** - No single Attestor can block or manipulate withdrawals; the threshold approval system ensures continued operation even with some nodes offline --- # Security Model URL: https://docs.bitsafe.finance/product-suite/assets/cbtc/security-model/ ## FROST Threshold Signatures CBTC uses FROST (Flexible Round-Optimized Schnorr Threshold Signatures) to secure Bitcoin deposits through a decentralized network of Attestor nodes. Unlike traditional on-chain multisig which requires multiple signatures and public keys, CBTC uses standard Bitcoin transactions with a single aggregated signature that is indistinguishable from regular Bitcoin transactions. This approach is compatible with any wallet that supports Taproot addresses and results in smaller transaction sizes, lower fees, and enhanced privacy compared to conventional multisig operations. ## Canton-Side Operations Each BitSafe Attestor that helps sign Bitcoin transactions also operates a node on the Canton network. When creating new CBTC tokens, these Attestors must each approve the minting by submitting their agreement to the CBTC smart contract. Only when enough Attestors agree (reaching the threshold) are the new CBTC tokens actually minted. ## Canton Token Standard Compliance CBTC uses the Canton registry utility and will adopt the universal token standard when viable ## Distributed Infrastructure CBTC's security foundation rests on a carefully selected network of institutional-grade operators. The system employs 9 pre-screened external node operators (including established providers like P2P and Everstake) alongside 1 BitSafe-operated node. Each operator maintains over $1 billion in AUM (Assets Under Management), ensuring they have both the technical expertise and financial incentives to maintain system integrity. These operators run both Bitcoin and Canton nodes. ## Cryptographic Address Generation CBTC employs sophisticated cryptographic techniques to ensure each user receives a unique, secure Bitcoin deposit address. Each **DepositAccount** (DA) on Canton deterministically maps to a unique Bitcoin deposit address through a multi-step cryptographic process involving public key derivation and Taproot script construction. **Two-Stage Derivation Process:** 1. **Entropy Generation:** The system starts with a fixed unspendable public key as the cryptographic foundation. Each DA's unique identifier undergoes SHA-256 hashing to generate entropy, which then serves as the chain code in the key derivation process. This creates a deterministic extended public key (xpub) that's unique to each deposit account. 1. **Taproot Integration:** The derived xpub combines with a fixed single-key script to construct a Taproot output with script-path spending enabled. This results in a valid P2TR (Pay-to-Taproot) Bitcoin address that's fully determined by the DA's identifier and can only be spent using the Attestors' group private key. ## Transaction Validation Rules The system employs strict UTXO selection criteria to prevent double-spending and ensure proper transaction ordering: **For Deposit Processing**: A UTXO qualifies for minting only if it received 6 confirmations after the DepositAccount's recorded block_height, ensuring new deposits are processed in chronological order. **For Withdrawal Processing**: A UTXO becomes eligible for spending only if it was confirmed with 6 confirmations before or at the DepositAccount's block_height, guaranteeing that only properly secured funds can be withdrawn. This dual-criteria approach creates a clear separation between "available for withdrawal" and "pending deposit" funds, preventing race conditions and ensuring the integrity of the 1:1 backing mechanism. --- # A Deep-dive into FROST URL: https://docs.bitsafe.finance/product-suite/assets/cbtc/security-model/a-deep-dive-into-frost/ Flexible Round-Optimized Schnorr Threshold (FROST) underpins the security and decentralization of the Bitcoin side of BitSafe CBTC. As a threshold signature scheme, FROST enables a group of participants to collectively generate a single Schnorr signature, without any single participant ever having access to the full private key. This document provides a comprehensive technical overview of FROST, its integration with CBTC, and the significant advantages it offers for institutional Bitcoin custody. ## 1. Understanding FROST ### 1.1. What is FROST? FROST is a threshold signature scheme that allows for the creation of Schnorr signatures from a distributed set of key shares. ### 1.2. Why FROST for CBTC? The selection of FROST for decentralized control of the BTC in our on-chain Bitcoin network vault was a deliberate choice. ## 2. How FROST Works ### 2.1. Key Generation FROST supports two primary methods: Trusted Dealer Generation and Distributed Key Generation (DKG). ### 2.2. The Signing Process The FROST signing process is a two-round protocol coordinated by a designated entity. ### 2.3. Signature Aggregation and Verification Once the Coordinator has received a threshold of valid signature shares, it can aggregate them into a single, final Schnorr signature. ## 3. Advanced Features and Security ### 3.1. Share Resharing and Revocation One of the most powerful features of FROST is the ability to perform Verifiable Secret Resharing (VSR). ### 3.2. Security Model The security of FROST is based on strong cryptographic assumptions. ## 4. FROST in CBTC: Implementation Details ### 4.1. Attestor Network Architecture The CBTC system operates through a decentralized network of institutional-grade Attestors. ### 4.2. Coordinator and Governance Integration The system employs a Coordinator that executes periodic checks every 60-120 seconds. ### 4.3. Threshold Signing Process FROST enables the Attestor network to collectively authorize Bitcoin transactions. ### 4.4. Dual-Network Security Model The CBTC system security relies on coordination between two networks. ## 5. More Reading RFC 9591, Zcash Foundation FROST docs, Cryptology ePrint Archive Report 2020/852 --- # Operational Guides URL: https://docs.bitsafe.finance/product-suite/assets/cbtc/operational-guides/ The guides below provide high-level overviews for first-time users. Detailed technical implementation guides will be available as separate documents upon launch. ## Wallet Requirements **Bitcoin side:** No special setup required - any wallet that can send BTC to a Taproot address (e.g., Sparrow, Ledger Live, BlueWallet) will work when you deposit into the bridge. **For Canton:** Yes. After your Bitcoin is bridged, CBTC lives on Canton, so you'll need a wallet that understands Canton tokens. Today that list is short - the Canton CLI is fully supported, with additional wallets coming as the ecosystem progresses ## Run a Minter Application A Minter Application enables institutions to offer CBTC deposit and withdrawal services to their users. As a Minter, you'll coordinate between Bitcoin deposits and Canton token issuance. **Prerequisites** * Minter Credential (Get yours herearrow-up-right) * Bitcoin infrastructure for monitoring deposits and managing withdrawals * Canton participant node for interacting with CBTC contracts * Integration with the decentralized Attestor network for transaction approvals **High-Level Process** Running a Minter Application involves monitoring Bitcoin addresses for user deposits, coordinating with Attestors for verification, and triggering CBTC minting on Canton. The bridge also handles the reverse process for withdrawals, burning CBTC tokens and facilitating Bitcoin payouts. **Operational Considerations** * Monitor Bitcoin network for deposit confirmations (6 blocks required) * Coordinate with the governance module for Attestor approvals * Manage periodic checks every 60-120 seconds for processing transactions ## Run an Attestor Node Attestor Nodes form the decentralized security backbone of CBTC, independently verifying all mint and burn operations through Canton's governance system **Prerequisites:** * Technical infrastructure capable of running both Bitcoin and Canton nodes **High-Level Process** Attestors monitor Bitcoin transactions, verify deposit and withdrawal requests, and submit confirmations through Canton's governance module. Each important action requires group approval, ensuring no single party can unilaterally control minting or burning. **Operational Responsibilities** * Independent verification of Bitcoin transactions reaching 6 confirmations * Submission of **ConfirmDepositAction** for mints and **ArchiveWithdrawRequest** for burns * Participation in the threshold approval process with other Attestors * Maintenance of both Bitcoin monitoring and Canton governance infrastructure **Note:** Almost all of these responsibilities are automated with the only exception being governance (adding/removing nodes) which requires coordination between operators ## Spin Up a Canton Node/Instance Running a Canton Node allows institutions to participate directly in the CBTC ecosystem, whether as holders, minters, or service providers **Prerequisites:** * Appropriate CBTC credential (Holder or Minter) * Technical infrastructure for running Canton participant nodes * Integration capabilities for connecting to the broader Canton network **High-Level Setup** Canton nodes participate in the privacy-preserving, deterministic ledger that hosts CBTC contracts. Your node will process transactions, maintain contract state, and interact with other participants through Canton's encrypted messaging system. **Key Components** * Participant node for transaction processing and contract interaction * Connection to Canton's sync domain for coordinated state updates * Integration with CBTC governance contracts for credential verification * API endpoints for application integration (if providing services to end users) --- # Minting CBTC URL: https://docs.bitsafe.finance/product-suite/assets/cbtc/operational-guides/minting-cbtc/ This guide covers how to mint CBTC (Canton Bitcoin) by depositing native Bitcoin. CBTC is minted via the BitSafe Attestor Network, a decentralized network that monitors Bitcoin deposits and automatically mints CBTC to your Canton party. You do not need to run an attestor yourself. ## Integration Options You can mint CBTC either through the BitSafe web application (no code required) or programmatically using the cbtc-lib Rust library. * **Web Application:** Use the BitSafe app to initiate deposits and monitor minting status * **cbtc-lib (Rust):** A library of helper functions for minting, burning, and transferring CBTC on Canton. See [cbtc-lib](https://github.com/DLC-link/cbtc-lib) For full installation instructions, environment configuration, and code examples, see the [cbtc-lib README on GitHub](https://github.com/DLC-link/cbtc-lib). ## Prerequisites * A Bitcoin wallet that supports Taproot (P2TR) addresses * A Canton Network participant node * Sufficient BTC for the deposit plus network fees * A valid credential issued by your account manager * For programmatic minting: the CBTC Minting App DAR files installed on your participant node. See the cbtc-lib Installation Guide ## Minting Flow 1. **Step 1: Create a Deposit Account** — Use the BitSafe app or `cbtc-lib`'s `mint_redeem::mint::create_deposit_account()` to create a deposit account. You will receive a unique BTC deposit address (Taproot/P2TR). 2. **Step 2: Send Bitcoin** — Send BTC to the provided deposit address from your Bitcoin wallet. 3. **Step 3: Wait for Confirmations** — The BitSafe Attestor Network monitors your deposit address and waits for 6+ Bitcoin block confirmations. 4. **Step 4: Automatic Minting** — Once confirmations are received, the attestor network verifies the deposit and automatically mints the equivalent CBTC to your Canton party. No action is required from you at this step. 5. **Step 5: Verify Balance** — Check your CBTC balance on your Canton participant node. ## Environment Configuration Configure your environment to point to the correct BitSafe API: | Environment | `BITSAFE_API_URL` | | ----------- | ------------------------------------- | | Devnet | `https://api.devnet.bitsafe.finance` | | Testnet | `https://api.testnet.bitsafe.finance` | | Mainnet | `https://api.mainnet.bitsafe.finance` | ## Developer Resources * [cbtc-lib GitHub Repository](https://github.com/DLC-link/cbtc-lib) * [CBTC Quick Start Guide](/developers/cbtc-quick-start/) * [CBTC Minting and Burning (Developer Reference)](/developers/cbtc-minting-and-burning/) ## Important Notes * Each CBTC is backed 1:1 by Bitcoin held in decentralized custody * The minting process typically completes within minutes after 6 Bitcoin confirmations * You do not need to run an attestor. The BitSafe Attestor Network handles all verification and minting automatically * Deposits are subject to per-account limits - 0.0001 BTC minimum and 5 BTC maximum by default, adjustable on request. See [CBTC Minting and Burning](/developers/cbtc-minting-and-burning/) for details --- # Integrating BTC-USD Price Feed for CBTC URL: https://docs.bitsafe.finance/product-suite/assets/cbtc/operational-guides/integrating-btc-usd-price-feed-for-cbtc/ This guide explains how to integrate the BTC-USD price feed for CBTC applications on the Canton Network. ## Overview Accurate and reliable price data is essential for DeFi applications using CBTC. This guide covers how to access and integrate the BTC-USD price feed within your Canton applications. CBTC also has a Chainlink Proof of Reserve (CL PoR) feed for on-chain reserve verification: [https://data.chain.link/streams/cbtc-por-nav-datalink](https://data.chain.link/streams/cbtc-por-nav-datalink) ## Price Feed Architecture The BTC-USD price feed for CBTC is designed to provide real-time, tamper-resistant pricing data that can be consumed by smart contracts and applications on the Canton Network. ## Integration Steps ### Step 1: Access the Price Feed Connect to the price feed endpoint to receive real-time BTC-USD pricing data. ### Step 2: Validate the Data Always validate the freshness and integrity of price data before using it in critical operations. ### Step 3: Implement in Your Application Use the price feed data in your Canton application for operations such as collateral valuation, liquidation thresholds, and trading. ## Best Practices * Always check the timestamp of price data to ensure freshness * Implement fallback mechanisms in case of feed disruptions * Use multiple price sources for critical operations --- # Swap BTC to CBTC on Bron URL: https://docs.bitsafe.finance/product-suite/assets/cbtc/operational-guides/swap-btc-to-cbtc-on-bron/ This guide walks you through swapping BTC to CBTC using the Bron platform. ## Overview Bron provides a streamlined interface for swapping Bitcoin (BTC) to CBTC on the Canton Network. This guide covers the end-to-end process. ## Prerequisites * A Bitcoin wallet with BTC * A Canton Network wallet for receiving CBTC * Access to the Bron platform ## Swap Process ### Step 1: Connect Your Wallets Connect both your Bitcoin wallet and Canton wallet to the Bron platform. ### Step 2: Select the Swap Pair Select BTC to CBTC as your swap pair. The platform will display the current exchange rate and any applicable fees. ### Step 3: Enter the Amount Enter the amount of BTC you wish to swap to CBTC. ### Step 4: Review and Confirm Review the transaction details including the amount, fees, and estimated completion time. Confirm the swap. ### Step 5: Complete the Transaction Send the BTC to the provided address. Once confirmed on the Bitcoin network, your CBTC will be minted and sent to your Canton wallet. ## Fees and Timing * Swap fees are displayed before confirmation * Processing time depends on Bitcoin network confirmation speed * CBTC is minted after sufficient Bitcoin confirmations --- # Glossary URL: https://docs.bitsafe.finance/product-suite/assets/cbtc/glossary/ **Attestor** - Independent nodes that monitor Bitcoin, verify deposits and burns, and participate in the governance process to approve transactions. **CBTC** - A 1:1 wrapped Bitcoin token built for secure trading and bridging on Canton. **Burn** - The process of destroying CBTC tokens on Canton to initiate Bitcoin withdrawal. **Coordinator** - The service that executes periodic checks, monitors deposits, and coordinates with Attestors. **DepositAccount (DA)** - A Canton contract template that represents a deposit account, with each DA having a unique ID that deterministically maps to a Bitcoin deposit address. **Mint** - The process of creating new CBTC tokens on Canton after confirmed Bitcoin deposits. **Periodic Check (PC)** - A recurring process executed by the Coordinator every 60 to 120 seconds to trigger actions based on Bitcoin and Canton data. **WithdrawAccount (WA)** - A Canton contract template representing a withdrawal account that stores a user-defined destination Bitcoin address. **WithdrawRequest (WDR)** - A Canton contract template instantiated during withdrawal processing, containing the withdrawal amount, Bitcoin transaction ID, and destination address. --- # Future Plans URL: https://docs.bitsafe.finance/product-suite/assets/cbtc/future-plans/ The system has been designed to support future enhancements while maintaining the core mint-burn functionality described in this documentation. Following are some ways to increase the functionality of CBTC: * **Node operator rewards:** As a validator securing CBTC, you'll earn additional rewards from minting activity * **Customer minting:** You can potentially mint CBTC on behalf of customers, earning Canton coin rewards to share with them * **Utility-based rewards:** Canton is shifting toward rewarding apps that create actual trading and financial activity, which should benefit CBTC holders --- # CBTC FAQs URL: https://docs.bitsafe.finance/product-suite/assets/cbtc/faqs/ # FAQs ### What is CBTC? CBTC is a wrapped Bitcoin (1:1 backed) on the Canton network, designed for institutional use cases. It's built by BitSafe (makers of iBTC) and will support liquidity provision, and integration with derivatives marketplaces (e.g., the Canton-QCP collaboration). It's privacy-enabled and secure, using Schnorr/FROST and Taproot-based signatures along with a decentralized network of Attestors for the bridge. ### Do I need a Canton validator to participate? Yes, you need to have a live validator and a validator address on Canton mainnet to receive credentials ### What are the transaction fees? Current transaction fees are 5 basis points for minting/burning and 3 basis points for transferring/locking/unlocking ### Who operates the CBTC bridge nodes? 9 pre-screened external node operators (e.g., P2P, Everstake) with more than $1B in AUM and 1 BitSafe node, run both Bitcoin and Canton nodes ### Do I need special wallets? **Bitcoin side:** No special setup required - any wallet that can send BTC to a Taproot address (e.g., Sparrow, Ledger Live, BlueWallet) will work when you deposit into the bridge. **For Canton:** Yes. After your Bitcoin is bridged, CBTC lives on Canton, so you’ll need a wallet that understands Canton tokens. Today that list is short - the Canton CLI is fully supported, with additional wallets coming as the ecosystem matures. ### Are there any KYC/KYB requirements? No additional KYC/KYB is required between app creators because acceptance into Canton requires sponsorship by a Supervalidator ### Will running a CBTC Attestor Node make me a custodian of customer assets or allow me to sweep or transact against customer funds? Running an Attestor Node does **NOT** make you a custodian of any CBTC assets Here's what Attestor Nodes actually do: * Verify Bitcoin transactions and CBTC mint/burn operations * Participate in Canton's governance system as a "signing party" * Submit confirmations for deposits and withdrawals through automated processes * Help maintain the decentralized security of the CBTC network What Attestor Nodes do **NOT** do: * Hold or custody any CBTC tokens * Store customer private keys * Control any customer assets **The key distinction:** Attestors verify transactions; they don't custody assets. You can participate in the CBTC rewards system without any of the custodial concerns. ### What future opportunities are available? Following are some of the future opportunities with Canton and CBTC: * **Node operator rewards:** As a validator securing CBTC, you'll earn additional rewards from minting activity * **Customer minting:** You can potentially mint CBTC on behalf of customers, earning Canton coin rewards to share with them * **Utility-based rewards:** Canton is shifting toward rewarding apps that create actual trading and financial activity, which should benefit CBTC holders ### What if I have more questions? Email [sales@bitsafe.finance](mailto:sales@bitsafe.finance) or join the community --- # Audit Reports URL: https://docs.bitsafe.finance/product-suite/assets/cbtc/audit-reports/ * In August 2025, Quantstamp completed a security audit of CBTC's smart contracts on Canton Network. No High severity issues were found. --- # Resources URL: https://docs.bitsafe.finance/product-suite/assets/cbtc/resources/ ## Resources * FROST Whitepaper: [https://eprint.iacr.org/2020/852](https://eprint.iacr.org/2020/852) * Canton Whitepaper: [https://www.canton.network/whitepapers](https://www.canton.network/whitepapers) --- # CBTC Data & Price Feeds URL: https://docs.bitsafe.finance/product-suite/assets/cbtc/cbtc-data-and-price-feeds/ ### Proof of Reserve CBTC is backed 1:1 by Bitcoin, and that backing is verifiable on-chain through the Chainlink Proof of Reserve feed. The feed reports the reserves held against circulating CBTC and can be used for backing verification, monitoring, and risk checks. * Chainlink CBTC PoR / NAV feed: [https://data.chain.link/streams/cbtc-por-nav-datalink](https://data.chain.link/streams/cbtc-por-nav-datalink) ### Price data Kaiko provides a CBTC price feed built on Temple market data (the CBTC-USDCx pair). The pricing is served through Kaiko’s Fair Market Value endpoints available: * On chain, through Kaiko’s [Pull Oracle](https://docs.kaiko.com/on-chain/kaiko-data/kaiko-reference-rates/data-on-ramp/canton-pull-oracle), which provides Kaiko-signed price quotes that can be verified and consumed within Canton workflows: [https://docs.kaiko.com/on-chain/kaiko-data/kaiko-reference-rates/data-on-ramp/canton-pull-oracle](https://docs.kaiko.com/on-chain/kaiko-data/kaiko-reference-rates/data-on-ramp/canton-pull-oracle) * Off chain, through Kaiko’s REST API: [https://docs.kaiko.com/rest-api/analytics-solutions/kaiko-fair-market-value/established-assets](https://docs.kaiko.com/rest-api/analytics-solutions/kaiko-fair-market-value/established-assets)\ To get access to the Kaiko endpoint, reach out to the BitSafe team and we’ll make an introduction to Kaiko directly. ### BTC/USD as a reference price Since CBTC is redeemable 1:1 for Bitcoin, a BTC/USD price feed remains a valid reference for integrations that don't yet need a dedicated CBTC feed. See the existing guide on integrating a BTC/USD price feed for CBTC. --- # BETH URL: https://docs.bitsafe.finance/product-suite/assets/beth/ BETH is a 1:1 wrapped Ethereum token by BitSafe, brought to the Canton Network through a dedicated decentralized bridge. BETH follows the Canton token standard and is designed to be fully backed by native ETH held in the bridge contract on Ethereum. The wrapped token is issued by a decentralized threshold of parties on Canton and is held non-custodially by the user. This reduces the risks associated with centralized custodians and traditional bridge architectures. #### How the Ethereum Bridge works The reserve capital for BETH is held in a dedicated bridge contract on Ethereum. ETH can only leave the bridge with authorization from a decentralized network of Attestor nodes. This is not a traditional multisig wallet, but a threshold signature operation enforced by the bridge itself. Here's how it works: * **Decentralized custody:** Instead of a single entity holding withdrawal authority, the power to release ETH is distributed among a network of trusted, institutional-grade Attestor nodes. Each Attestor signs independently with its own key, and the bridge contract verifies that the required threshold of signatures is present before any payout. * **Bound, replay-proof authorizations:** Each Attestor signature uses the EIP-712 standard and is bound to a specific withdrawal request, destination, amount, Ethereum chain, and bridge contract. A signature cannot be reused for another payout or another deployment. * **Native ETH:** BETH wraps native ETH directly, not WETH or a staking derivative. Deposits are a single contract call to the bridge carrying the depositor's Canton account identifier, supported by any wallet or custody setup that can make Ethereum contract calls. This model ensures that no single Attestor can authorize a payout on its own. The security of value movement rests on the honest-majority assumption of the Attestor network, which is composed of highly reputable and financially incentivized participants. Administrative controls, such as upgrades and pauses, are governed separately and are described in the security documentation. #### Dual network security BitSafe Attestors don't just observe Ethereum. They also verify state on Canton. The same trusted network confirms finalized ETH deposits and protects BETH issuance and redemption, creating seamless security across both networks. This design also adds resilience. BETH is issued by a decentralized party on Canton, so governed actions such as mint and redemption approvals require a threshold of independent members rather than a single operator. Operations continue even if an individual member is unavailable, and no lone member can act for the network. #### Why Canton? The BETH-Canton Network integration advances ETH adoption by enabling resilient, privacy-preserving flows for trading, structured products, and derivatives, alongside CBTC for Bitcoin exposure. Canton has the following features: * Configurable on-chain privacy settings: flows are visible only to the counterparties who need to see them. * Built for lending, trading, and settlements. --- # Overview URL: https://docs.bitsafe.finance/product-suite/assets/beth/overview/ BETH brings native ETH to Canton Network as a wrapped token. Credentialed participants deposit ETH through an Ethereum bridge and receive BETH on Canton. Redemption burns BETH on Canton before the bridge pays ETH to the specified Ethereum address. BETH is designed to represent native ETH at a 1:1 ratio. It does not represent WETH or stETH. The current design does not stake deposited ETH. BETH follows the same model as CBTC, the first non-native asset on Canton. The two assets use separate contracts, credentials, and governance. #### How minting works 1. A credentialed participant creates a BETH deposit account on Canton. The account supplies a stable identifier. 2. The participant deposits native ETH into the Ethereum bridge contract, together with that identifier. A plain ETH transfer is not a valid deposit. 3. Attestors observe the finalized Ethereum deposit. Canton governance confirms and executes the mint. 4. The participant receives BETH on Canton and can use it in compatible wallets and applications. #### How burning works 1. A participant creates a withdrawal account with an Ethereum destination address. 2. A withdrawal command burns BETH on Canton. 3. Attestors authorize the Ethereum payout. The bridge pays native ETH to the destination address. 4. After Ethereum finality, Canton records the completed redemption. #### Key facts | Item | Detail | | ------------------ | ------------------------------------------------------------------------ | | Asset | Wrapped native ETH on Canton Network, designed as 1:1 | | Networks | Ethereum Mainnet and Canton Network | | Bridge fee | Free at launch. Ethereum gas costs are separate. | | Transaction limits | 0.01 to 100 ETH per deposit or withdrawal | | Precision | 10 decimal places | | Access | Minting and redemption require onboarding and the BETH Minter credential | #### Availability Access to minting, redemption, and third-party applications depends on onboarding and the relevant provider's approval. --- # Where to Trade URL: https://docs.bitsafe.finance/product-suite/assets/beth/where-to-trade/ The BETH go live date is yet to be announced. Please return for more information soon. --- # Decentralization Manager URL: https://docs.bitsafe.finance/product-suite/decentralization-manager/ ## Overview Decentralization Manager is the open-source framework for creating and managing Decentralized Parties and governed applications on Canton Network. It is currently in public beta. Use it to coordinate operators, configure governance, and deploy application logic through the Generalized Governance Core, Token Management Module, and Custody Module. Run it self-hosted, or use the BitSafe-hosted Admin UI where available. ## Features * **Web-Based Management UI**: React frontend for managing decentralized parties * **Multi-Party Onboarding**: Coordinated workflow for creating decentralized party namespaces * **Contract Deployment**: Upload DAR files and deploy governance contracts with multi-party signing * **Governance Actions**: View and manage governance confirmations with threshold-based execution * **Participant Management**: View party membership, kick participants with threshold-based voting * **OAuth Authentication (Keycloak or Auth0)**: Supports M2M (client\_credentials) and password flows for Ledger API access, with a per-node choice of provider for both frontend gating and outbound Canton tokens * **Secure P2P Communication**: Noise Protocol Framework for encrypted coordinator to peer communication * **Real-time Status**: Live peer connectivity monitoring and workflow progress tracking * **Canton Integration**: Native gRPC integration with Canton Admin and Ledger APIs ## Documentation * [Introduction](/product-suite/decentralization-manager/introduction/): Start here - what Decentralization Manager does and why to decentralize your application on Canton * [Architecture Overview](https://github.com/DLC-link/decentralization-manager/blob/main/docs/ARCHITECTURE.md): System architecture, core concepts, communication protocol, and technical constraints * [User Guide](https://github.com/DLC-link/decentralization-manager/blob/main/USER_GUIDE.md): Walkthrough of the web UI for day-to-day party and governance operations * [Custom DAML Templates](https://github.com/DLC-link/decentralization-manager/blob/main/docs/CUSTOM_DAML_TEMPLATES.md): Authoring and deploying your own DAML governance templates * [Contributing Guide](https://github.com/DLC-link/decentralization-manager/blob/main/docs/CONTRIBUTING.md): Development setup, coding standards, commit conventions, and the PR process ### Security The Decentralization Manager was audited by Quantstamp (May 2026). The full audit report is available here: [Quantstamp Audit Report](https://certificate.quantstamp.com/full/bitsafe-dec-manager/9d0b465f-46c1-41bc-8d56-cfb3d3c44a76/index.html) ## Architecture The application runs as an HTTP server with an embedded React frontend. Multiple instances coordinate via the Noise Protocol: * **Coordinator**: Initiates workflows and orchestrates multi-party operations * **Peers**: Respond to coordinator commands, sign proposals, and execute local operations * **Automatic Key Management**: Noise keypairs are generated automatically on first run ``` ┌─────────────────┐ Noise Protocol ┌─────────────────┐ │ Participant 1 │◄───────────────────────►│ Participant 2 │ │ (Coordinator) │ │ (Peer) │ │ HTTP :8081 │ │ HTTP :8082 │ │ Noise :9001 │ │ Noise :9002 │ └────────┬────────┘ └────────┬────────┘ │ │ │ Canton Network │ └───────────────────┬───────────────────────┘ │ ┌────────▼────────┐ │ Canton Nodes │ │ (Admin/Ledger │ │ APIs) │ └─────────────────┘ ``` ## Quick Start ### Prerequisites * Rust toolchain (for building from source) * Access to Canton participant nodes (Admin API and Ledger API) * Docker (optional, for containerized deployment) ### Running Locally ```bash # Build and run with env vars DECPM_DIR=./development/participant-1 \ DECPM_PORT=8081 \ DECPM_CANTON_ADMIN_HOST=localhost \ DECPM_CANTON_ADMIN_PORT=5002 \ DECPM_CANTON_ADMIN_LEDGER_HOST=localhost \ DECPM_CANTON_LEDGER_PORT=5001 \ DECPM_NOISE_PORT=9001 \ cargo run -- serve # Or with a .env file in the data directory cargo run -- -d ./development/participant-1 serve # Or with release build cargo build --release DECPM_PORT=8081 ./target/release/dec-party-manager -d ./development/participant-1 serve ``` Open [http://localhost:8081](http://localhost:8081/) in your browser. ### Running with Docker ```bash # Build the image docker build -t dec-party-manager . # Run a single instance docker run -p 8080:8080 -v ./data:/data \ -e DECPM_CANTON_ADMIN_HOST=canton-node \ -e DECPM_CANTON_ADMIN_PORT=5002 \ -e DECPM_CANTON_LEDGER_HOST=canton-node \ -e DECPM_CANTON_LEDGER_PORT=5001 \ -e DECPM_NOISE_PORT=9001 \ -e DECPM_CANTON_SYNCHRONIZER=global \ -e DECPM_CANTON_NETWORK=devnet \ dec-party-manager ``` ### Running Multiple Participants (Development) ```bash cd development docker compose up ``` This starts three participant instances on ports 8081, 8082, and 8083. ## Configuration All node configuration is done via environment variables (prefixed `DECPM_*`) or CLI arguments. The `--dir` (`-d`) flag points to a directory for persistent data. If a `.env` file exists in that directory, it is loaded automatically before parsing CLI arguments. ### Directory Structure ``` participant-dir/ ├── .env # Optional environment file (loaded automatically) └── data/ ├── noise.key # Auto-generated Noise keypair ├── decpm.db # SQLite database (peers, party credentials) └── dars/ # DAR files for contract deployment ``` The database file path can be overridden with the `--db` CLI flag. ### Environment Variables | Variable | Description | Default | | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- | | `DECPM_DIR` | Root directory for persistent data (`--dir`/`-d`) | . | | `DECPM_HOST` | Host address to bind the HTTP/UI server to | `0.0.0.0` | | `DECPM_PORT` | Port for the HTTP/UI server | `8080` | | `DECPM_DB_PATH` | SQLite database path override (CLI flag `--db`) | (defaults to `{dir}/data/decpm.db`) | | `DECPM_DB_ENCRYPTION_KEY` | Encryption key for secrets stored in the database | (none) | | `DECPM_ADMIN_ROLE` | Role name that gates sensitive endpoints (unset skips the role check) | (none) | | `DECPM_ALLOWED_ORIGIN` | Origin permitted by CORS (for example `https://dpm.example.com`) | (none, same-origin only) | | `DECPM_LISTEN_ADDRESS` | Address to listen on for Noise protocol connections | `0.0.0.0` | | `DECPM_NOISE_PORT` | Port for Noise protocol connections | `9000` | | `DECPM_PUBLIC_ADDRESS` | Public address that peers use to connect to this node | (falls back to listen address) | | `DECPM_CANTON_ADMIN_HOST` | Canton Admin API host | `127.0.0.1` | | `DECPM_CANTON_ADMIN_PORT` | Canton Admin API port | `5002` | | `DECPM_CANTON_LEDGER_HOST` | Canton Ledger API host | `127.0.0.1` | | `DECPM_CANTON_LEDGER_PORT` | Canton Ledger API port | `5001` | | `DECPM_CANTON_SYNCHRONIZER` | Canton synchronizer name | `global` | | `DECPM_CANTON_NETWORK` | Canton network environment (`devnet`, `testnet`, `mainnet`) | `devnet` | | `DECPM_KEYCLOAK_URL` | Keycloak server URL for frontend auth | (none) | | `DECPM_KEYCLOAK_REALM` | Keycloak realm name for frontend auth | (none) | | `DECPM_KEYCLOAK_CLIENT_ID` | Keycloak client ID for frontend auth | (none) | | `DECPM_KEYCLOAK_INTERNAL_URL` | Internal/backchannel Keycloak URL the server uses for OIDC discovery, JWKS, and introspection when it cannot reach the public Keycloak URL directly | DECPM\_KEYCLOAK\_URL | | `DECPM_AUTH0_DOMAIN` | Auth0 tenant domain for frontend auth (mutually exclusive with the Keycloak variables) | (none) | | `DECPM_AUTH0_CLIENT_ID` | Auth0 SPA client ID for frontend auth | (none) | | `DECPM_AUTH0_AUDIENCE` | Auth0 API audience the SPA's access tokens target | (none) | | `DECPM_TIMEOUT_HANDSHAKE` | Noise handshake timeout in seconds | 30 | | `DECPM_TIMEOUT_MESSAGE` | Noise message timeout in seconds | 120 | | `DECPM_TIMEOUT_RETRY_ATTEMPTS` | Connection retry attempts | 3 | | `DECPM_TIMEOUT_RETRY_DELAY` | Connection retry delay in seconds | 5 | | `DECPM_NOISE_RETRY_TIMEOUT_SEC` | Per-attempt timeout for the bounded peer-Noise retry wrapper, in seconds | 5 | | `DECPM_NOISE_RETRY_MAX_ATTEMPTS` | Total attempts (initial plus retries) for the bounded peer-Noise retry wrapper | 2 | | `DECPM_NOISE_RETRY_BACKOFF_MS` | Backoff between attempts of the bounded peer-Noise retry wrapper, in milliseconds | 250 | ## API Reference The manager exposes an HTTP API for configuration, workflow orchestration, and governance. A complete, interactive reference is available via the Swagger UI at /swagger-ui/ (OpenAPI document at /api-docs/openapi.json). Note that these interactive endpoints are only mounted in development and test builds; the shipped release image does not expose them. The main endpoint groups are: * Node and network configuration: node and network info, peer list management, and per-party credential configuration. * Decentralized parties: listing parties and viewing participant connectivity and key status. * Workflows: starting, tracking, cancelling, retrying, and dismissing the onboarding, contracts, and kick workflows, plus managing invitations. * Authentication: checking authentication status and testing outbound identity-provider auth per party. * Governance: viewing governance state and confirmations, and submitting, executing, expiring, or cancelling governance actions. * Contracts and services: querying deployed vaults, provider/user/registrar services, active contracts by template, configured package IDs, and token-standard contracts. * DAR distribution: uploading DARs to the current node, distributing them across all participants, and tracking distribution progress. --- # Introduction URL: https://docs.bitsafe.finance/product-suite/decentralization-manager/introduction/ Decentralization Manager is the open-source application for creating, configuring, and managing Decentralized Parties, and the governed applications that run on them. A Decentralized Party is a single on-chain party whose keys and approvals are split across several independent node operators, so no single node can act alone. Understanding Decentralization Manager starts with understanding parties on Canton. ### Parties on Canton On Canton Network, assets are held by a party, not by the contract itself. A party can be controlled by a single node, which means one operator holds the keys and can act alone. The Decentralized Party is native Canton technology that distributes control of a party across multiple independent nodes under a signing threshold, so an application no longer depends on, or has to trust, any single node. ### Single-party building concentrates risk When one operator controls the party that holds an application's assets, several risks compound: * **Custodial risk:** a single operator can move or freeze assets. * **Operational risk:** if that one node goes offline, the application stops. * **Counterparty risk:** users and partners place full trust in a single entity. * **Regulatory risk:** sole control of user assets concentrates custodial responsibility in one operator. Institutions ask two questions before committing capital: who can move or freeze these assets, and what happens if one operator goes down. ### Distributing trust makes applications institutional-grade Decentralization Manager is the solution on Canton Network for building with Decentralized Parties and making applications institutional-grade. Decentralization Manager handles both sides: adding and removing operators, coordinating approvals, and keeping governance in sync. A party can be created, built upon, and configured from a visual interface or a CLI, and by connecting with peer operators, it runs the applications built on top of it. ### How Decentralization Manager works Members propose an action, confirm it against a signing threshold, then execute, with keys and governance distributed across independent nodes by design. ![](/assets/main/0705c58f-2324-4eee-92f5-b7872daf7c64.png) ### What can be built The same propose, confirm, execute lifecycle supports a wide range of applications: * **Tokenization and real-world assets:** multi-party issuance with on-chain governance, no single signer on the asset. * **Governed token issuance:** wrapped assets, stablecoins, and backed tokens issued and managed by a Decentralized Party. * **Decentralized custody and wallets:** threshold-confirmed transfers with no single custodian counterparty. * **DEXs, lending, and structured products:** governed parameters, treasury workflows, and admin operations on custom DAML. * **Vaults:** pooled deposits under a curator, governed by a Decentralized Party. * **Governed admin and protocol operations:** hold an application's most sensitive admin and governance actions, such as updating price oracles, adjusting supply caps, tuning interest rate formulae, and setting liquidation thresholds and borrowing limits, behind a signing threshold, so no single operator can change critical parameters alone. A protocol can decentralize these admin keys first, as a security operations baseline, before extending distribution to user-facing flows or to infrastructure resilience. The rest of these docs cover product architecture, deploying Decentralization Manager on a Canton node, creating a Decentralized Party, onboarding node operators, and building with each module. --- # Architecture Overview URL: https://docs.bitsafe.finance/product-suite/decentralization-manager/architecture-overview/ The Decentralization Manager runs as an HTTP server with an embedded React frontend. Multiple instances coordinate with one another over the Noise Protocol Framework to perform multi-party operations on Canton network deployments. ## Core concepts Coordinator: the instance that initiates workflows and orchestrates multi-party operations. Peers: instances that respond to coordinator commands, sign proposals, and execute local operations. Automatic key management: Noise keypairs are generated automatically on first run. ## Communication protocol Instances communicate over the Noise Protocol Framework, which provides encrypted coordinator-to-peer messaging. The coordinator listens on a Noise port (default 9000) while serving the management UI over HTTP (default 8080). Peers are configured with each other's connection details, and the coordinator orchestrates key generation, topology proposals, multi-party signing, and submission to Canton. ## Technical constraints Each node requires access to Canton participant nodes via the Admin API and Ledger API. Configuration is supplied through DECPM\_\* environment variables or CLI arguments. Peer and party state is persisted in a local SQLite database, and the interactive API reference (Swagger UI) is only mounted in development and test builds, not in the shipped release image. --- # User Guide URL: https://docs.bitsafe.finance/product-suite/decentralization-manager/user-guide/ This guide walks through the day-to-day operations available in the Decentralization Manager web UI. Open the UI in your browser at the configured host and port (for example http://localhost:8081), authenticate via the configured identity provider, and use the workflows below. ## Creating a decentralized party (onboarding) Configure every participant node with the others' connection details, start all participant servers, then on the coordinator's UI click Create Party and enter a party ID prefix. The coordinator invites peers and orchestrates cryptographic key generation, topology proposal creation, multi-party signing, and submission to Canton. ## Deploying contracts From a party card, click Deploy Contracts, upload DAR files via the file picker, and configure the contract definitions (operator party, templates, fields). The coordinator distributes and uploads the DARs to all participants, prepares the ledger submission, collects multi-party signatures, and executes on the Canton ledger. ## Removing a participant (kick) From a party card, click Kick Participant and select the participant to remove. The coordinator exports the current namespace state, creates updated topology proposals with a reduced threshold and the removed P2P mapping, collects signatures from the remaining members, and submits the proposal to Canton. ## Governance actions The UI surfaces governance confirmations grouped by action. Members confirm a proposed action, and once the confirmation threshold is met the action can be executed. Stale confirmations can be expired or cancelled. Workflow instances and their lifecycle state are visible in the UI, where you can also dismiss or retry failed workflows. ## Monitoring status Live peer connectivity monitoring and workflow progress tracking are available throughout the UI, so you can see which peers are reachable and how each multi-party workflow is progressing in real time. --- # Custom DAML Templates URL: https://docs.bitsafe.finance/product-suite/decentralization-manager/custom-daml-templates/ The Decentralization Manager can deploy governance contracts built from your own DAML templates, in addition to the built-in token-custody, utility, and vote plugins. This page covers authoring custom templates and deploying them through the manager. ## Authoring templates Write your governance logic as DAML templates and compile them into DAR files using the DAML SDK. Templates should define the operator party and any fields the manager will populate when configuring a contract definition. Keep template parameters explicit so they can be mapped to the deployment form in the web UI. ## Deploying templates Deploy your compiled DAR files from a party card in the web UI by clicking Deploy Contracts and uploading the files. The coordinator distributes the DARs to all participants, prepares the ledger submission, collects multi-party signatures, and executes deployment on the Canton ledger. Configured package IDs for a party can be reviewed through the manager once deployment completes. ## Best practices Test templates against a local development network before deploying to testnet or mainnet, version your DAR files so deployments are reproducible, and confirm that the operator party and signing thresholds in your template match the decentralized party configuration in the manager. --- # Use Cases URL: https://docs.bitsafe.finance/product-suite/decentralization-manager/use-cases/ The Decentralization Manager supports a range of multi-party governance scenarios on Canton. The walkthroughs below illustrate common deployments built on the onboarding, contract deployment, and governance workflows. ## Vault governance Deploy vault contracts governed by a decentralized party, where actions on the vault require threshold-based confirmation from member participants before they execute on the ledger. ## FAR rewards Coordinate the distribution of FAR rewards through governance confirmations, so that reward actions are proposed, confirmed by the required members, and executed under shared control. ## Multi-sig wallet Operate a wallet under decentralized control, where transactions are signed by multiple participants and only execute once the configured signing threshold is reached, removing reliance on any single key holder. ## Utility service Provision and run a utility service such as minting and burning under governance. The manager coordinates provider setup, mint, and burn actions through propose-confirm-execute cycles across the member participants. --- # Contributing Guide URL: https://docs.bitsafe.finance/product-suite/decentralization-manager/contributing-guide/ Contributions to the Decentralization Manager are welcome. This guide covers setting up a development environment, the coding standards, commit conventions, and the pull request process. Please also review the project's Code of Conduct, and report any vulnerabilities via the Security Policy. ## Development setup The backend is built with the Rust toolchain and the frontend is a React application embedded into the Rust binary at build time. Build with cargo build (add --release for a release build), and for the frontend run npm install and npm run dev for a hot-reloading development server, or npm run build for a production build. ``` # Build the backend (add --release for an optimized build) cargo build # Frontend (run from the frontend/ directory) npm install npm run dev # hot-reloading dev server npm run build # production build ``` ## Coding standards Format Rust code with cargo fmt and lint with cargo clippy --all-targets --all-features -- -D warnings, which treats warnings as errors. Run cargo test for unit tests before opening a pull request. ``` # Format code cargo fmt # Lint (warnings treated as errors) cargo clippy --all-targets --all-features -- -D warnings # Run unit tests cargo test ``` ## Testing The integration test boots a local Canton network, spawns three manager instances, configures peers, and runs an end-to-end governance workflow covering onboarding, DAR distribution, governance contract deployment, the plugin scenarios, and the kick workflow. Run it with ./integration-tests/run.sh, adding --verbose when diagnosing a stuck or failing run. The same suite can run against a real Canton devnet cluster with ./integration-tests/run.sh --target devnet. ``` # Run the integration test suite (quiet mode by default) ./integration-tests/run.sh # Verbose mode when diagnosing a stuck or failing run ./integration-tests/run.sh --verbose # Run against a real Canton devnet cluster ./integration-tests/run.sh --target devnet ``` ## Commit conventions and pull requests Follow the repository's commit message conventions and open a pull request for review. Ensure formatting, linting, and tests pass before requesting review, and keep changes focused so they are straightforward to review and merge. --- # Use Cases URL: https://docs.bitsafe.finance/use-cases/ ## Use Cases This page outlines practical applications for CBTC, addressing specific needs for BitSafe's institutional and developer audiences. ### CBTC: Confidential Bitcoin on Canton Network CBTC enables institutions to execute private trades and settlements on the Canton Network, ensuring transaction confidentiality for sensitive operations like OTC desk activities. It supports the creation of structured products, such as derivatives or margin flows, allowing investors to build complex financial instruments with privacy. ### Integrator Use Cases DEX Liquidity: Decentralized exchanges can integrate CBTC to offer private Bitcoin trading pairs on Canton, enabling institutional participants to trade without exposing position sizes or strategies. Wallet Support: Wallet providers can add CBTC support to give their institutional clients access to Canton Network's privacy features for Bitcoin holdings and transfers. Custody and Vault Platforms: Third-party custody providers and vault platforms can integrate CBTC to offer their clients access to Canton's private settlement infrastructure while maintaining their existing custody workflows. Trading Firm Settlement: Trading firms can use CBTC for confidential settlement of OTC trades, margin flows, and cross-venue transfers on Canton, reducing information leakage and counterparty risk. ### Key Benefits * Tailored Strategies: From private settlement to complex derivatives, CBTC aligns with institutional operational needs. * Transparency: Explicit risk disclosures, audited infrastructure, and real-time metrics empower informed decision-making. * Flexibility: Self-custodial or regulated custody options cater to diverse compliance needs. --- # FAQs URL: https://docs.bitsafe.finance/faqs/ ## FAQs BitSafe is committed to supporting institutional investors and developers with clear answers and detailed resources. Below, we address common questions about CBTC, compliance, and security. #### General Questions How does BitSafe ensure compliance? BitSafe follows a compliance-first approach designed to support institutional onboarding and ongoing risk management. Contact BitSafe for current requirements and supported custody workflows for your jurisdiction. What custody options are available? Investors can choose: * Self-Custodial * Regulated Custodians: Use trusted providers for CBTC * Multi-Party Computation (MPC): Secure wallets for flexible, institutional-grade custody #### Product-Specific Questions CBTC What privacy features does the Canton Network offer? Canton uses configurable sub-transaction privacy to ensure transaction details (e.g., amounts, parties) remain confidential, ideal for OTC desks and private trading. Only authorized nodes verify transactions. How is CBTC secured? CBTC is secured by the Attestor Network, a decentralized group of independent, institutional-grade operators using FROST threshold signatures. No single entity controls the majority, and the system is designed so that no single party can unilaterally move funds. What are the risks of bridging to CBTC? Risks include potential operator collusion (mitigated by the decentralized Attestor Network structure) and market risks on Canton. BitSafe provides explicit custody disclosures and audit reports for transparency. #### Risk and Security How does BitSafe mitigate smart contract vulnerabilities? BitSafe uses audited smart contracts from reputable developers, conducts regular third-party audits, and employs decentralized threshold security through the Attestor Network to minimize risks. How are funds protected? Funds are safeguarded through: * Decentralized Management: CBTC's Attestor Network prevents single-point failures * Regulated Custody: Optional regulated custody for CBTC * Audits: Regular smart contract and infrastructure audits ensure integrity #### Support Channels How can I get help? * Commercial enquiries: sales@bitsafe.finance * Technical support: support@bitsafe.finance --- # Getting Oriented URL: https://docs.bitsafe.finance/faqs/getting-oriented/ ### What this page is for Use this page to quickly find the right section of the docs site for what you are trying to do. ### I am new here. Where should I start? * If you are integrating CBTC into an app, start in **Developers** and begin with **CBTC Quick Start**. * If you are a trading firm evaluating or onboarding, start in **Trading Firms**. ### Key links * Developers * CBTC Quick Start: [https://docs.bitsafe.finance/developers/cbtc-quick-start](https://docs.bitsafe.finance/developers/cbtc-quick-start) * API Reference: [https://docs.bitsafe.finance/developers/cbtc-api-reference](https://docs.bitsafe.finance/developers/cbtc-api-reference) * Authentication: [https://docs.bitsafe.finance/developers/cbtc-authentication](https://docs.bitsafe.finance/developers/cbtc-authentication) * Trading Firms * Overview: [https://docs.bitsafe.finance/trading-firms](https://docs.bitsafe.finance/trading-firms) * Getting Started: [https://docs.bitsafe.finance/trading-firms/getting-started-venues-wallets-and-cbtc-acquisition](https://docs.bitsafe.finance/trading-firms/getting-started-venues-wallets-and-cbtc-acquisition) * FAQ for Trading Firms: [https://docs.bitsafe.finance/trading-firms/faq-for-trading-firms](https://docs.bitsafe.finance/trading-firms/faq-for-trading-firms) * CBTC (Product Suite) * CBTC FAQs: [https://docs.bitsafe.finance/product-suite/cbtc/cbtc-faqs](https://docs.bitsafe.finance/product-suite/cbtc/cbtc-faqs) * Audit Reports: [https://docs.bitsafe.finance/product-suite/cbtc/audit-reports](https://docs.bitsafe.finance/product-suite/cbtc/audit-reports) ### What is CBTC? CBTC is a 1:1 wrapped Bitcoin token by BitSafe that lives on the Canton Network. ### What is BitSafe? BitSafe builds institutional-grade Bitcoin infrastructure and products. CBTC is BitSafe’s Bitcoin product on the Canton Network. --- # CBTC Basics URL: https://docs.bitsafe.finance/faqs/cbtc-basics/ ### What this page is for This page answers the most common cross-cutting questions about CBTC. For deeper content, follow the links in each answer. ### How do I acquire CBTC? If you are a trading firm, start here: * [https://docs.bitsafe.finance/trading-firms/getting-started-venues-wallets-and-cbtc-acquisition](https://docs.bitsafe.finance/trading-firms/getting-started-venues-wallets-and-cbtc-acquisition) If you are integrating minting into an application, start here: * [https://docs.bitsafe.finance/developers/cbtc-quick-start](https://docs.bitsafe.finance/developers/cbtc-quick-start) ### How do minting and burning work? For the full lifecycle and edge cases, see: * [https://docs.bitsafe.finance/developers/cbtc-minting-and-burning](https://docs.bitsafe.finance/developers/cbtc-minting-and-burning) ### Do I need to run a Canton validator node? It depends on your workflow. Some acquisition paths do not require running a node, but direct minting flows typically do. Start with: * [https://docs.bitsafe.finance/trading-firms/getting-started-venues-wallets-and-cbtc-acquisition](https://docs.bitsafe.finance/trading-firms/getting-started-venues-wallets-and-cbtc-acquisition) ### Is there a testnet? Yes. Start with: * [https://docs.bitsafe.finance/developers/cbtc-testnet-guide](https://docs.bitsafe.finance/developers/cbtc-testnet-guide) ### Where can I find definitions of common terms? * [https://docs.bitsafe.finance/product-suite/cbtc/glossary](https://docs.bitsafe.finance/product-suite/cbtc/glossary) * [https://docs.bitsafe.finance/trading-firms/glossary](https://docs.bitsafe.finance/trading-firms/glossary) --- # Security and Audits URL: https://docs.bitsafe.finance/faqs/security-and-audits/ ### What this page is for This page covers the most common security questions at a high level and points to the canonical pages for details. ### How is CBTC secured? CBTC uses threshold signing with FROST to secure Bitcoin reserves. For the detailed security explanation, see: * [https://docs.bitsafe.finance/developers/security-deep-dive](https://docs.bitsafe.finance/developers/security-deep-dive) ### Is CBTC audited? See the audit reports here: * [https://docs.bitsafe.finance/product-suite/cbtc/audit-reports](https://docs.bitsafe.finance/product-suite/cbtc/audit-reports) You can also view the public audit report here: * [https://certificate.quantstamp.com/full/cbtc/5d0d805e-8cf0-4a39-bf1a-0e94899b3c1c/index.html](https://certificate.quantstamp.com/full/cbtc/5d0d805e-8cf0-4a39-bf1a-0e94899b3c1c/index.html) ### Where can I learn more about the security model? * [https://docs.bitsafe.finance/product-suite/cbtc/security-model](https://docs.bitsafe.finance/product-suite/cbtc/security-model) ### What are the main things to double-check before production use? * Use the Developers docs as the source of truth for integration steps. * Treat API behavior as subject to change unless explicitly labeled otherwise. * Validate assumptions against the changelog for recent updates: [https://docs.bitsafe.finance/developers/changelog](https://docs.bitsafe.finance/developers/changelog) --- # Support URL: https://docs.bitsafe.finance/faqs/support/ ### What this page is for Use this page to figure out the fastest path to help. ### Sales and onboarding If you are evaluating CBTC as a trading firm, want access, or need introductions to venues and partners, use: * Email: [sales@bitsafe.finance](mailto:sales@bitsafe.finance) * Trading Firms overview: [https://docs.bitsafe.finance/trading-firms](https://docs.bitsafe.finance/trading-firms) * Trading Firms FAQ: [https://docs.bitsafe.finance/trading-firms/faq-for-trading-firms](https://docs.bitsafe.finance/trading-firms/faq-for-trading-firms) ### Technical support for developers If you are integrating CBTC and need help with authentication, APIs, minting, burning, or testnet: * Email: [support@bitsafe.finance](mailto:support@bitsafe.finance) * Start here: [https://docs.bitsafe.finance/developers](https://docs.bitsafe.finance/developers) ### Reporting a docs issue Email the most relevant address above with: * The page URL * The exact sentence or section that looks wrong * What you expected to see instead --- # Brand & Press URL: https://docs.bitsafe.finance/brand-and-press/ For press inquiries or branding details, refer to our [Branding Kit](https://bitsafe.finance/brand-kit) or reach out to us at [sales@bitsafe.finance](mailto:sales@bitsafe.finance). --- # Trading Firms URL: https://docs.bitsafe.finance/trading-firms/ Evaluate and onboard to CBTC as a trading firm. Find venue guides, reward playbooks, onboarding checklists, and everything you need to start trading institutional-grade Bitcoin on the Canton Network. --- # Overview URL: https://docs.bitsafe.finance/trading-firms/overview/ Trade CBTC on Canton with privacy, MEV protection, and decentralized custody on top of your trading P\&L. *** ## For Prop Trading Desks > Whether you're running market making, arbitrage, or inventory rebalancing strategies, Canton's transaction-count-based rewards mean your existing edge in execution speed and trade frequency translates directly into Canton Coin rewards on top of your P\&L. > > * **Prop Desk Playbook** - Strategies and reward mechanics > * **Selecting a Trading Venue** - Compare RFQ, CLOB, and AMM options *** > > #### Passive Yield > > Not running an active desk? SciFeCap SMA offers a fully managed option targeting 8-10% yield with no infrastructure required on your side. 🔍 > > #### Evaluating CBTC? > > Start with **Why CBTC for Trading Firms** for Canton's differentiators, then check the **FAQ** for common questions from trading firms. *** :::note[Trade BTC with privacy, MEV protection, and institutional infrastructure →] Start with the [Prop Desk Playbook](https://docs.bitsafe.finance/trading-firms/prop-desk-playbook) for strategies and reward mechanics, then use [Getting Started: Venues, Wallets, and CBTC Acquisition](https://docs.bitsafe.finance/trading-firms/getting-started-venues-wallets-and-cbtc-acquisition) to find the right fit for your desk. ::: --- # Why CBTC for Trading Firms URL: https://docs.bitsafe.finance/trading-firms/why-cbtc-for-trading-firms/ CBTC is the native wrapped Bitcoin on the Canton Network, designed for institutional trading with privacy, MEV protection, and decentralized custody. This page explains why trading firms are integrating CBTC into their operations. *** ## Canton's Differentiators for Traders | **🛡️ MEV Protection** | **🔒 Private Positions** | **🏛️ Institutional Counterparties** | | -------------------------------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------- | | No public mempool. No front-running or sandwich attacks. | Your positions and strategy are not visible to other participants. | All nodes are KYC-verified. Trade against vetted, compliant institutions. | *** ## How CBTC Is Secured CBTC uses **FROST threshold signatures** over Bitcoin UTXOs for decentralized custody. There is no single custodian holding the underlying BTC. * **1:1 BTC backing** at all times, verified by Chainlink Proof of Reserve * **Decentralized Attestor Network** collectively approves mints and burns using a 2-of-4 threshold signing scheme * **No single point of failure.** No individual entity can unilaterally move the underlying Bitcoin * **Audited by Quantstamp.** Full report available at [certificate.quantstamp.com](https://certificate.quantstamp.com/) *** ## How to Trade CBTC > #### Active Trading > > For firms with in-house quant and dev resources running spot BTC strategies. > > * Market making, arbitrage, inventory rebalancing, directional trading > * Multiple venue types: RFQ, CLOB, AMM > * Transaction-count-based rewards favor high-frequency strategies See the **Prop Desk Playbook** for strategy details. *** ## Use Cases > **Spot and Perpetual Trading** Trade across RFQ (Elk/Trngle), CLOB (Temple Digital), and AMM (Tradefast) venues. No platform fees on most venues currently. 📊 **Lending and Borrowing** Lend CBTC on Haven Digital, Acme Markets, or Verity. Earn yield from interest on every lending transaction. Over-collateralized and smart contract secured. 💎 **Collateral Management** Use CBTC as high-quality collateral across multiple Canton venues. Atomic settlement reduces counterparty risk and improves capital efficiency. 🏗️ **Structured Products** Combine derivatives, lending, and spot markets to build risk-managed structured products. Canton's privacy model keeps your strategies confidential. *** ## Recommended Trading Pairs | **Pair** | **Description** | **Notes** | | ----------------- | -------------------------------------- | ------------------------------------------------- | | **CBTC / USDXLR** | Canton-native yield-bearing stablecoin | Primary pair. Earns rewards from both assets. | | **CBTC / USDCx** | Cross-chain stablecoin | Familiar stable pairing for BTC traders. | | **CBTC / CC** | Canton Coin | Network token exposure. Available on most venues. | Pair availability varies by venue. See **Selecting a Trading Venue** for venue-specific details. *** ## Technical Resources * [CBTC Technical Documentation](https://docs.bitsafe.finance/product-suite/cbtc) * [FROST Whitepaper](https://eprint.iacr.org/2020/852) (threshold signature security model) * [Canton Network Whitepaper](https://www.canton.network/whitepapers) * [Quantstamp Audit Report](https://certificate.quantstamp.com/full/cbtc/5d0d805e-8cf0-4a39-bf1a-0e94899b3c1c/index.html) *** ## Next Steps :::note[Ready to get started?] * Read the **Prop Desk Playbook** to understand strategies and reward mechanics * Compare venues in **Selecting a Trading Venue** * Follow the **Onboarding Checklist** to go from signup to first trade * [Complete the CBTC Signup Form](https://bitsafe.typeform.com/to/NsiwLKIY) * Email: [sales@bitsafe.finance](mailto:sales@bitsafe.finance) ::: *** :::note[Disclosures] Target yields are not guaranteed. Canton Coin rewards depend on network activity, token economics, and market conditions. Strategies carry risk; conduct independent due diligence. This is not investment advice. ::: --- # Prop Desk Playbook URL: https://docs.bitsafe.finance/trading-firms/prop-desk-playbook/ This guide is for prop trading firms with in-house quant and dev resources running spot BTC strategies. It explains how Canton's reward model works, which strategies generate the most value, and what rules apply. *** ## How Canton's Reward Model Works for Active Traders Canton Network rewards are based on **transaction count, not volume.** Every legitimate transaction involving CBTC generates Canton Coin (CC) rewards. For firms already running high-frequency spot strategies, this means your existing edge in execution speed and trade frequency translates directly into CC rewards on top of your trading P\&L. * No minimum volume thresholds. Every accepted trade counts. Rewards are only generated on transactions accepted by the counterparty. * Strategies you already run (market making, arbitrage, inventory rebalancing) generate both trading P\&L _and_ network rewards. *** ## Strategies That Work Canton's reward model rewards _frequency of legitimate economic activity._ These strategies naturally align with how prop firms already operate. ### Market Making Quote CBTC/USDXLR or CBTC/USDCx with defined inventory bands. Earn spread P\&L plus Canton rewards on every fill. ### Cross-Venue Arbitrage Exploit pricing differences between Elk RFQ, Temple CLOB, and Tradefast AMM. Each leg generates a separate reward-eligible transaction. ### Inventory Rebalancing Rotate CBTC across venues and pairs as part of normal risk management. Every rebalance trade counts toward rewards. ### Directional Spot Trading Apply existing spot BTC strategies to CBTC pairs. Same directional thesis, additional reward layer. ### Basis Trading Trade CBTC vs BTC price differentials across Canton and external venues. *** ## Venue Selection for Prop Desks Canton supports multiple venue types. The right choice depends on your trading style, technical stack, and preferred execution model. ### Which venue fits your desk? **Do you need institutional-size execution with custom pairs?** * **Elk / Trngle RFQ:** Programmatic OTC, negotiable spreads, bring your own wallet **Do you want an exchange-style order book with the best reward economics?** * **Temple Digital CLOB:** 40% bonus reward share on top of standard CBTC rewards **Do you want fast deployment with familiar DeFi infrastructure?** * **Tradefast AMM:** Uniswap V2 style, fastest integration path **Want the simplest starting point to test the waters?** * **Bron:** Intuitive interface, comprehensive docs, quick onboarding For full venue comparison tables and integration details, see **Selecting a Trading Venue**. *** ## Anti-Gaming Rules :::caution[Important] Strategies must involve real economic risk. Canton's tokenomics accountability process flags and shuts down scripted back-and-forth transfers (A to B to A) designed solely to farm rewards. If your strategy does not involve swapping into another asset, managing inventory risk, or providing liquidity, it will likely be flagged. Legitimate activity includes: market making, arbitrage, inventory rebalancing, directional trading, lending, and liquidity provision. ::: *** ## Getting Started :::note[Ready to start?] 1. Compare venues in **Selecting a Trading Venue** 2. Follow the **Onboarding Checklist** from signup to first trade * [Complete the CBTC Signup Form](https://bitsafe.typeform.com/to/NsiwLKIY) * Email: [sales@bitsafe.finance](mailto:sales@bitsafe.finance) ::: *** :::note[Disclosures] Target yields are not guaranteed. Canton Coin rewards depend on network activity, token economics, and market conditions. Strategies carry risk; conduct independent due diligence. This is not investment advice. ::: --- # Getting Started: Venues, Wallets, and CBTC Acquisition URL: https://docs.bitsafe.finance/trading-firms/getting-started-venues-wallets-and-cbtc-acquisition/ Canton supports multiple venue types for trading CBTC, each with different execution models, fee structures, and reward economics. This guide helps you choose the right venue for your firm. *** > ### Choose Your Venue > > **Do you have in-house quant and dev resources?** > > * **Yes:** You're a fit for active trading. See the venue comparison below. > * **No:** Consider **Temple Digital LP** (passive, single-sided) or **SciFeCap SMA** (fully managed, 8-10% target yield). **Do you need institutional-size execution with custom pairs?** > * **Elk / Trngle RFQ.** Contact Elk Capital for spread negotiation based on expected volume. **Do you want an exchange-style order book with the best reward economics?** > * **Temple Digital CLOB.** 40% bonus reward share on top of standard CBTC rewards. **Do you want fast deployment with familiar DeFi infrastructure?** > * **Tradefast AMM.** Uniswap V2 style, fastest integration path. **Want the simplest starting point?** > * **Bron.** Intuitive interface, comprehensive docs, quick onboarding. *** ## Active Trading Venues For firms with in-house quant and dev resources running active strategies. | **Venue** | **Type** | **Best For** | **Key Features** | **Pairs** | | ------------------ | ------------ | ---------------------------- | ------------------------------------------------------------------------- | --------------------------- | | **Elk / Trngle** | RFQ | Institutional-size execution | Programmatic OTC, negotiable spreads, custom pairs, bring your own wallet | Multiple (custom available) | | **Temple Digital** | CLOB | Order book traders | Exchange-style order book, 40% bonus reward share, best reward economics | CC-CBTC, USDCx-CBTC | | **Tradefast** | AMM | Fast deployment | Uniswap V2 style, fastest integration path, familiar DeFi infrastructure | BTC-CBTC, USDCx-CBTC | | **Bron** | Wallet + DEX | Simple starting point | Intuitive interface, comprehensive docs, quick onboarding | BTC-CBTC, CC-CBTC | *** ## Passive Allocation Options For firms seeking yield without active management or infrastructure build-out. | **Option** | **Type** | **Description** | **Key Details** | | --------------------- | ------------------- | ----------------------------------------------- | ----------------------------------------------------------------- | | **Temple Digital LP** | Liquidity Provision | Single-sided liquidity with no impermanent loss | Deposit CBTC, earn trading fees and Canton Coin rewards | | **SciFeCap SMA** | Managed Account | Fully managed strategy with 8-10% target yield | No active management required. Professional portfolio management. | :::note Target yields for passive options are illustrative only. Actual returns depend on market conditions, network activity, and token economics. ::: *** ## Recommended Trading Pairs | **Pair** | **Description** | **Notes** | | ----------------- | -------------------------------------- | --------------------------------------------- | | **CBTC / USDXLR** | Canton-native yield-bearing stablecoin | Primary pair. Earns rewards from both assets. | | **CBTC / USDCx** | Cross-chain stablecoin | Familiar stable pairing for BTC traders. | | **CBTC / CC** | Canton Coin | Network token exposure. | Pair availability varies by venue. Check the active trading venues table above for venue-specific pairs. *** ## Canton Wallet Options You need a Canton-compatible wallet to hold and transact with CBTC. | **Wallet** | **Type** | **Best For** | | ----------- | ------------------ | -------------------------------------------------- | | **Zoro** | Self-custody | Firms wanting SDK/API access and full control | | **Console** | Self-custody | Browser-based with clear signing and risk checks | | **Loop** | Self-custody | Web-based, no extensions needed, open source SDK | | **Cantor8** | Enterprise custody | Multi-signature security and regulatory compliance | For the full list of wallets and DeFi apps, see the **Canton DeFi Ecosystem** page. *** ## Acquiring CBTC Two paths depending on your infrastructure: **Option A: OTC Purchase** _(fastest, no Canton node required)_ * Initiate a cross-chain CBTC swap with Trngle or an OTC purchase through Elk Capital * Ideal for firms without a Canton validator node * Contact Elk Capital for spread negotiation based on expected volume **Option B: Direct Minting** _(requires Canton validator node)_ * Call Rust APIs via cbtc-lib to mint CBTC directly from BTC * More cost-effective for high-volume operations * See the developer documentation at [docs.bitsafe.finance/product-suite/cbtc](https://docs.bitsafe.finance/product-suite/cbtc) for technical details *** ## Don't Have a Canton Validator Node? :::note[Multi-tenant validators] provide a streamlined, cost-effective path to network participation without running a full Canton validator. BitSafe can connect you with trusted providers in the ecosystem. * Lower barrier to entry * Shared infrastructure costs * Get started in days, not weeks ::: *** ## Next Steps :::note[Ready to choose a venue?] * Review the **Prop Desk Playbook** for strategy recommendations * Follow the **Onboarding Checklist** to go from signup to first trade * [Complete the CBTC Signup Form](https://bitsafe.typeform.com/to/NsiwLKIY) * Email: [sales@bitsafe.finance](mailto:sales@bitsafe.finance) ::: *** :::note[Disclosures] Target yields are not guaranteed. Canton Coin rewards depend on network activity, token economics, and market conditions. Strategies carry risk; conduct independent due diligence. This is not investment advice. ::: --- # Canton DeFi Ecosystem URL: https://docs.bitsafe.finance/trading-firms/canton-defi-ecosystem/ The Canton Network ecosystem is growing rapidly with new wallets, DEXes, and DeFi applications launching regularly. This guide helps you navigate the available options for interacting with Canton Network and CBTC. > Each venue and wallet maintains its own documentation and onboarding process. For introductions or access requests, contact [sales@bitsafe.finance](mailto:sales@bitsafe.finance). *** ## Wallets Store, send, receive, and manage your Canton assets. | **Wallet** | **Type** | **Description** | **Website** | | --------------- | ------------------ | ------------------------------------------------------------------------------ | --------------------------------------------- | | **Zoro** | Self-custody | SDK and API support for institutional traders | [zorowallet.com](https://zorowallet.com/) | | **Console** | Self-custody | Browser wallet with clear signing and built-in risk checks | [consolewallet.io](https://consolewallet.io/) | | **Loop** | Self-custody | Web-based, works in any browser, no extensions needed. Open source SDK. | [cantonloop.com](https://cantonloop.com/) | | **Cantor8** | Enterprise custody | Privacy-first mobile wallet. No registration, no data collection. | [cantor8.tech](https://cantor8.tech/) | | **Bron** | Self-custody | Seedless recovery with MPC security, plus cross-chain swaps and staking | [bron.org](https://bron.org/) | | **Cansai** | Self-custody | First iOS-native Canton wallet with seamless Apple device sync | [cansai.app](https://cansai.app/) | | **Cypherock** | Hardware | Hardware wallet with decentralized key management | [cypherock.com](https://cypherock.com/) | | **Nightly** | Multi-chain | Multi-chain wallet with Canton support | [nightly.app](https://nightly.app/) | | **Send Wallet** | Self-custody | Passkey-first wallet. Log in with face or fingerprint instead of seed phrases. | [cantonwallet.com](https://cantonwallet.com/) | *** ## Trading Venues Swap, trade, and provide liquidity on Canton. | **Venue** | **Type** | **Available Pairs** | **Website** | | ------------------ | ------------ | --------------------------- | ----------------------------------------- | | **Elk / Trngle** | RFQ | Multiple (custom available) | [trngle.xyz](https://trngle.xyz/) | | **Temple Digital** | CLOB | CC-CBTC, USDCx-CBTC | [temple.digital](https://temple.digital/) | | **Tradefast** | DEX / AMM | BTC-CBTC, USDCx-CBTC | [trade.fast](https://trade.fast/) | | **Bron** | Wallet + DEX | BTC-CBTC, CC-CBTC | [bron.org](https://bron.org/) | | **TradeCraft** | AMM | CC-CBTC | [tradecraft.fi](https://tradecraft.fi/) | | **Cantex** | DEX | Multiple pairs | [cantex.io](https://cantex.io/) | | **Kairo** | DEX | Multiple pairs | [kairo.ag](https://kairo.ag/) | *** ## Lending Platforms Borrow and lend on Canton. | **Platform** | **Status** | **Description** | **Website** | | -------------------------- | ----------- | ------------------------------------------------------------------------- | ----------------------------------------------------------------- | | **Haven Digital Partners** | Live | Institutional lending app on Canton | [canton-lending.havendp.com](https://canton-lending.havendp.com/) | | **Acme (Hello Moon)** | Live | Decentralized, overcollateralized lending pools / money markets on Canton | [acmemarkets.cc](https://acmemarkets.cc/) | | **Verity (Hashrupt)** | Live | On-chain collateralized lending and loan lifecycle management on Canton | [hashrupt.com](https://hashrupt.com/) | | **Holdex** | In progress | Lending platform being built on Canton | [holdex.io](https://holdex.io/) | *** ## Other DeFi Apps Asset management, prediction markets, and more on Canton. | **App** | **Category** | **Website** | | ------------ | ----------------- | ------------------------------------------- | | **Unhedged** | Prediction Market | [unhedged.gg](https://unhedged.gg/) | | **Modulo** | DeFi Platform | [modulo.finance](https://modulo.finance/) | | **AllDeFi** | Asset Management | [alldefi.finance](https://alldefi.finance/) | | **Hecto** | DeFi Platform | [hecto.finance](https://hecto.finance/) | *** ## Coming Soon * **Additional Wallets:** Utila, Meteor Wallet *** _This is a living document. The Canton Network ecosystem is evolving rapidly. Check back regularly for updates._ *** :::note[Disclosures] This is not investment advice. Conduct independent due diligence before interacting with any third-party application. ::: --- # Onboarding Checklist: From Signup to First Trade URL: https://docs.bitsafe.finance/trading-firms/onboarding-checklist-from-signup-to-first-trade/ This guide walks you through the complete onboarding process for trading CBTC on Canton, from initial signup to your first live trade. Expected timeline: 1 to 2 weeks depending on your firm's readiness and chosen venue. *** ## Step 1: Express Interest > **Complete the CBTC Signup Form** [bitsafe.typeform.com/to/NsiwLKIY](https://bitsafe.typeform.com/to/NsiwLKIY) This registers your firm's interest and triggers outreach from the BitSafe BD team. You will be contacted to discuss your trading goals, preferred venues, and technical requirements. *** ## Step 2: Execute Agreements > **Sign the MSA** > > * **Master Service Agreement (MSA):** Standard commercial terms for using BitSafe services > * **KYC/AML:** Complete any required compliance checks Contact [sales@bitsafe.finance](mailto:sales@bitsafe.finance) if you have questions about the agreements. *** ## Step 3: Set Up a Canton Wallet > **Choose and configure your wallet** You need a Canton-compatible wallet to hold and transact with CBTC. Options for institutional traders: | **Wallet** | **Type** | **Best For** | | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | -------------------------------------------------- | | **Zoro** | Self-custody | Firms wanting SDK/API access and full control | | **Console** | Self-custody | Browser-based with clear signing and risk checks | | **Loop** | Self-custody | Web-based, no extensions needed, open source SDK | | **Cantor8** | Enterprise custody | Multi-signature security and regulatory compliance | | For the full list of Canton wallets and SDK/API documentation, see the [Canton DeFi Ecosystem](https://docs.bitsafe.finance/trading-firms/canton-defi-ecosystem) guide. | | | *** ## Step 4: Acquire CBTC > **Get CBTC into your wallet** Two paths depending on your infrastructure: **Option A: OTC Purchase** _(fastest, no Canton node required)_ > > * Initiate a cross-chain CBTC swap with Trngle or an OTC purchase through Elk Capital > * Ideal for firms without a Canton validator node > * Contact Elk Capital for spread negotiation based on expected volume **Option B: Direct Minting** _(requires Canton validator node)_ > * Install the mint/burn software on your validator node > * Call Rust APIs via cbtc-lib to mint CBTC directly from BTC > * More cost-effective for high-volume operations > * See the developer documentation at [docs.bitsafe.finance/product-suite/cbtc](https://docs.bitsafe.finance/product-suite/cbtc) for technical details *** ## Step 5: Choose and Connect to a Venue > **Select your trading venue and integrate** See **Selecting a Trading Venue** for the full comparison. Quick summary: > > * **Elk / Trngle** (RFQ) - Institutional OTC, negotiable spreads, custom pairs > * **Temple Digital** (CLOB) - Order book trading, 40% bonus reward share > * **Tradefast** (AMM) - Uniswap V2 style, fastest integration > * **Bron** - Intuitive interface, quick onboarding Each venue has its own API documentation and onboarding process. The BitSafe BD team will facilitate introductions. *** ## Step 6: Start Trading > **You are live.** > > * Begin trading on your chosen venue > * Every trade, swap, and lending transaction earns Canton Coin rewards > * Rewards are transaction-count-based, not volume-based. High-frequency strategies earn more. > * Review the **Prop Desk Playbook** for strategy recommendations **Recommended first trades:** > * CBTC/USDXLR (primary pair, earns rewards from both assets) > * CBTC/USDCx (familiar stable pairing) > * CBTC/CC (Canton Coin exposure) *** ## Questions? * **Email:** [sales@bitsafe.finance](mailto:sales@bitsafe.finance) * **Common questions:** See the FAQ for Trading Firms * **Technical questions:** See the developer documentation at [docs.bitsafe.finance/product-suite/cbtc](https://docs.bitsafe.finance/product-suite/cbtc) *** :::note[Disclosures] Target yields are not guaranteed. Canton Coin rewards depend on network activity, token economics, and market conditions. Strategies carry risk; conduct independent due diligence. This is not investment advice. ::: --- # FAQ for Trading Firms URL: https://docs.bitsafe.finance/trading-firms/faq-for-trading-firms/ Common questions from trading firms evaluating or onboarding to CBTC on Canton. This FAQ is compiled from sales conversations, partner calls, and Slack discussions. *** ## Fees and Costs ### What are the fees for minting and burning CBTC? Minting and burning fees are **currently waived.** This is subject to change in the future. Check with the BitSafe BD team for the latest fee schedule. ### Are there trading fees on the venues? Each venue sets its own fee structure: * **Elk / Trngle:** Negotiable spreads based on volume * **Temple Digital:** No platform fees currently * **Tradefast:** Standard AMM swap fees * **Bron:** Check venue documentation *** ## Anti-Gaming and Compliance ### What counts as "legitimate" trading activity? Strategies must involve **real economic risk.** This includes market making, arbitrage, inventory rebalancing, directional trading, lending, and liquidity provision. Each of these generates genuine market activity and is eligible for rewards. ### What activity is flagged or prohibited? Canton's tokenomics accountability process flags and shuts down **scripted back-and-forth transfers** (A to B to A) designed solely to farm rewards. If your strategy does not involve swapping into another asset, managing inventory risk, or providing liquidity, it will likely be flagged. ## Wallets and Infrastructure ### What wallet do I need? You need a **Canton-compatible wallet** that supports CBTC. Recommended options for institutional traders include Zoro (self-custody with SDK/API), Console (browser-based), Loop (web-based, open source SDK), and Cantor8 (enterprise custody with multi-sig). See the Canton DeFi Ecosystem guide for full details. ### Do I need to run a Canton validator node? Not necessarily. You can acquire CBTC via **OTC purchase** through Elk Capital or Trngle without running a node. However, if you want to **mint CBTC directly** from BTC, you will need a validator node. Multi-tenant validator options are available for firms that want node access without the full infrastructure build. ### Can I use multiple wallets? Yes. You can use multiple Canton-compatible wallets for trading CBTC across different venues. *** ## Venues and Trading ### Which venue should I choose? It depends on your trading style: * **Need institutional-size execution with custom pairs?** Elk / Trngle RFQ * **Want an order book with the best reward economics?** Temple Digital CLOB (40% bonus) * **Want fast deployment with familiar DeFi infra?** Tradefast AMM * **Want the simplest starting point?** Bron * **Prefer hands-off yield?** Temple Digital LP or SciFeCap SMA See **Selecting a Trading Venue** for the full comparison and decision guide. ### What trading pairs are available? The primary pairs are: * **CBTC / USDXLR** - Canton-native yield-bearing stablecoin (primary pair, earns rewards from both assets) * **CBTC / USDCx** - Cross-chain stablecoin * **CBTC / CC** - Canton Coin Availability varies by venue. Check the venue comparison table in **Selecting a Trading Venue**. ### Who are the current market participants? Active institutional counterparties on Canton include Elk Capital Markets, SciFeCap, HashKey Cloud, Desyn, IMC, QCP, and others. The trading firm pipeline is growing rapidly. *** ## Onboarding ### How long does onboarding take? Typically **1 to 2 weeks** from initial signup to first trade, depending on your firm's readiness, compliance review timeline, and chosen venue's integration requirements. ### What is the onboarding process? 1. Complete the CBTC signup form 2. Sign MSA and complete KYC/AML 3. Set up a Canton wallet 4. Acquire CBTC (OTC or direct mint) 5. Connect to your chosen venue 6. Start trading See the **Onboarding Checklist** for the full step-by-step guide. *** ## Security ### How is CBTC secured? CBTC uses **FROST threshold signatures** over Bitcoin UTXOs for decentralized custody. There is no single custodian. The Attestor Network collectively approves mints and burns using a threshold signing scheme. CBTC is fully 1:1 backed by BTC at all times. ### Has CBTC been audited? Yes. CBTC has been audited by **Quantstamp.** The full audit report is available at [certificate.quantstamp.com](https://certificate.quantstamp.com/). *** ## Getting Started :::note[Ready to start?] * [Complete the CBTC Signup Form](https://bitsafe.typeform.com/to/NsiwLKIY) * Email: [sales@bitsafe.finance](mailto:sales@bitsafe.finance) * Read the **Onboarding Checklist** for the full step-by-step process ::: *** :::note[Disclosures] Target yields are not guaranteed. Canton Coin rewards depend on network activity, token economics, and market conditions. Strategies carry risk; conduct independent due diligence. This is not investment advice. ::: --- # CBTC Ecosystem Docs URL: https://docs.bitsafe.finance/trading-firms/cbtc-ecosystem-docs/ Programmatically use products on Canton that support CBTC. Find documentation and links for venues, wallets, and other apps in the ecosystem. :::note Each venue and wallet maintains its own documentation and onboarding process. For introductions or access requests, contact [sales@bitsafe.finance](mailto:sales@bitsafe.finance). ::: *** ## Trading Venues | **Venue** | **Type** | **Docs / Website** | | | ------------------ | ------------ | --------------------------------------------------------- | - | | **Elk / Trngle** | RFQ | [trngle.xyz](https://trngle.xyz/) | | | **Temple Digital** | CLOB | [templedigitalgroup.com](https://templedigitalgroup.com/) | | | **Tradefast** | DEX / AMM | [trade.fast](https://trade.fast/) | | | **Bron** | Wallet + DEX | [bron.org](https://bron.org/) | | | **TradeCraft** | AMM | [tradecraft.fi](https://tradecraft.fi/) | | | **Cantex** | DEX | [cantex.io](https://cantex.io/) | | | **Kairo** | DEX | [kairo.ag](https://kairo.ag/) | | *** ## Wallets | **Wallet** | **Type** | **Docs / Website** | | ------------- | ------------------ | --------------------------------------------- | | **Zoro** | Self-custody | [zorowallet.com](https://zorowallet.com/) | | **Console** | Self-custody | [consolewallet.io](https://consolewallet.io/) | | **Loop** | Self-custody | [cantonloop.com](https://cantonloop.com/) | | **Cantor8** | Enterprise custody | [cantor8.tech](https://cantor8.tech/) | | **Bron** | Self-custody | [bron.org](https://bron.org/) | | **Cansai** | Self-custody | [cansai.app](https://cansai.app/) | | **Cypherock** | Hardware | [cypherock.com](https://cypherock.com/) | *** :::note[Disclosures] Venue APIs and SDKs are maintained by their respective providers. BitSafe does not guarantee the availability, accuracy, or stability of third-party documentation. Conduct your own technical due diligence. This is not investment advice. ::: --- # Resources URL: https://docs.bitsafe.finance/trading-firms/resources/ Consolidated links, documentation, and contact information for trading firms working with CBTC on Canton. *** ## Get Started | **Resource** | **Link** | | -------------------- | ---------------------------------------------------------------------------- | | CBTC Signup Form | [bitsafe.typeform.com/to/NsiwLKIY](https://bitsafe.typeform.com/to/NsiwLKIY) | | Sales and BD Contact | [sales@bitsafe.finance](mailto:sales@bitsafe.finance) | *** ## Technical Documentation | **Document** | **Link** | | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | CBTC Developer Documentation | [docs.bitsafe.finance/product-suite/cbtc](https://docs.bitsafe.finance/product-suite/cbtc) | | FROST Whitepaper (threshold signatures) | [eprint.iacr.org/2020/852](https://eprint.iacr.org/2020/852) | | Canton Network Whitepaper | [canton.network/whitepapers](https://canton.network/whitepapers) | | Quantstamp Audit Report | [certificate.quantstamp.com](https://certificate.quantstamp.com/) | | CBTC Technical Documentation (legacy) | [docs.bitsafe.finance/bitsafe-documentation/product-suite/cbtc](https://docs.bitsafe.finance/bitsafe-documentation/product-suite/cbtc) | | FROST Security Deep Dive | [docs.bitsafe.finance/product-suite/assets/cbtc/security-model/a-deep-dive-into-frost](https://docs.bitsafe.finance/product-suite/assets/cbtc/security-model/a-deep-dive-into-frost) | *** ## Venue Links | **Venue** | **Type** | **Website** | | -------------- | ------------ | ----------------------------------------- | | Elk / Trngle | RFQ | [trngle.xyz](https://trngle.xyz/) | | Temple Digital | CLOB | [temple.digital](https://temple.digital/) | | Tradefast | AMM | [trade.fast](https://trade.fast/) | | Bron | Wallet + DEX | [bron.org](https://bron.org/) | | TradeCraft | AMM | [tradecraft.fi](https://tradecraft.fi/) | *** ## Wallet Links | **Wallet** | **Website** | | ---------- | --------------------------------------------- | | Zoro | [zorowallet.com](https://zorowallet.com/) | | Console | [consolewallet.io](https://consolewallet.io/) | | Loop | [cantonloop.com](https://cantonloop.com/) | | Cantor8 | [cantor8.tech](https://cantor8.tech/) | | Bron | [bron.org](https://bron.org/) | | Cansai | [cansai.app](https://cansai.app/) | | Cypherock | [cypherock.com](https://cypherock.com/) | *** ## Trading Documentation All institutional docs live at [docs.bitsafe.finance/trading-firms](https://docs.bitsafe.finance/trading-firms). * **Why CBTC for Trading Firms:** Canton's differentiators, security model, and use cases * **Prop Desk Playbook:** Strategies, reward mechanics, and anti-gaming rules * **Selecting a Trading Venue:** Venue comparison, decision guide, and wallet options * **Canton DeFi Ecosystem:** Full wallet, DEX, and DeFi app directory * **Onboarding Checklist:** Step-by-step from signup to first trade * **FAQ for Trading Firms:** Common questions answered Developer documentation lives at [docs.bitsafe.finance/product-suite/cbtc](https://docs.bitsafe.finance/product-suite/cbtc). *** ## Standardized Disclosures :::note[Risk Disclosure] Target yields and reward projections are illustrative only and are not guaranteed. Canton Coin rewards depend on network activity, token economics, and market conditions. Trading strategies carry risk. Conduct independent due diligence before making any trading or allocation decisions. ℹ️ **Not Investment Advice** Nothing in this documentation constitutes investment, legal, or tax advice. All information is provided for informational purposes only. ::: --- # Glossary URL: https://docs.bitsafe.finance/trading-firms/glossary/ Key terms and acronyms used across the institutional documentation. If you are coming from traditional finance or other blockchain networks, this page will help you navigate Canton-specific terminology. --- ## Assets and Tokens **CBTC (Canton Bitcoin)** Wrapped Bitcoin on the Canton Network. 1 CBTC is always backed 1:1 by BTC held in decentralized custody. CBTC is the primary asset for institutional trading on Canton. **CC (Canton Coin)** The native network rewards token on Canton. CC is earned through eligible transactions and distributed to participants. CC is not a stablecoin. Its value fluctuates based on market conditions. **USDXLR** A Canton-native yield-bearing stablecoin. The primary trading pair for CBTC. Trading CBTC/USDXLR earns rewards from both assets. **USDCx** A cross-chain stablecoin available on Canton. Provides a familiar stable pairing for BTC traders. --- ## Canton Network **Canton Network** An institutional-grade blockchain network designed for privacy, compliance, and atomic settlement. All participants are KYC-verified. **Daml** Canton's smart contract language. Used for building applications and defining transaction logic on the network. **CIP-56** Canton token standard. Defines how tokens (including CBTC) are created, transferred, and managed on Canton. **Validator Node** A node that participates in the Canton Network's consensus and transaction processing. Required for direct CBTC minting. Multi-tenant validator options are available for firms that do not want to run their own. **Multi-Tenant Validator** A shared validator node operated by a third-party provider. Allows firms to participate in the Canton Network without running their own infrastructure. Lower cost and faster setup than a dedicated node. --- ## Security and Custody **FROST (Flexible Round-Optimized Schnorr Threshold)** The threshold signature scheme used for CBTC's decentralized custody. FROST allows multiple parties to collectively sign Bitcoin transactions without any single party holding the full private key. **Attestor Network** The group of decentralized signers that collectively approve CBTC mints and burns using FROST threshold signatures. Currently operates on a 2-of-4 threshold. **Threshold (M-of-N)** The minimum number of attestors required to approve a transaction. For CBTC, 2 out of 4 attestors must sign to authorize a mint or burn. **Proof of Reserve (PoR)** Chainlink's verification mechanism confirming that all CBTC in circulation is fully backed 1:1 by BTC held in custody. --- ## Trading and Venues **RFQ (Request for Quote)** A trading model where a firm requests a price from a market maker and can accept or reject the quote. Used by Elk Capital / Trngle for institutional OTC execution. **CLOB (Central Limit Order Book)** A traditional exchange-style order book where buy and sell orders are matched by price and time priority. Used by Temple Digital. **AMM (Automated Market Maker)** A DeFi trading model where liquidity pools and mathematical formulas determine prices instead of an order book. Used by Tradefast. **MEV (Miner/Maximal Extractable Value)** The profit that can be extracted by reordering, inserting, or censoring transactions in a block. Canton eliminates MEV because it has no public mempool. **Mempool** A holding area for unconfirmed transactions visible to all network participants. Canton does not have a public mempool, which prevents front-running and sandwich attacks. --- ## Rewards and Economics **Transaction-Count-Based Rewards** Canton's reward model where every eligible transaction generates CC rewards regardless of transaction size. High-frequency strategies earn more rewards than low-frequency, high-volume strategies. **Featured App (FA)** A Canton application that has been designated as a Featured App, which affects reward multipliers for activity within that application. **Anti-Gaming Policy** Canton's tokenomics accountability process that detects and shuts down artificial transaction patterns (such as A to B to A transfers) designed to farm rewards without real economic activity. --- ## Agreements and Onboarding **MSA (Master Service Agreement)** The standard commercial agreement between a trading firm and BitSafe. Required before a firm can mint CBTC. **KYC/AML (Know Your Customer / Anti-Money Laundering)** Compliance checks required during onboarding. All Canton participants must be KYC-verified. --- ## Technical **DAR (Daml Archive)** A compiled Daml package file used to deploy smart contracts on Canton. **cbtc-lib** A Rust library for interacting with CBTC minting and burning functionality. Required for direct minting from BTC. **Canton SDK** The software development kit for building applications and submitting transactions on the Canton Network. --- # Developers URL: https://docs.bitsafe.finance/developers/ Build integrations, wallets, and DeFi protocols with CBTC on the Canton Network. This section covers everything you need to go from first API call to production deployment. ## Getting Started * [CBTC Overview](/developers/cbtc-overview/) - Architecture and core concepts * [SDK Setup and Installation](/developers/sdk-setup-and-installation/) - Install cbtc-lib, upload the DAR files, and configure your environment. **Start here.** * [CBTC Quick Start](/developers/cbtc-quick-start/) - Mint your first CBTC in 15 minutes * [CBTC Testnet Guide](/developers/cbtc-testnet-guide/) - Test on Canton testnet before going live ## Core Operations * [CBTC Minting and Burning](/developers/cbtc-minting-and-burning/) - Convert BTC to CBTC and back with code * [CBTC Authentication](/developers/cbtc-authentication/) - Authenticate with the Canton Ledger API * [CBTC API Reference](/developers/cbtc-api-reference/) - Full API endpoint documentation * [Instrument ID Management](/developers/instrument-id-management/) - Manage CBTC instrument identifiers ## Advanced * [Integration Guides](/developers/integration-guides/) - Integrate CBTC into your platform * [Technical Reference](/developers/technical-reference/) - Detailed technical specifications * [Security Deep Dive](/developers/security-deep-dive/) - Threat model, FROST signatures, and audit results ## Reference * [Resources](/developers/resources/) - Audit reports, whitepapers, and external links * [Changelog](/developers/changelog/) - Release notes and version history --- # CBTC Overview URL: https://docs.bitsafe.finance/developers/cbtc-overview/ :::caution[API Disclaimer] CBTC APIs are subject to change. There is no formal versioning policy today. Breaking changes are communicated via the site changelog. ::: --- ## What is CBTC? Bitcoin on the Canton Network CBTC is a **1:1 wrapped Bitcoin token** built on the [Canton Network](https://www.canton.network/), a privacy-first blockchain for institutional finance. Each CBTC is fully backed by native BTC held in decentralized custody using FROST threshold signatures. CBTC is **CIP-56 compliant**, meaning it works with any Canton token-standard-compatible tool out of the box. CBTC brings Bitcoin's liquidity into Canton's privacy-enabled smart contract environment, where app developers and trading firms can build trading, DeFi, custody, and settlement applications without exposing positions to a public mempool. Unlike wrapped Bitcoin on public chains, CBTC transactions are private by default, eliminating MEV (Maximal Extractable Value) risks like front-running and sandwich attacks. **Key properties:** | Property | Value | | --- | --- | | **Backing** | 1 CBTC = 1 BTC, always | | **Standard** | CIP-56 (Canton Instrument Protocol) | | **Custody** | Decentralized via FROST threshold signatures (no single party can move reserves) | | **Network** | Canton Network (permissioned, private transactions) | | **Audit** | [Quantstamp audit report](https://certificate.quantstamp.com/full/cbtc/5d0d805e-8cf0-4a39-bf1a-0e94899b3c1c/index.html) | | **Confirmations** | 6 Bitcoin block confirmations (~60 minutes) for minting | --- ## CBTC Architecture: How Wrapped Bitcoin Works on Canton The CBTC system bridges Bitcoin's UTXO model to Canton's Daml-based smart contract network through three layers: ### 1. Bitcoin Layer Bitcoin transactions are monitored and verified. A user sends BTC to a generated Taproot deposit address. The system waits for 6 block confirmations before proceeding. ### 2. Attestor Network A decentralised network of institutional-grade node operators independently verify Bitcoin deposits and withdrawals. Each Attestor runs nodes on **both** the Bitcoin and Canton networks. Key details: * **Operators:** Pre-screened institutional node operators (including providers like Finoa and Nethermind) * **Threshold:** A configurable M-of-N threshold of Attestors must approve every mint and burn operation * **Coordination:** A Coordinator executes periodic checks (every 60-120 seconds), monitors deposit accounts, constructs Bitcoin transactions, and submits governance actions * **No unilateral control:** No single party - including BitSafe or the Coordinator - can mint, burn, or move BTC without threshold approval ### 3. Canton Asset Layer Daml contracts mint and burn CBTC tokens, but **only** after the required threshold of Attestor signatures is reached on the governance contract. CBTC is then held in the user's Canton party, fully under their control. ```mermaid flowchart LR A["Bitcoin Network
(Taproot deposit address)"] -->|"6 confirmations"| B["Attestor Network
(FROST threshold signing)"] B -->|"M-of-N approval"| C["Canton Network
(Daml contracts mint CBTC)"] C -->|"Burn request"| B B -->|"Signed BTC tx"| A ``` --- ## Security Model: FROST Threshold Signatures for Bitcoin Custody CBTC's security rests on **FROST** (Flexible Round-Optimised Schnorr Threshold Signatures), a cryptographic protocol added to Bitcoin with the Taproot upgrade. **Why FROST matters for developers:** * **Taproot-native:** Deposit addresses are standard P2TR addresses. Any wallet that supports Taproot can send BTC to mint CBTC. * **Indistinguishable on-chain:** FROST signatures look identical to regular single-signature Bitcoin transactions. No one can tell from the blockchain that a threshold scheme is in use. * **Smaller transactions, lower fees:** Compared to traditional on-chain multisig, FROST produces a single aggregated signature regardless of how many Attestors participated. * **No single point of failure:** Even if some Attestors go offline, the system continues to operate as long as the threshold is met. For a full technical deep dive, see the [Security Deep Dive](https://docs.bitsafe.finance/developers/security-deep-dive) page. For the original research, see the [FROST whitepaper](https://eprint.iacr.org/2020/852). --- ## What You Can Build with Wrapped Bitcoin on Canton CBTC is a foundational layer for building institutional-grade financial products on Canton: * **DeFi Protocols** - DEXs, lending platforms, and liquidity pools using CBTC as collateral * **Custody and Wallet Solutions** - Institutional-grade wallets supporting CBTC and Canton-native assets * **Structured Products** - Yield-generating vaults, options strategies, and derivatives * **Payment and Settlement** - Instant, low-cost cross-border transactions * **Trading Systems** - Spot and perpetual trading with Canton's privacy (no public mempool, no MEV) --- ## Developer Resources | Resource | Description | Link | | --- | --- | --- | | **cbtc-lib (Rust)** | SDK for minting, burning, sending, and receiving CBTC | [GitHub](https://github.com/DLC-link/cbtc-lib) · [Setup guide](https://docs.bitsafe.finance/developers/sdk-setup-and-installation) | | **canton-lib** | Lower-level Canton interaction library | [GitHub](https://github.com/DLC-link/canton-lib/) | | **CBTC DAR files** | Daml packages to install on your Canton participant | [GitHub](https://github.com/DLC-link/cbtc-lib/tree/main/cbtc-dars) | | **FROST Whitepaper** | Original threshold signature research | [ePrint](https://eprint.iacr.org/2020/852) | | **Canton Whitepaper** | Canton Network technical overview | [canton.network](https://canton.network/) | | **Quantstamp Audit** | Security audit of CBTC smart contracts | [View Report](https://certificate.quantstamp.com/full/cbtc/5d0d805e-8cf0-4a39-bf1a-0e94899b3c1c/index.html) | | **Data API** | Analytics and rewards API for institutional clients | [API Reference](https://docs.bitsafe.finance/developers/cbtc-api-reference) | --- ## Next Steps * **Ready to code?** Start with [SDK Setup and Installation](https://docs.bitsafe.finance/developers/sdk-setup-and-installation) to install `cbtc-lib` and configure your environment, then follow the [Developer Quick Start](https://docs.bitsafe.finance/developers/cbtc-quick-start) to mint your first CBTC in 15 minutes * **Need API details?** See the [API Reference](https://docs.bitsafe.finance/developers/cbtc-api-reference) for Canton Ledger API endpoints * **Setting up authentication?** See the [Authentication Guide](https://docs.bitsafe.finance/developers/cbtc-authentication) for Keycloak setup (and an Auth0 community example) * **Want to test first?** See the [Testnet Guide](https://docs.bitsafe.finance/developers/cbtc-testnet-guide) for sandbox environment setup --- --- # SDK Setup and Installation URL: https://docs.bitsafe.finance/developers/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. :::caution[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`: ```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: ```toml 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](https://docs.bitsafe.finance/cbtc/concepts-and-reference/token-standard-and-contract-model) for the complete boundary. ### Configure the repository examples The repository examples load a local `.env` file. Copy the tagged template: ```bash cp .env.example .env ``` Use this setup pattern, replacing every placeholder: ```dotenv 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: * [Password authentication and balance query](https://github.com/DLC-link/cbtc-lib/blob/v0.9.0/examples/check_balance.rs) * [Authenticated TokenClient setup](https://github.com/DLC-link/cbtc-lib/blob/v0.9.0/examples/token_client.rs) 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: ```bash 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. 1. Check out the approved v0.9.0 tag. 2. Complete the local configuration. 3. Build the workspace without live credentials: ```bash cargo build --examples ``` 4. In the approved test environment, run: ```bash 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: ```bash 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 * [v0.9.0 manifest](https://github.com/DLC-link/cbtc-lib/blob/v0.9.0/Cargo.toml) * [v0.9.0 environment template](https://github.com/DLC-link/cbtc-lib/blob/v0.9.0/.env.example) * [v0.9.0 README](https://github.com/DLC-link/cbtc-lib/blob/v0.9.0/README.md) *** ## 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 *** --- # CBTC Quick Start URL: https://docs.bitsafe.finance/developers/cbtc-quick-start/ :::caution[API Disclaimer] CBTC APIs have no formal versioning policy today. All endpoints and library interfaces described in this guide are **subject to change**. Breaking changes are communicated via the changelog. This disclaimer will be updated once a formal versioning and stability policy is established. ::: This step-by-step guide walks you through minting your first CBTC (wrapped Bitcoin) on the Canton Network. You will authenticate with Keycloak, create a deposit account, send BTC to a Taproot address, and receive 1:1 backed CBTC on your Canton participant node. The full process takes about 15 minutes of active work plus \~60 minutes of Bitcoin confirmation time. :::tip[What you will accomplish] * Authenticate to the Canton Network via Keycloak * Create a CBTC deposit account * Obtain a Bitcoin deposit address * Send BTC and wait for confirmation * Verify your CBTC balance * Send CBTC to another party ::: :::note[Install the SDK first] Every code example on this page uses the `cbtc-lib` Rust SDK. If you have not installed it yet, start with [SDK Setup and Installation](https://docs.bitsafe.finance/developers/sdk-setup-and-installation) — it covers installing `cbtc-lib` and `canton-lib`, uploading the CBTC DAR files to your participant node, and configuring your environment variables. Come back here once the verification check on that page passes. ::: *** ## Prerequisites for Minting CBTC Before you begin minting wrapped Bitcoin on Canton, make sure you have the following: | Requirement | Description | | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Canton participant node** | A running Canton participant node connected to the network. See [Canton documentation](https://docs.digitalasset.com/canton) for setup. | | **DA Registry Utility** | Installed and configured. See [Digital Asset Utilities docs](https://docs.digitalasset.com/utilities/mainnet/index.html). | | **Keycloak credentials** | A valid Keycloak host, realm, client ID, username, and password for your environment. | | **Party ID** | Your Canton Party ID, obtained during onboarding. | | **Minter credential** | **Required to mint or burn.** Issued to your party by the CBTC registrar as part of onboarding. Request one via [sales@bitsafe.finance](mailto:sales@bitsafe.finance). See [Minting and Burning](https://docs.bitsafe.finance/developers/cbtc-minting-and-burning) for how to check and accept it. | | **Rust toolchain** | If using cbtc-lib (Rust). Install via [rustup.rs](https://rustup.rs/). | | **BTC to deposit** | Real BTC (mainnet) or testnet BTC (testnet). For testnet, you can use the [CBTC Testnet Faucet](https://faucet.bitsafe.finance/) to get test CBTC directly. For mainnet, you mint CBTC by depositing real BTC. | *** ## Choose Your CBTC Environment: Testnet or Mainnet CBTC is available on three environments. **Start with testnet** for experimentation, then move to mainnet for production. CBTC also exists on Devnet, but minting and withdrawals are not available to external users on Devnet. You can use the faucet to obtain test CBTC for development. :::note[Testnet vs. Mainnet: what is identical and what differs] * **Identical:** DAR file, API surface, mint/burn flows, governance model, transfer mechanics * **Differs:** Attestor set (smaller on testnet), confirmation times (may be faster), Instrument IDs (different from mainnet), faucet-only BTC on testnet (no real value) * **Mocked or unavailable on testnet:** Real BTC settlement, production Attestor SLAs, mainnet fee structure * **Operational note:** Testnet may be reset without notice. Testnet CBTC balances and transaction history may not persist across resets. Do not rely on testnet state for production planning. ::: ### Environment Configuration | 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` | `cbtc-network::12202a83c6f4082217c175e29bc53da5f2703ba2675778ab99217a5a881a949203ff` | `cbtc-network::12201b1741b63e2494e4214cf0bedc3d5a224da53b3bf4d76dba468f8e97eb15508f` | `cbtc-network::12205af3b949a04776fc48cdcc05a060f6bda2e470632935f375d1049a8546a3b262` | Set these as environment variables before running any commands: ```bash export BITSAFE_API_URL="https://api.testnet.bitsafe.finance" export REGISTRY_URL="" export CANTON_NETWORK="canton-testnet" export DECENTRALIZED_PARTY_ID="" export KEYCLOAK_HOST="https://your-keycloak-host" export KEYCLOAK_REALM="your-realm" export KEYCLOAK_CLIENT_ID="your-client-id" export KEYCLOAK_USERNAME="your-username" export KEYCLOAK_PASSWORD="your-password" export LEDGER_HOST="https://your-ledger-host" export PARTY_ID="your-party-id" ``` *** ## Step 1: Authenticate with Keycloak All CBTC operations require a valid Keycloak access token. The `canton-lib` crate provides a helper for this. ### Using cbtc-lib (Rust) ```rust use keycloak::login::{password, token_url, PasswordParams}; let auth = password(PasswordParams { client_id: keycloak_client_id.clone(), username: keycloak_username.clone(), password: keycloak_password.clone(), url: token_url(&keycloak_host, &keycloak_realm), }).await?; let access_token = auth.access_token; ``` ### Using the Keycloak API directly ```bash curl -X POST "${KEYCLOAK_HOST}/realms/${KEYCLOAK_REALM}/protocol/openid-connect/token" \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "grant_type=password" \ -d "client_id=${KEYCLOAK_CLIENT_ID}" \ -d "username=${KEYCLOAK_USERNAME}" \ -d "password=${KEYCLOAK_PASSWORD}" ``` Save the `access_token` from the response. You will pass it as a Bearer token in all subsequent API calls. :::note[`api_url` in the code examples below] is the BitSafe API base URL — the value you set as `BITSAFE_API_URL` above. It serves the `/cbtc/v1/*` endpoints that back deposit accounts, deposit addresses, and withdrawals. ::: *** ## Step 2: Create a Deposit Account A deposit account maps your Canton Party ID to a unique Bitcoin deposit address. You only need to create this once; the address can be reused for future deposits. :::caution[This step requires a Minter credential] Deposit account creation fails without one. If you have not been issued a Minter credential yet, request one via [sales@bitsafe.finance](mailto:sales@bitsafe.finance). See [Minting and Burning](https://docs.bitsafe.finance/developers/cbtc-minting-and-burning) for how to check for and accept your credential. ::: ### Using cbtc-lib ```rust use cbtc::mint_redeem::{mint, attestor}; // First get account rules from the Attestor let account_rules = attestor::get_account_contract_rules(&api_url).await?; let deposit_account = mint::create_deposit_account(mint::CreateDepositAccountParams { ledger_host: ledger_host.clone(), party: party_id.clone(), user_name: username.clone(), access_token: access_token.clone(), account_rules, credential_cids: minter_credential_cids.clone(), }).await?; ``` ### Using the Canton API directly Submit a `CreateDepositAccount` command to the Canton Ledger API v2 endpoint. You can fetch the `CBTCDepositAccountRules` contract from an Attestor's `GET /cbtc/v1/account-contract-rules` endpoint. ```bash curl -X POST "${LEDGER_HOST}/v2/commands/submit-and-wait-for-transaction" \ --header 'Authorization: Bearer ${ACCESS_TOKEN}' \ --header 'Content-Type: application/json' \ --data '{ "commands": { "commands": [ { "ExerciseCommand": { "templateId": "#cbtc:CBTC.DepositAccount:CBTCDepositAccountRules", "contractId": "${DA_RULES_CID}", "choice": "CBTCDepositAccountRules_CreateDepositAccount", "choiceArgument": { "owner": "${OWNER_PARTY}", "credentialCids": ["${MINTER_CREDENTIAL_CID}"] } } } ], "actAs": [ "${OWNER_PARTY}" ], "commandId": "someCommandID", "disclosedContracts": [ { "templateId": "#cbtc:CBTC.DepositAccount:CBTCDepositAccountRules", "contractId": "${DA_RULES_CID}", "createdEventBlob": "${DA_RULES_BLOB}", "synchronizerId": "" } ] } }' ``` :::note Note: These samples use the submit-and-wait-for-transaction endpoint. Canton deprecated the submit-and-wait-for-transaction-tree endpoint in 3.4. Canton 3.6 disables it by default, and Canton 3.7 removes it. ::: :::note[Ephemeral contract IDs] `DA_RULES_CID` and `DA_RULES_BLOB` are ephemeral contract IDs. Query them from the Active Contract Service (`POST /v2/state/active-contracts`) at submit time. These IDs change after every consuming exercise. ::: *** ## Step 3: Get Your Bitcoin Deposit Address Once the deposit account is created, retrieve the Bitcoin address associated with it. This address is derived from the Deposit Account's `id` field (or the `contract_id` if the Deposit Account is new). ### Using cbtc-lib ```rust let btc_address = mint::get_bitcoin_address(mint::GetBitcoinAddressParams { api_url: api_url.clone(), account_id: deposit_account.account_id().to_string(), }).await?; println!("Send BTC to: {}", btc_address); ``` ### Using the BitSafe API directly Retrieve the deposit address from: ``` GET ${BITSAFE_API_URL}/cbtc/v1/bitcoin-address/{accountId} ``` Use the deposit account's `id` field as `accountId`. **Important:** This address can be reused indefinitely for future deposits. You can also request additional deposit addresses if needed. *** ## Step 4: Send BTC Send Bitcoin to the deposit address using any standard Bitcoin wallet or tooling. :::caution[Deposits are subject to per-account limits] By default the minimum is **0.0001 BTC** and the maximum is **5 BTC**. A deposit outside that range will not be minted. Limits are set per account and can be adjusted on request - see [Transaction Limits](https://docs.bitsafe.finance/developers/cbtc-minting-and-burning) for how to read your account's actual limits at runtime rather than assuming the defaults. ::: ```javascript Bitcoin address: [your deposit address from Step 3] ``` After sending, you need to wait for **6 Bitcoin block confirmations** before the Attestor network will process the deposit. *** ## Step 5: Wait for Confirmations and Auto-Minting Once your BTC transaction reaches 6 confirmations: 1. The **Attestor network** detects the confirmed deposit 2. Each Attestor independently verifies the transaction 3. When a threshold of Attestors confirm (via `ConfirmDepositAction` on the CBTC Governance module), CBTC is **automatically minted** to your Canton Party 4. No further action is required from you This process typically takes 60 to 90 minutes, depending on Bitcoin block times. *** ## Step 6: Check Your CBTC Balance ### Using cbtc-lib ```rust use cbtc::active_contracts; let holdings = active_contracts::get(active_contracts::Params { ledger_host: ledger_host.clone(), party: party_id.clone(), access_token: access_token.clone(), instrument_id: cbtc::InstrumentId { admin: decentralized_party_id.clone(), id: cbtc::CBTC_TICKER.to_string(), }, // `None` reads every holding the party owns. account: None, }).await?; println!("CBTC holdings: {} contract(s)", holdings.len()); ``` ### Using the Canton API directly Query active contracts filtered by the token holding interface: ```bash curl -X POST "${LEDGER_HOST}/v2/state/active-contracts" \ -H "Authorization: Bearer ${ACCESS_TOKEN}" \ -H "Content-Type: application/json" \ -d '{ "eventFormat": { "filtersByParty": { "'"${PARTY_ID}"'": { "cumulative": [{ "identifierFilter": { "InterfaceFilter": { "value": { "interfaceId": "#splice-api-token-holding-v1:Splice.Api.Token.HoldingV1:Holding", "includeInterfaceView": true, "includeCreatedEventBlob": true } } } }] } }, "verbose": false }, "activeAtOffset": '"${LATEST_OFFSET}"' }' ``` :::note[Filtering required] This query returns all token holdings, including Canton Coin (CC). To isolate your CBTC balance, you must filter the results client-side by the CBTC `instrumentId`. The `cbtc-lib` library handles this automatically via `active_contracts::get`. There is no single curl that can query and filter for CBTC holdings in one step. The `activeAtOffset` must be set to the actual latest offset from your ledger. ::: :::note[UTXO model] CBTC uses a UTXO model similar to Bitcoin. Your balance may be spread across multiple holding contracts (soft limit of 10 UTXOs per party per token type). Use the `cbtc::consolidate` module to merge UTXOs, or `cbtc::split` to divide them. ::: *** ## Step 7: Transfer CBTC Between Canton Parties A CBTC transfer has one of two outcomes. The registry creates a transfer offer, and the receiver accepts it. Or the registry settles the transfer on submission, and the receiver has nothing to accept. The registry settles on submission for a self transfer and for a receiver that pre-approved the sender. `transfer::submit` returns a `TransferReceipt`, and its `outcome` field tells you which outcome occurred. ### Phase 1: Submit the transfer (sender) ```rust use cbtc::transfer; let receipt = transfer::submit(transfer::Params { transfer: cbtc::Transfer { sender: sender_party_id.clone(), receiver: receiver_party_id.clone(), amount: cbtc::DamlDecimal::parse("0.01")?, instrument_id: cbtc::InstrumentId { admin: decentralized_party_id.clone(), id: "CBTC".to_string(), }, requested_at: chrono::Utc::now().to_rfc3339(), execute_before: (chrono::Utc::now() + chrono::Duration::hours(168)).to_rfc3339(), input_holding_cids: None, meta: None, }, ledger_host: ledger_host.clone(), access_token: access_token.clone(), registry_url: registry_url.clone(), decentralized_party_id: decentralized_party_id.clone(), }).await?; ``` ### Phase 2: Accept the transfer (receiver) Do this step only when `receipt.outcome` is `TransferOutcome::Pending`. `receipt.outcome.transfer_offer_cid()` returns the offer ID. A `Completed` outcome leaves no offer to accept. ```rust use cbtc::accept; accept::submit(accept::Params { transfer_offer_contract_id: transfer_contract_id.clone(), receiver_party: receiver_party_id.clone(), ledger_host: ledger_host.clone(), access_token: receiver_access_token.clone(), registry_url: registry_url.clone(), decentralized_party_id: decentralized_party_id.clone(), }).await?; ``` :::note[No curl example for transfers] The raw API transfer flow requires 5-6 sequential API calls with contract disclosures and is too complex to represent as a single curl example. Use `cbtc-lib` for transfers, or refer to the [Canton Utility docs](https://docs.digitalasset.com/utilities/mainnet/index.html) for the full API sequence. ::: :::note[This is a free-of-payment (FOP) transfer] CBTC moves in one direction with nothing exchanged in return. If you need **delivery-versus-payment** — where CBTC only moves if a second leg moves atomically with it — use the `cbtc::allocation` module instead. See [DvP Settlement Using Allocations](https://docs.bitsafe.finance/developers/integration-guides) in the Integration Guides. ::: *** ## Redeem CBTC: Convert Wrapped Bitcoin Back to BTC To convert CBTC back to BTC (this also requires a Minter credential): 1. **Create a withdraw account** specifying your Bitcoin destination address using the `cbtc::mint_redeem::redeem` module 2. **Submit the withdrawal** which burns CBTC on Canton 3. The **Attestor network** detects the burn and constructs a Bitcoin transaction 4. Attestors sign the transaction via threshold signing (FROST) 5. The BTC transaction is broadcast to the Bitcoin network ### Using cbtc-lib ```rust use cbtc::mint_redeem::redeem; // 1. Create a withdraw account with your BTC destination address let withdraw_account = redeem::create_withdraw_account(redeem::CreateWithdrawAccountParams { ledger_host: ledger_host.clone(), party: party_id.clone(), user_name: username.clone(), access_token: access_token.clone(), account_rules_contract_id: rules.wa_rules.contract_id.clone(), account_rules_template_id: rules.wa_rules.template_id.clone(), account_rules_created_event_blob: rules.wa_rules.created_event_blob.clone(), destination_btc_address: btc_destination_address.clone(), credential_cids: minter_credential_cids.clone(), }).await?; // 2. Submit the withdrawal (burns CBTC, Attestors process BTC payout) let updated_account = redeem::submit_withdraw(redeem::SubmitWithdrawParams { ledger_host: ledger_host.clone(), party: party_id.clone(), user_name: username.clone(), access_token: access_token.clone(), api_url: api_url.clone(), withdraw_account_contract_id: withdraw_account.contract_id.clone(), amount: cbtc::DamlDecimal::parse("0.001")?, holding_contract_ids: holding_ids, credential_cids: Some(minter_credential_cids.clone()), }).await?; println!("Pending balance: {}", updated_account.pending_balance); ``` ### Using the Canton API directly Submit a `CBTCWithdrawAccount_Withdraw` command. You can get the correct `extraArgs` and contract disclosures from an Attestor's `GET /cbtc/v1/token-standard-contracts` endpoint. The `contractIds`, `templateIds`, and `blobs` in this example are for illustration only: ```bash curl -X POST "${LEDGER_HOST}/v2/commands/submit-and-wait-for-transaction" \ --header 'Authorization: Bearer ${ACCESS_TOKEN}' \ --header 'Content-Type: application/json' \ --data '{ "commands": { "commands": [ { "ExerciseCommand": { "templateId": "#cbtc:CBTC.WithdrawAccount:CBTCWithdrawAccount", "contractId": "${WA_CID}", "choice": "CBTCWithdrawAccount_Withdraw", "choiceArgument": { "amount": "${AMOUNT}", "tokens": [ "${INPUT_HOLDING}" ], "burnMintFactoryCid": "${ALLOCATION_FACTORY_CID}", "extraArgs": { "context": { "values": { "utility.digitalasset.com/instrument-configuration": { "tag": "AV_ContractId", "value": "00da61fcfa2d9b358c606f040a1d635fbabe4265d33908744a148a80be0dcdc383ca111220e86787467ef7be665f68b813a30de6b0480955dcb514ef29832720618375dee5" }, "utility.digitalasset.com/app-reward-configuration": { "tag": "AV_ContractId", "value": "00bee23612f3c82dd6091e64ffde81cb535e7b446d7ebdf6d91329502c6023d1cdca1112209569dade5e20bf97f963882f6387293034a82f716d2b0df28820a82048f5f86c" }, "utility.digitalasset.com/featured-app-right": { "tag": "AV_ContractId", "value": "001c6e92181f8de9e4d15956e33f90db3085c518747de627134b6850459bf3662fca111220ee87bf1e3b05ed4d3f8a6c336290660f23409cb8d11a028e1073137eac8f78bf" }, "utility.digitalasset.com/issuer-credentials": { "tag": "AV_List", "value": [ { "tag": "AV_ContractId", "value": "0058feffeeaa48cc5526c723c4877af4f6abe3c76131c54ba0d63c6da299f8681bca111220b7032514b6b448d75ea6d9eefe01f0a345504e897a5f2e72fabf974322b20b07" } ] } } }, "meta": { "values": { "splice.lfdecentralizedtrust.org/reason": "CBTC Burn" } } } } } } ], "actAs": [ "${OWNER_PARTY}" ], "commandId": "someCommandId", "disclosedContracts": [ { "templateId": "82798df018301852704f210b97adaabf76d3ecd37d889e1bf96b5f31a20eea34:Utility.Registry.App.V0.Service.AllocationFactory:AllocationFactory", "contractId": "00d58a5f061f086b3c4b405b57ca08f4cefcb7f3a27a26089be6388eb62ee619a8ca1112200991d565daa04ca691901bc04238a8655e2c068039130e4c00027eac2675d9f4", "createdEventBlob": "CgMyLjEShwYKRQDVil8GHwhrPEtAW1fKCPTO/LfzonomCJvmOI62LuYZqMoREiAJkdVl2qBMppGQG8BCOKhlXiwGgDkTDkwAAn6sJnXZ9BIXdXRpbGl0eS1yZWdpc3RyeS1hcHAtdjAajQEKQDgyNzk4ZGYwMTgzMDE4NTI3MDRmMjEwYjk3YWRhYWJmNzZkM2VjZDM3ZDg4OWUxYmY5NmI1ZjMxYTIwZWVhMzQSB1V0aWxpdHkSCFJlZ2lzdHJ5EgNBcHASAlYwEgdTZXJ2aWNlEhFBbGxvY2F0aW9uRmFjdG9yeRoRQWxsb2NhdGlvbkZhY3RvcnkioQJqngIKVgpUOlJjYnRjLW5ldHdvcms6OjEyMjAyYTgzYzZmNDA4MjIxN2MxNzVlMjliYzUzZGE1ZjI3MDNiYTI2NzU3NzhhYjk5MjE3YTVhODgxYTk0OTIwM2ZmClYKVDpSY2J0Yy1uZXR3b3JrOjoxMjIwMmE4M2M2ZjQwODIyMTdjMTc1ZTI5YmM1M2RhNWYyNzAzYmEyNjc1Nzc4YWI5OTIxN2E1YTg4MWE5NDkyMDNmZgpsCmo6aGF1dGgwXzAwN2M2NWY4NTdmMWMzZDU5OWNiNmRmNzM3NzU6OjEyMjBkMmQ3MzJkMDQyYzI4MWNlZTgwZjQ4M2FiODBmM2NiYWE0NzgyODYwZWQ1ZjRkYzIyOGFiMDNkZWRkMmVlOGY5KlJjYnRjLW5ldHdvcms6OjEyMjAyYTgzYzZmNDA4MjIxN2MxNzVlMjliYzUzZGE1ZjI3MDNiYTI2NzU3NzhhYjk5MjE3YTVhODgxYTk0OTIwM2ZmMmhhdXRoMF8wMDdjNjVmODU3ZjFjM2Q1OTljYjZkZjczNzc1OjoxMjIwZDJkNzMyZDA0MmMyODFjZWU4MGY0ODNhYjgwZjNjYmFhNDc4Mjg2MGVkNWY0ZGMyMjhhYjAzZGVkZDJlZThmOTlubOVh5DkGAEIqCiYKJAgBEiCdDhxHJbSFz7Snbvg8xLkPDPvaP3wl+HzTfq2LxHAGmRAe", "synchronizerId": "" }, { "templateId": "3ca1343ab26b453d38c8adb70dca5f1ead8440c42b59b68f070786955cbf9ec1:Splice.Amulet:FeaturedAppRight", "contractId": "001c6e92181f8de9e4d15956e33f90db3085c518747de627134b6850459bf3662fca111220ee87bf1e3b05ed4d3f8a6c336290660f23409cb8d11a028e1073137eac8f78bf", "createdEventBlob": "CgMyLjESvQQKRQAcbpIYH43p5NFZVuM/kNswhcUYdH3mJxNLaFBFm/NmL8oREiDuh78eOwXtTT+KbDNikGYPI0CcuNEaAo4QcxN+rI94vxINc3BsaWNlLWFtdWxldBpkCkAzY2ExMzQzYWIyNmI0NTNkMzhjOGFkYjcwZGNhNWYxZWFkODQ0MGM0MmI1OWI2OGYwNzA3ODY5NTVjYmY5ZWMxEgZTcGxpY2USBkFtdWxldBoQRmVhdHVyZWRBcHBSaWdodCKqAWqnAQpNCks6SURTTzo6MTIyMGJlNThjMjllNjVkZTQwYmYyNzNiZTFkYzJiMjY2ZDQzYTlhMDAyZWE1YjE4OTU1YWVlZjdhYWM4ODFiYjQ3MWEKVgpUOlJjYnRjLW5ldHdvcms6OjEyMjAyYTgzYzZmNDA4MjIxN2MxNzVlMjliYzUzZGE1ZjI3MDNiYTI2NzU3NzhhYjk5MjE3YTVhODgxYTk0OTIwM2ZmKklEU086OjEyMjBiZTU4YzI5ZTY1ZGU0MGJmMjczYmUxZGMyYjI2NmQ0M2E5YTAwMmVhNWIxODk1NWFlZWY3YWFjODgxYmI0NzFhMlJjYnRjLW5ldHdvcms6OjEyMjAyYTgzYzZmNDA4MjIxN2MxNzVlMjliYzUzZGE1ZjI3MDNiYTI2NzU3NzhhYjk5MjE3YTVhODgxYTk0OTIwM2ZmOVDK9pNvQQYAQioKJgokCAESIOo7ddJGewmnI6M13zqEh5d8VRVxWJ73gao2y0uty955EB4=", "synchronizerId": "" }, { "templateId": "ed73d5b9ab717333f3dbd122de7be3156f8bf2614a67360c3dd61fc0135133fa:Utility.Registry.V0.Configuration.Instrument:InstrumentConfiguration", "contractId": "00da61fcfa2d9b358c606f040a1d635fbabe4265d33908744a148a80be0dcdc383ca111220e86787467ef7be665f68b813a30de6b0480955dcb514ef29832720618375dee5", "createdEventBlob": "CgMyLjESnwkKRQDaYfz6LZs1jGBvBAodY1+6vkJl0zkIdEoUioC+Dc3Dg8oREiDoZ4dGfve+Zl9ouBOjDeawSAlV3LUU7ymDJyBhg3Xe5RITdXRpbGl0eS1yZWdpc3RyeS12MBqNAQpAZWQ3M2Q1YjlhYjcxNzMzM2YzZGJkMTIyZGU3YmUzMTU2ZjhiZjI2MTRhNjczNjBjM2RkNjFmYzAxMzUxMzNmYRIHVXRpbGl0eRIIUmVnaXN0cnkSAlYwEg1Db25maWd1cmF0aW9uEgpJbnN0cnVtZW50GhdJbnN0cnVtZW50Q29uZmlndXJhdGlvbiK9BWq6BQpsCmo6aGF1dGgwXzAwN2M2NWY4NTdmMWMzZDU5OWNiNmRmNzM3NzU6OjEyMjBkMmQ3MzJkMDQyYzI4MWNlZTgwZjQ4M2FiODBmM2NiYWE0NzgyODYwZWQ1ZjRkYzIyOGFiMDNkZWRkMmVlOGY5ClYKVDpSY2J0Yy1uZXR3b3JrOjoxMjIwMmE4M2M2ZjQwODIyMTdjMTc1ZTI5YmM1M2RhNWYyNzAzYmEyNjc1Nzc4YWI5OTIxN2E1YTg4MWE5NDkyMDNmZgpWClQ6UmNidGMtbmV0d29yazo6MTIyMDJhODNjNmY0MDgyMjE3YzE3NWUyOWJjNTNkYTVmMjcwM2JhMjY3NTc3OGFiOTkyMTdhNWE4ODFhOTQ5MjAzZmYKhAEKgQFqfwpWClQ6UmNidGMtbmV0d29yazo6MTIyMDJhODNjNmY0MDgyMjE3YzE3NWUyOWJjNTNkYTVmMjcwM2JhMjY3NTc3OGFiOTkyMTdhNWE4ODFhOTQ5MjAzZmYKCAoGQgRDQlRDChsKGUIXUmVnaXN0cmFySW50ZXJuYWxTY2hlbWUKigEKhwFahAEKgQFqfwpWClQ6UmNidGMtbmV0d29yazo6MTIyMDJhODNjNmY0MDgyMjE3YzE3NWUyOWJjNTNkYTVmMjcwM2JhMjY3NTc3OGFiOTkyMTdhNWE4ODFhOTQ5MjAzZmYKCAoGQgRDQlRDChsKGUIXUmVnaXN0cmFySW50ZXJuYWxTY2hlbWUKBAoCWgAKBAoCWgAKegp4UnYKdFpyCnBqbgpaClg6VmNidGMtYmVuZWZpY2lhcnk6OjEyMjBmYTg1NDNkYjZjNjZmZTNhNTViMWYxODBjOGRmYzdmODc2MjY1Yzc2Njg0ZmJjMWQzNWQ4OWUwMmM4YWFmZThlChAKDjIMMS4wMDAwMDAwMDAwKlJjYnRjLW5ldHdvcms6OjEyMjAyYTgzYzZmNDA4MjIxN2MxNzVlMjliYzUzZGE1ZjI3MDNiYTI2NzU3NzhhYjk5MjE3YTVhODgxYTk0OTIwM2ZmMmhhdXRoMF8wMDdjNjVmODU3ZjFjM2Q1OTljYjZkZjczNzc1OjoxMjIwZDJkNzMyZDA0MmMyODFjZWU4MGY0ODNhYjgwZjNjYmFhNDc4Mjg2MGVkNWY0ZGMyMjhhYjAzZGVkZDJlZThmOTnz2t5E5kEGAEIqCiYKJAgBEiAb19AdEjIoV/7xtMY8A2/BkXnnQHGPcCNC0UEu/b5/YxAe", "synchronizerId": "" }, { "templateId": "77df4e7b980c12de438d7b052141a762215fae790d81f71179c8fb534beb68f7:Utility.Credential.V0.Credential:Credential", "contractId": "0058feffeeaa48cc5526c723c4877af4f6abe3c76131c54ba0d63c6da299f8681bca111220b7032514b6b448d75ea6d9eefe01f0a345504e897a5f2e72fabf974322b20b07", "createdEventBlob": "CgMyLjESjQgKRQBY/v/uqkjMVSbHI8SHevT2q+PHYTHFS6DWPG2imfhoG8oREiC3AyUUtrRI116m2e7+AfCjRVBOiXpfLnL6v5dDIrILBxIVdXRpbGl0eS1jcmVkZW50aWFsLXYwGnMKQDc3ZGY0ZTdiOTgwYzEyZGU0MzhkN2IwNTIxNDFhNzYyMjE1ZmFlNzkwZDgxZjcxMTc5YzhmYjUzNGJlYjY4ZjcSB1V0aWxpdHkSCkNyZWRlbnRpYWwSAlYwEgpDcmVkZW50aWFsGgpDcmVkZW50aWFsIuwDaukDCloKWDpWaUJUQy12YWxpZGF0b3ItMTo6MTIyMGZhODU0M2RiNmM2NmZlM2E1NWIxZjE4MGM4ZGZjN2Y4NzYyNjVjNzY2ODRmYmMxZDM1ZDg5ZTAyYzhhYWZlOGUKVgpUOlJjYnRjLW5ldHdvcms6OjEyMjAyYTgzYzZmNDA4MjIxN2MxNzVlMjliYzUzZGE1ZjI3MDNiYTI2NzU3NzhhYjk5MjE3YTVhODgxYTk0OTIwM2ZmChIKEEIOY2J0Yy1wcm92LWhhY2sKDgoMQgpXb3JrYXJvdW5kCgQKAlIACgQKAlIACoQBCoEBWn8KfWp7ClYKVEJSY2J0Yy1uZXR3b3JrOjoxMjIwMmE4M2M2ZjQwODIyMTdjMTc1ZTI5YmM1M2RhNWYyNzAzYmEyNjc1Nzc4YWI5OTIxN2E1YTg4MWE5NDkyMDNmZgoTChFCD2hhc1JlZ2lzdHJ5Um9sZQoMCgpCCFByb3ZpZGVyCnwKemp4CnYKdGJyCnAKajpoYXV0aDBfMDA3YzY1Zjg1N2YxYzNkNTk5Y2I2ZGY3Mzc3NTo6MTIyMGQyZDczMmQwNDJjMjgxY2VlODBmNDgzYWI4MGYzY2JhYTQ3ODI4NjBlZDVmNGRjMjI4YWIwM2RlZGQyZWU4ZjkSAgoAKlJjYnRjLW5ldHdvcms6OjEyMjAyYTgzYzZmNDA4MjIxN2MxNzVlMjliYzUzZGE1ZjI3MDNiYTI2NzU3NzhhYjk5MjE3YTVhODgxYTk0OTIwM2ZmKlZpQlRDLXZhbGlkYXRvci0xOjoxMjIwZmE4NTQzZGI2YzY2ZmUzYTU1YjFmMTgwYzhkZmM3Zjg3NjI2NWM3NjY4NGZiYzFkMzVkODllMDJjOGFhZmU4ZTJoYXV0aDBfMDA3YzY1Zjg1N2YxYzNkNTk5Y2I2ZGY3Mzc3NTo6MTIyMGQyZDczMmQwNDJjMjgxY2VlODBmNDgzYWI4MGYzY2JhYTQ3ODI4NjBlZDVmNGRjMjI4YWIwM2RlZGQyZWU4Zjk5iBIJ/7RABgBCKgomCiQIARIgwrTBnrlaL0STx5Hh0v7BEmbbCERCZDgwJWqqcljhQZ0QHg==", "synchronizerId": "" } ] } }' ``` *** ## Additional Operations The `cbtc-lib` library provides several utility modules for managing your CBTC holdings: | Module | Purpose | | ------------------------ | ------------------------------------------------- | | `cbtc::batch` | Batch operations for sending CBTC from a CSV file | | `cbtc::distribute` | Distribute CBTC across multiple parties | | `cbtc::consolidate` | Merge multiple UTXO holdings into fewer contracts | | `cbtc::split` | Split a single holding into multiple UTXOs | | `cbtc::active_contracts` | Query your current CBTC holdings | *** ## Troubleshooting
My deposit has not been minted after 90 minutes * Verify the BTC transaction has at least 6 confirmations on a block explorer * Confirm you sent to the correct deposit address (from Step 3) * Check that your Canton participant node is connected and syncing * Escalation: contact [support@bitsafe.finance](mailto:support@bitsafe.finance)
Transfer offer is not appearing for the receiver * The receiver must be registered in the DA Registry with a valid credential * Confirm the receiver's Party ID is correct * Check that both parties are connected to the same Canton sync domain
"Insufficient holdings" error when sending * CBTC uses a UTXO model. You may need to consolidate holdings first using `cbtc::consolidate` * Check your balance with `cbtc::active_contracts` to verify available amounts
Authentication token expired * Keycloak tokens have a limited lifetime. Re-authenticate using Step 1 before retrying the operation
*** ## Next Steps * [**CBTC Minting and Burning**](https://docs.bitsafe.finance/developers/cbtc-minting-and-burning) - The same mint and burn flows in more depth, with error handling and recovery patterns for production * [**API Reference**](https://docs.bitsafe.finance/developers/cbtc-api-reference) - Canton Ledger API endpoints, instrument IDs, rate limits, and error codes * [**SDK Setup and Installation**](https://docs.bitsafe.finance/developers/sdk-setup-and-installation) - Full `cbtc-lib` and `canton-lib` module reference * [**Authentication Guide**](https://docs.bitsafe.finance/developers/cbtc-authentication) - Detailed Keycloak setup and an Auth0 community example * [**Integration Guides**](https://docs.bitsafe.finance/developers/integration-guides) - Patterns for DeFi protocols, wallets, custody, and trading systems * [**Withdraw via curl**](/developers/cbtc-quick-start/withdraw-curl/) - The raw API withdrawal sequence, without the SDK *** :::note[Need help?] Reach out to [support@bitsafe.finance](mailto:support@bitsafe.finance) ::: --- # Withdraw curl URL: https://docs.bitsafe.finance/developers/cbtc-quick-start/withdraw-curl/ You can get the correct extraArgs and contract disclosures from the BitSafe API's `/cbtc/v1/token-standard-contracts` endpoint. So the contractIds, templateIds, and blobs in this example are just for example: ```bash curl -X POST '${LEDGER_HOST}/v2/commands/submit-and-wait-for-transaction-tree' \ --header 'Authorization: Bearer ${ACCESS_TOKEN}' \ --data '{ "commands": [ { "ExerciseCommand": { "templateId": "#cbtc:CBTC.WithdrawAccount:CBTCWithdrawAccount", "contractId": "${WA_CID}", "choice": "CBTCWithdrawAccount_Withdraw", "choiceArgument": { "amount": "${AMOUNT}", "tokens": [ "${INPUT_HOLDING}" ], "burnMintFactoryCid": "${ALLOCATION_FACTORY_CID}", "extraArgs": { "context": { "values": { "utility.digitalasset.com/instrument-configuration": { "tag": "AV_ContractId", "value": "00da61fcfa2d9b358c606f040a1d635fbabe4265d33908744a148a80be0dcdc383ca111220e86787467ef7be665f68b813a30de6b0480955dcb514ef29832720618375dee5" }, "utility.digitalasset.com/app-reward-configuration": { "tag": "AV_ContractId", "value": "00bee23612f3c82dd6091e64ffde81cb535e7b446d7ebdf6d91329502c6023d1cdca1112209569dade5e20bf97f963882f6387293034a82f716d2b0df28820a82048f5f86c" }, "utility.digitalasset.com/featured-app-right": { "tag": "AV_ContractId", "value": "001c6e92181f8de9e4d15956e33f90db3085c518747de627134b6850459bf3662fca111220ee87bf1e3b05ed4d3f8a6c336290660f23409cb8d11a028e1073137eac8f78bf" }, "utility.digitalasset.com/issuer-credentials": { "tag": "AV_List", "value": [ { "tag": "AV_ContractId", "value": "0058feffeeaa48cc5526c723c4877af4f6abe3c76131c54ba0d63c6da299f8681bca111220b7032514b6b448d75ea6d9eefe01f0a345504e897a5f2e72fabf974322b20b07" } ] } } }, "meta": { "values": { "splice.lfdecentralizedtrust.org/reason": "CBTC Burn" } } } } } } ], "actAs": [ "${OWNER_PARTY}" ], "commandId": "someCommandId", "disclosedContracts": [ { "templateId": "82798df018301852704f210b97adaabf76d3ecd37d889e1bf96b5f31a20eea34:Utility.Registry.App.V0.Service.AllocationFactory:AllocationFactory", "contractId": "00d58a5f061f086b3c4b405b57ca08f4cefcb7f3a27a26089be6388eb62ee619a8ca1112200991d565daa04ca691901bc04238a8655e2c068039130e4c00027eac2675d9f4", "createdEventBlob": "CgMyLjEShwYKRQDVil8GHwhrPEtAW1fKCPTO/LfzonomCJvmOI62LuYZqMoREiAJkdVl2qBMppGQG8BCOKhlXiwGgDkTDkwAAn6sJnXZ9BIXdXRpbGl0eS1yZWdpc3RyeS1hcHAtdjAajQEKQDgyNzk4ZGYwMTgzMDE4NTI3MDRmMjEwYjk3YWRhYWJmNzZkM2VjZDM3ZDg4OWUxYmY5NmI1ZjMxYTIwZWVhMzQSB1V0aWxpdHkSCFJlZ2lzdHJ5EgNBcHASAlYwEgdTZXJ2aWNlEhFBbGxvY2F0aW9uRmFjdG9yeRoRQWxsb2NhdGlvbkZhY3RvcnkioQJqngIKVgpUOlJjYnRjLW5ldHdvcms6OjEyMjAyYTgzYzZmNDA4MjIxN2MxNzVlMjliYzUzZGE1ZjI3MDNiYTI2NzU3NzhhYjk5MjE3YTVhODgxYTk0OTIwM2ZmClYKVDpSY2J0Yy1uZXR3b3JrOjoxMjIwMmE4M2M2ZjQwODIyMTdjMTc1ZTI5YmM1M2RhNWYyNzAzYmEyNjc1Nzc4YWI5OTIxN2E1YTg4MWE5NDkyMDNmZgpsCmo6aGF1dGgwXzAwN2M2NWY4NTdmMWMzZDU5OWNiNmRmNzM3NzU6OjEyMjBkMmQ3MzJkMDQyYzI4MWNlZTgwZjQ4M2FiODBmM2NiYWE0NzgyODYwZWQ1ZjRkYzIyOGFiMDNkZWRkMmVlOGY5KlJjYnRjLW5ldHdvcms6OjEyMjAyYTgzYzZmNDA4MjIxN2MxNzVlMjliYzUzZGE1ZjI3MDNiYTI2NzU3NzhhYjk5MjE3YTVhODgxYTk0OTIwM2ZmMmhhdXRoMF8wMDdjNjVmODU3ZjFjM2Q1OTljYjZkZjczNzc1OjoxMjIwZDJkNzMyZDA0MmMyODFjZWU4MGY0ODNhYjgwZjNjYmFhNDc4Mjg2MGVkNWY0ZGMyMjhhYjAzZGVkZDJlZThmOTlubOVh5DkGAEIqCiYKJAgBEiCdDhxHJbSFz7Snbvg8xLkPDPvaP3wl+HzTfq2LxHAGmRAe", "synchronizerId": "" }, { "templateId": "3ca1343ab26b453d38c8adb70dca5f1ead8440c42b59b68f070786955cbf9ec1:Splice.Amulet:FeaturedAppRight", "contractId": "001c6e92181f8de9e4d15956e33f90db3085c518747de627134b6850459bf3662fca111220ee87bf1e3b05ed4d3f8a6c336290660f23409cb8d11a028e1073137eac8f78bf", "createdEventBlob": "CgMyLjESvQQKRQAcbpIYH43p5NFZVuM/kNswhcUYdH3mJxNLaFBFm/NmL8oREiDuh78eOwXtTT+KbDNikGYPI0CcuNEaAo4QcxN+rI94vxINc3BsaWNlLWFtdWxldBpkCkAzY2ExMzQzYWIyNmI0NTNkMzhjOGFkYjcwZGNhNWYxZWFkODQ0MGM0MmI1OWI2OGYwNzA3ODY5NTVjYmY5ZWMxEgZTcGxpY2USBkFtdWxldBoQRmVhdHVyZWRBcHBSaWdodCKqAWqnAQpNCks6SURTTzo6MTIyMGJlNThjMjllNjVkZTQwYmYyNzNiZTFkYzJiMjY2ZDQzYTlhMDAyZWE1YjE4OTU1YWVlZjdhYWM4ODFiYjQ3MWEKVgpUOlJjYnRjLW5ldHdvcms6OjEyMjAyYTgzYzZmNDA4MjIxN2MxNzVlMjliYzUzZGE1ZjI3MDNiYTI2NzU3NzhhYjk5MjE3YTVhODgxYTk0OTIwM2ZmKklEU086OjEyMjBiZTU4YzI5ZTY1ZGU0MGJmMjczYmUxZGMyYjI2NmQ0M2E5YTAwMmVhNWIxODk1NWFlZWY3YWFjODgxYmI0NzFhMlJjYnRjLW5ldHdvcms6OjEyMjAyYTgzYzZmNDA4MjIxN2MxNzVlMjliYzUzZGE1ZjI3MDNiYTI2NzU3NzhhYjk5MjE3YTVhODgxYTk0OTIwM2ZmOVDK9pNvQQYAQioKJgokCAESIOo7ddJGewmnI6M13zqEh5d8VRVxWJ73gao2y0uty955EB4=", "synchronizerId": "" }, { "templateId": "ed73d5b9ab717333f3dbd122de7be3156f8bf2614a67360c3dd61fc0135133fa:Utility.Registry.V0.Configuration.Instrument:InstrumentConfiguration", "contractId": "00da61fcfa2d9b358c606f040a1d635fbabe4265d33908744a148a80be0dcdc383ca111220e86787467ef7be665f68b813a30de6b0480955dcb514ef29832720618375dee5", "createdEventBlob": "CgMyLjESnwkKRQDaYfz6LZs1jGBvBAodY1+6vkJl0zkIdEoUioC+Dc3Dg8oREiDoZ4dGfve+Zl9ouBOjDeawSAlV3LUU7ymDJyBhg3Xe5RITdXRpbGl0eS1yZWdpc3RyeS12MBqNAQpAZWQ3M2Q1YjlhYjcxNzMzM2YzZGJkMTIyZGU3YmUzMTU2ZjhiZjI2MTRhNjczNjBjM2RkNjFmYzAxMzUxMzNmYRIHVXRpbGl0eRIIUmVnaXN0cnkSAlYwEg1Db25maWd1cmF0aW9uEgpJbnN0cnVtZW50GhdJbnN0cnVtZW50Q29uZmlndXJhdGlvbiK9BWq6BQpsCmo6aGF1dGgwXzAwN2M2NWY4NTdmMWMzZDU5OWNiNmRmNzM3NzU6OjEyMjBkMmQ3MzJkMDQyYzI4MWNlZTgwZjQ4M2FiODBmM2NiYWE0NzgyODYwZWQ1ZjRkYzIyOGFiMDNkZWRkMmVlOGY5ClYKVDpSY2J0Yy1uZXR3b3JrOjoxMjIwMmE4M2M2ZjQwODIyMTdjMTc1ZTI5YmM1M2RhNWYyNzAzYmEyNjc1Nzc4YWI5OTIxN2E1YTg4MWE5NDkyMDNmZgpWClQ6UmNidGMtbmV0d29yazo6MTIyMDJhODNjNmY0MDgyMjE3YzE3NWUyOWJjNTNkYTVmMjcwM2JhMjY3NTc3OGFiOTkyMTdhNWE4ODFhOTQ5MjAzZmYKhAEKgQFqfwpWClQ6UmNidGMtbmV0d29yazo6MTIyMDJhODNjNmY0MDgyMjE3YzE3NWUyOWJjNTNkYTVmMjcwM2JhMjY3NTc3OGFiOTkyMTdhNWE4ODFhOTQ5MjAzZmYKCAoGQgRDQlRDChsKGUIXUmVnaXN0cmFySW50ZXJuYWxTY2hlbWUKigEKhwFahAEKgQFqfwpWClQ6UmNidGMtbmV0d29yazo6MTIyMDJhODNjNmY0MDgyMjE3YzE3NWUyOWJjNTNkYTVmMjcwM2JhMjY3NTc3OGFiOTkyMTdhNWE4ODFhOTQ5MjAzZmYKCAoGQgRDQlRDChsKGUIXUmVnaXN0cmFySW50ZXJuYWxTY2hlbWUKBAoCWgAKBAoCWgAKegp4UnYKdFpyCnBqbgpaClg6VmNidGMtYmVuZWZpY2lhcnk6OjEyMjBmYTg1NDNkYjZjNjZmZTNhNTViMWYxODBjOGRmYzdmODc2MjY1Yzc2Njg0ZmJjMWQzNWQ4OWUwMmM4YWFmZThlChAKDjIMMS4wMDAwMDAwMDAwKlJjYnRjLW5ldHdvcms6OjEyMjAyYTgzYzZmNDA4MjIxN2MxNzVlMjliYzUzZGE1ZjI3MDNiYTI2NzU3NzhhYjk5MjE3YTVhODgxYTk0OTIwM2ZmMmhhdXRoMF8wMDdjNjVmODU3ZjFjM2Q1OTljYjZkZjczNzc1OjoxMjIwZDJkNzMyZDA0MmMyODFjZWU4MGY0ODNhYjgwZjNjYmFhNDc4Mjg2MGVkNWY0ZGMyMjhhYjAzZGVkZDJlZThmOTnz2t5E5kEGAEIqCiYKJAgBEiAb19AdEjIoV/7xtMY8A2/BkXnnQHGPcCNC0UEu/b5/YxAe", "synchronizerId": "" }, { "templateId": "77df4e7b980c12de438d7b052141a762215fae790d81f71179c8fb534beb68f7:Utility.Credential.V0.Credential:Credential", "contractId": "0058feffeeaa48cc5526c723c4877af4f6abe3c76131c54ba0d63c6da299f8681bca111220b7032514b6b448d75ea6d9eefe01f0a345504e897a5f2e72fabf974322b20b07", "createdEventBlob": "CgMyLjESjQgKRQBY/v/uqkjMVSbHI8SHevT2q+PHYTHFS6DWPG2imfhoG8oREiC3AyUUtrRI116m2e7+AfCjRVBOiXpfLnL6v5dDIrILBxIVdXRpbGl0eS1jcmVkZW50aWFsLXYwGnMKQDc3ZGY0ZTdiOTgwYzEyZGU0MzhkN2IwNTIxNDFhNzYyMjE1ZmFlNzkwZDgxZjcxMTc5YzhmYjUzNGJlYjY4ZjcSB1V0aWxpdHkSCkNyZWRlbnRpYWwSAlYwEgpDcmVkZW50aWFsGgpDcmVkZW50aWFsIuwDaukDCloKWDpWaUJUQy12YWxpZGF0b3ItMTo6MTIyMGZhODU0M2RiNmM2NmZlM2E1NWIxZjE4MGM4ZGZjN2Y4NzYyNjVjNzY2ODRmYmMxZDM1ZDg5ZTAyYzhhYWZlOGUKVgpUOlJjYnRjLW5ldHdvcms6OjEyMjAyYTgzYzZmNDA4MjIxN2MxNzVlMjliYzUzZGE1ZjI3MDNiYTI2NzU3NzhhYjk5MjE3YTVhODgxYTk0OTIwM2ZmChIKEEIOY2J0Yy1wcm92LWhhY2sKDgoMQgpXb3JrYXJvdW5kCgQKAlIACgQKAlIACoQBCoEBWn8KfWp7ClYKVEJSY2J0Yy1uZXR3b3JrOjoxMjIwMmE4M2M2ZjQwODIyMTdjMTc1ZTI5YmM1M2RhNWYyNzAzYmEyNjc1Nzc4YWI5OTIxN2E1YTg4MWE5NDkyMDNmZgoTChFCD2hhc1JlZ2lzdHJ5Um9sZQoMCgpCCFByb3ZpZGVyCnwKemp4CnYKdGJyCnAKajpoYXV0aDBfMDA3YzY1Zjg1N2YxYzNkNTk5Y2I2ZGY3Mzc3NTo6MTIyMGQyZDczMmQwNDJjMjgxY2VlODBmNDgzYWI4MGYzY2JhYTQ3ODI4NjBlZDVmNGRjMjI4YWIwM2RlZGQyZWU4ZjkSAgoAKlJjYnRjLW5ldHdvcms6OjEyMjAyYTgzYzZmNDA4MjIxN2MxNzVlMjliYzUzZGE1ZjI3MDNiYTI2NzU3NzhhYjk5MjE3YTVhODgxYTk0OTIwM2ZmKlZpQlRDLXZhbGlkYXRvci0xOjoxMjIwZmE4NTQzZGI2YzY2ZmUzYTU1YjFmMTgwYzhkZmM3Zjg3NjI2NWM3NjY4NGZiYzFkMzVkODllMDJjOGFhZmU4ZTJoYXV0aDBfMDA3YzY1Zjg1N2YxYzNkNTk5Y2I2ZGY3Mzc3NTo6MTIyMGQyZDczMmQwNDJjMjgxY2VlODBmNDgzYWI4MGYzY2JhYTQ3ODI4NjBlZDVmNGRjMjI4YWIwM2RlZGQyZWU4Zjk5iBIJ/7RABgBCKgomCiQIARIgwrTBnrlaL0STx5Hh0v7BEmbbCERCZDgwJWqqcljhQZ0QHg==", "synchronizerId": "" }, { "templateId": "ed73d5b9ab717333f3dbd122de7be3156f8bf2614a67360c3dd61fc0135133fa:Utility.Registry.V0.Configuration.AppReward:AppRewardConfiguration", "contractId": "00bee23612f3c82dd6091e64ffde81cb535e7b446d7ebdf6d91329502c6023d1cdca1112209569dade5e20bf97f963882f6387293034a82f716d2b0df28820a82048f5f86c", "createdEventBlob": "CgMyLjESigcKRQC+4jYS88gt1gkeZP/egctTXntEbX699tkTKVAsYCPRzcoREiCVadreXiC/l/ljiC9jhykwNKgvcW0rDfKIIKggSPX4bBITdXRpbGl0eS1yZWdpc3RyeS12MBqLAQpAZWQ3M2Q1YjlhYjcxNzMzM2YzZGJkMTIyZGU3YmUzMTU2ZjhiZjI2MTRhNjczNjBjM2RkNjFmYzAxMzUxMzNmYRIHVXRpbGl0eRIIUmVnaXN0cnkSAlYwEg1Db25maWd1cmF0aW9uEglBcHBSZXdhcmQaFkFwcFJld2FyZENvbmZpZ3VyYXRpb24iqgNqpwMKbApqOmhhdXRoMF8wMDdjNjVmODU3ZjFjM2Q1OTljYjZkZjczNzc1OjoxMjIwZDJkNzMyZDA0MmMyODFjZWU4MGY0ODNhYjgwZjNjYmFhNDc4Mjg2MGVkNWY0ZGMyMjhhYjAzZGVkZDJlZThmOQpWClQ6UmNidGMtbmV0d29yazo6MTIyMDJhODNjNmY0MDgyMjE3YzE3NWUyOWJjNTNkYTVmMjcwM2JhMjY3NTc3OGFiOTkyMTdhNWE4ODFhOTQ5MjAzZmYK3gEK2wFq2AEKTQpLOklEU086OjEyMjBiZTU4YzI5ZTY1ZGU0MGJmMjczYmUxZGMyYjI2NmQ0M2E5YTAwMmVhNWIxODk1NWFlZWY3YWFjODgxYmI0NzFhCoYBCoMBaoABCmwKajpoYXV0aDBfMDA3YzY1Zjg1N2YxYzNkNTk5Y2I2ZGY3Mzc3NTo6MTIyMGQyZDczMmQwNDJjMjgxY2VlODBmNDgzYWI4MGYzY2JhYTQ3ODI4NjBlZDVmNGRjMjI4YWIwM2RlZGQyZWU4ZjkKEAoOMgwwLjIwMDAwMDAwMDAqaGF1dGgwXzAwN2M2NWY4NTdmMWMzZDU5OWNiNmRmNzM3NzU6OjEyMjBkMmQ3MzJkMDQyYzI4MWNlZTgwZjQ4M2FiODBmM2NiYWE0NzgyODYwZWQ1ZjRkYzIyOGFiMDNkZWRkMmVlOGY5MlJjYnRjLW5ldHdvcms6OjEyMjAyYTgzYzZmNDA4MjIxN2MxNzVlMjliYzUzZGE1ZjI3MDNiYTI2NzU3NzhhYjk5MjE3YTVhODgxYTk0OTIwM2ZmOTNRkpGtQQYAQioKJgokCAESIEkSmOztxETzHu7k7YoYrhYmnA4xZxW6uqMAl1xkvmiOEB4=", "synchronizerId": "" } ] }' ``` --- # CBTC Testnet Guide URL: https://docs.bitsafe.finance/developers/cbtc-testnet-guide/ :::caution[API Disclaimer] CBTC APIs are subject to change. Testnet behavior may differ from mainnet in some respects (see Parity section below). ::: --- ## Overview: CBTC Testnet for Developers The CBTC testnet is a sandbox environment where developers can experiment with the full mint, burn, and transfer lifecycle using **test BTC** with no real funds at risk. We recommend all integrations start on testnet before deploying to mainnet. --- ## How to Get Testnet CBTC: Three Options ### Option 1: CBTC Testnet Faucet (Recommended) The fastest way to get testnet tokens: [**CBTC Testnet Faucet →**](https://faucet.bitsafe.finance/) Simply enter your testnet wallet address and receive testnet CBTC and CC (for gas) instantly. :::note[Quick and easy] No setup required. Just enter your address and go. ::: ### Option 2: Bron Wallet Testnet Environment If the faucet is unavailable or you want a full testnet wallet environment: 1. **Create a new workspace** in [Bron Wallet](https://bron.app/) 1. Enable **Developer settings → Testnet mode** during workspace creation 1. **Create a testnet account** (toggle Testnet ON in account settings) 1. Select a **Trusted third party** (e.g., Qrypt) for key recovery 1. Use the faucet to fund your new testnet account ### Option 3: Mint via Testnet Flow You can also mint testnet CBTC through the same flow as mainnet, using testnet BTC. This is useful for testing the full minting integration: 1. Set up your participant pointing at the **testnet** Canton network 1. Install CBTC DAR files 1. Follow the standard minting flow (see [Minting and Burning Guide](https://docs.bitsafe.finance/developers/cbtc-minting-and-burning)) 1. Use testnet BTC from a Bitcoin testnet faucet --- ## Testnet Environment Details | Property | Testnet | Mainnet | | --- | --- | --- | | **Registry URL** | [`https://api.utilities.digitalasset-staging.com`](https://api.utilities.digitalasset-staging.com/) | [`https://api.utilities.digitalasset.com`](https://api.utilities.digitalasset.com/) | | **Coordinator URL** | [`https://testnet.dlc.link/attestor-1`](https://testnet.dlc.link/attestor-1) | [`https://mainnet.dlc.link/attestor-1`](https://mainnet.dlc.link/attestor-1) | | **Instrument ID (admin)** | `cbtc-network::12201b17...508f` | `cbtc-network::12205af3...b262` | | **BTC network** | Bitcoin Testnet | Bitcoin Mainnet | | **Faucet** | [faucet.bitsafe.finance](https://faucet.bitsafe.finance/) | N/A (real BTC required) | ### Testnet Instrument ID (Full) ```json { "instrument_id": { "admin": "cbtc-network::12201b1741b63e2494e4214cf0bedc3d5a224da53b3bf4d76dba468f8e97eb15508f", "id": "CBTC" }, "registry_url": "https://api.utilities.digitalasset-staging.com" } ``` --- ## Testnet vs. Mainnet: What Is the Same and What Differs :::note Understanding what is the same and what differs between testnet and mainnet is critical for a smooth production launch. ::: ### What Is Identical * **DAR files:** Same CBTC Daml packages * **API surface:** Same Canton Ledger API endpoints and Daml template interfaces * **Mint and burn flows:** Same step-by-step process * **Governance model:** Same Attestor threshold approval mechanism * **Token standard:** CIP-56 compliant on both networks ### What Differs * **Attestor set:** Testnet runs a **smaller** Attestor set than mainnet * **Confirmation times:** May be faster on testnet due to less Bitcoin network congestion * **Instrument IDs:** Different across networks - always fetch from the metadata URL, never hardcode * **BTC:** Testnet uses test BTC with no real value * **Faucet availability:** Testnet has a faucet; mainnet requires real BTC ### What Is Mocked or Unavailable on Testnet * **Real BTC settlement:** No real Bitcoin is involved * **Production Attestor SLAs:** Testnet Attestors do not carry the same uptime guarantees * **Mainnet fee structure:** Fees on testnet may not reflect production costs --- ## Important Operational Notes :::caution[Testnet may be reset without notice] Do not rely on testnet state for production planning. Testnet CBTC balances and transaction history may not persist across resets. ::: * Testnet is for **development and testing only** * Do not use testnet data for compliance, reporting, or production decisions * Testnet performance is not indicative of mainnet performance --- ## Migrate from CBTC Testnet to Mainnet: Step-by-Step Checklist When your testnet integration is working, the migration to mainnet involves: 1. **Update your participant config** to point at the mainnet Canton network 1. **Update Instrument IDs** to mainnet values (see [API Reference](https://docs.bitsafe.finance/developers/cbtc-api-reference)) 1. **Update Coordinator URL** to [`https://mainnet.dlc.link/attestor-1`](https://mainnet.dlc.link/attestor-1) 1. **Use real BTC** for minting - the flow is identical 1. **Review authentication** - ensure your production OIDC provider is configured 1. **Test with a small amount first** - mint a minimal amount of CBTC on mainnet before going live --- ## Devnet There is also a **devnet** environment for earlier-stage experimentation. Devnet is less stable than testnet and may be updated more frequently. **Coordinator URL:** [`https://devnet.dlc.link/attestor-2`](https://devnet.dlc.link/attestor-2) ```json { "instrument_id": { "admin": "cbtc-network::12202a83c6f4082217c175e29bc53da5f2703ba2675778ab99217a5a881a949203ff", "id": "CBTC" }, "registry_url": "https://api.utilities.digitalasset-dev.com" } ``` --- ## Troubleshooting | Issue | Resolution | | --- | --- | | Faucet not working | Use Bron Wallet testnet setup (Option 2) or contact [support@bitsafe.finance](mailto:support@bitsafe.finance) | | Testnet CBTC balance disappeared | Testnet may have been reset - request new tokens from the faucet | | Minting on testnet takes too long | Check Bitcoin testnet block times - they can be irregular | | Cannot connect to testnet participant | Verify your participant config points to the correct testnet endpoints | **Support:** [support@bitsafe.finance](mailto:support@bitsafe.finance) --- --- # CBTC Minting and Burning URL: https://docs.bitsafe.finance/developers/cbtc-minting-and-burning/ :::caution[API Disclaimer] CBTC APIs are subject to change. There is no formal versioning policy today. Breaking changes are communicated via the site changelog. ::: *** ## Overview: The Full BTC to CBTC Lifecycle This guide covers the complete lifecycle of converting Bitcoin to CBTC and back: minting (BTC to CBTC on Canton) and burning (CBTC back to BTC). For a quick end-to-end walkthrough, see the [CBTC Quick Start](https://docs.bitsafe.finance/developers/cbtc-quick-start). This guide goes deeper into each step, covering edge cases, error handling, and recovery patterns for production integrations. :::note[Prerequisite: install the SDK] The Rust examples on this page use the `cbtc-lib` SDK. See [SDK Setup and Installation](https://docs.bitsafe.finance/developers/sdk-setup-and-installation) for installing `cbtc-lib` and `canton-lib`, uploading the CBTC DAR files, and configuring your environment. ::: **Key facts:** * **Exchange rate:** 1 BTC = 1 CBTC, always * **Confirmations required:** 6 Bitcoin block confirmations (\~60 minutes) * **Processing time:** Additional 60-120 seconds after confirmations for Attestor verification * **Wallet requirement:** Taproot-compatible Bitcoin wallet (P2TR addresses) * **Transaction limits:** 0.0001 BTC minimum, 5 BTC maximum by default - set per account and adjustable on request (see below) * **Minter credential:** Required before you can create a deposit or withdraw account (see below) *** ## Transaction Limits Mint and burn amounts are bounded by **per-account limits**. The defaults are: | Limit | Default | | ----------- | ---------- | | **Minimum** | 0.0001 BTC | | **Maximum** | 5 BTC | :::note[Limits are adjustable] These are defaults, not fixed protocol constraints. If your integration needs a different range, contact [sales@bitsafe.finance](mailto:sales@bitsafe.finance) to have your account limits modified. ::: ### Read limits from the account, do not hardcode them Because limits are set per account and can be changed on request, **read them at runtime rather than hardcoding the defaults**. They are carried on the Deposit Account (for minting) and the Withdraw Account (for burning), and are returned by the deposit account status call: ```rust use cbtc::mint_redeem::mint; let status = mint::get_deposit_account_status(mint::GetDepositAccountStatusParams { ledger_host: ledger_host.clone(), party: party_id.clone(), access_token: access_token.clone(), api_url: api_url.clone(), account_contract_id: deposit_account.contract_id.clone(), }).await?; if let Some(limits) = &status.limits { println!("Min: {:?} | Max: {:?}", limits.min_amount, limits.max_amount); } ``` Both fields are optional. `None` means that bound is not enforced for the account: ```rust pub struct Limits { pub min_amount: Option, // serialised as "minAmount" pub max_amount: Option, // serialised as "maxAmount" } ``` ### Validate before submitting `cbtc::mint_redeem::models::check_limits` validates an amount against a set of limits locally, so an out-of-range request fails in your code instead of being rejected downstream: ```rust use cbtc::mint_redeem::models::check_limits; check_limits("Withdraw", amount.clone(), &withdraw_account.limits)?; ``` It returns a descriptive error - `"Withdraw amount 0.00001 is below minimum 0.0001"` or `"... exceeds maximum 5"` - and succeeds when no limits are set. *** ## Prerequisite: Obtain a Minter Credential :::caution[Minting and burning require a Minter credential] This is a hard requirement, not an optional step. Creating a deposit account or a withdraw account will fail without one. Transferring, receiving, and holding CBTC do **not** require a credential — only minting and burning do. ::: A Minter credential is a Daml contract issued to your Canton party by the **CBTC registrar**. It carries a claim with the property `hasCBTCRole` and the value `Minter`, and you pass its contract ID into the account-creation calls. ### How to request one Minter credentials are issued as part of commercial onboarding. To request one, contact the BitSafe team at [sales@bitsafe.finance](mailto:sales@bitsafe.finance) with your Canton Party ID and target environment (testnet or mainnet). ### Check whether you already hold one Once the registrar has issued your credential, use the `cbtc::credentials` module to find it. A credential is a Minter credential if any of its claims has `property == "hasCBTCRole"` and `value == "Minter"`: ```rust use cbtc::credentials::{list_credentials, ListCredentialsParams}; let credentials = list_credentials(ListCredentialsParams { ledger_host: ledger_host.clone(), party: party_id.clone(), access_token: access_token.clone(), }).await?; let minter_credential_cids: Vec = credentials .iter() .filter(|c| { c.claims .iter() .any(|claim| claim.property == "hasCBTCRole" && claim.value == "Minter") }) .map(|c| c.contract_id.clone()) .collect(); if minter_credential_cids.is_empty() { return Err("No Minter credential found for this party".into()); } ``` ### Accept a pending credential offer The registrar issues the credential as an **offer** that your party must accept before it becomes active. If `list_credentials` returns nothing, check for a pending offer and accept it: ```rust use cbtc::credentials::{ accept_credential_offer, find_user_service, list_credential_offers, AcceptCredentialOfferParams, FindUserServiceParams, ListCredentialOffersParams, }; let user_service = find_user_service(FindUserServiceParams { ledger_host: ledger_host.clone(), party: party_id.clone(), access_token: access_token.clone(), }).await?; let offers = list_credential_offers(ListCredentialOffersParams { ledger_host: ledger_host.clone(), party: party_id.clone(), access_token: access_token.clone(), }).await?; accept_credential_offer(AcceptCredentialOfferParams { ledger_host: ledger_host.clone(), party: party_id.clone(), access_token: access_token.clone(), user_service_contract_id: user_service.contract_id.clone(), user_service_template_id: user_service.template_id.clone(), credential_offer_cid: offers[0].contract_id.clone(), }).await?; ``` :::note[Accepting a credential is permanent] It creates a persistent on-ledger contract with no archive choice, so a credential cannot be un-accepted. Accept only the offer you actually intend to use. ::: A complete runnable version of this flow is in the library's [`credentials` example](https://github.com/DLC-link/cbtc-lib/blob/v0.9.0/examples/credentials.rs). *** ## How to Mint CBTC: Deposit Bitcoin and Receive Wrapped BTC on Canton ### How It Works ```mermaid sequenceDiagram participant Dev as Your App participant Canton as Canton Ledger API participant BTC as Bitcoin Network participant Att as Attestor Network Dev->>Canton: 1. Authenticate (get JWT) Dev->>Canton: 2. Create Deposit Account Canton-->>Dev: Deposit Account ID Dev->>Canton: 3. Request BTC Deposit Address Canton-->>Dev: Taproot address (P2TR) Dev->>BTC: 4. Send BTC to address BTC-->>Att: 5. Attestors monitor for 6 confirmations Att->>Canton: 6. Submit ConfirmDepositAction (threshold) Canton-->>Dev: 7. CBTC minted to your party ``` ### Step-by-Step Step 1: Authenticate Obtain a JWT token from your OIDC provider (Keycloak is officially supported). See the [Authentication Guide](https://docs.bitsafe.finance/developers/cbtc-authentication) for setup details. Step 2: Create a Deposit Account A Deposit Account is required before you can generate deposit addresses. This call requires the Minter credential contract IDs obtained in the prerequisite step above. **Using cbtc-lib (Rust):** ```rust use cbtc::mint_redeem::{mint, attestor}; // First get account rules from the Attestor let account_rules = attestor::get_account_contract_rules(&api_url).await?; let deposit_account = mint::create_deposit_account(mint::CreateDepositAccountParams { ledger_host: ledger_host.clone(), party: party_id.clone(), user_name: username.clone(), access_token: access_token.clone(), account_rules, credential_cids: minter_credential_cids.clone(), }).await?; println!("Deposit Account ID: {}", deposit_account.contract_id); ``` **Using Canton API (curl):** You can fetch the CBTCDepositAccountRules from the BitSafe API's `/cbtc/v1/account-contract-rules` endpoint :::caution[A Minter credential is required] The `CreateDepositAccount` choice takes your Minter credential contract IDs as an argument. See [Prerequisite: Obtain a Minter Credential](/developers/cbtc-minting-and-burning/#prerequisite-obtain-a-minter-credential) above. Requests without a valid credential are rejected. ::: ```bash curl -X POST "${LEDGER_HOST}/v2/commands/submit-and-wait-for-transaction" \ --header 'Authorization: Bearer ${ACCESS_TOKEN}' \ --header 'Content-Type: application/json' \ --data '{ "commands": { "commands": [ { "ExerciseCommand": { "templateId": "#cbtc:CBTC.DepositAccount:CBTCDepositAccountRules", "contractId": "${DA_RULES_CID}", "choice": "CBTCDepositAccountRules_CreateDepositAccount", "choiceArgument": { "owner" : "${OWNER_PARTY}", "credentialCids": ["${MINTER_CREDENTIAL_CID}"] } } } ], "actAs": [ "${OWNER_PARTY}" ], "commandId": "someCommandID", "disclosedContracts": [ { "templateId": "#cbtc:CBTC.DepositAccount:CBTCDepositAccountRules", "contractId": "${DA_RULES_CID}", "createdEventBlob": "${DA_RULES_BLOB}", "synchronizerId": "" } ] } }' ``` :::note Note: This sample uses the submit-and-wait-for-transaction endpoint. Canton deprecated the submit-and-wait-for-transaction-tree endpoint in 3.4. Canton 3.6 disables it by default, and Canton 3.7 removes it. ::: Step 3: Generate a Bitcoin Deposit Address Each deposit address is unique to your account and is a standard **Taproot (P2TR)** address. **Using cbtc-lib (Rust):** ```rust use cbtc::mint_redeem::mint; let btc_address = mint::get_bitcoin_address(mint::GetBitcoinAddressParams { api_url: api_url.clone(), account_id: deposit_account.contract_id.clone(), }).await?; println!("Send BTC to: {}", btc_address); ``` Step 4: Send Bitcoin Send the exact amount of BTC you want to mint as CBTC to the generated Taproot address from your Bitcoin wallet. Step 5: Wait for Confirmations The Attestor network automatically monitors the Bitcoin network. Once your transaction reaches **6 confirmations** (\~60 minutes), it transitions to the processing state. You can poll for deposit status: **Using cbtc-lib (Rust):** ```rust use cbtc::mint_redeem::mint; let status = mint::get_deposit_account_status(mint::GetDepositAccountStatusParams { ledger_host: ledger_host.clone(), party: party_id.clone(), access_token: access_token.clone(), api_url: api_url.clone(), account_contract_id: deposit_account.contract_id.clone(), }).await?; println!("Bitcoin address: {} | Last processed block: {}", status.bitcoin_address, status.last_processed_bitcoin_block); ``` Step 6: Attestor Verification This step is fully automated. The Attestor network: 1. Independently verifies the Bitcoin transaction has 6+ confirmations 2. Each Attestor submits a `ConfirmDepositAction` to the Canton governance module 3. Once the required threshold of confirmations is reached, the Coordinator executes the mint **No action is required from your application during this step.** Step 7: CBTC Available Your CBTC is minted and available in your Canton party. Check your balance: **Using cbtc-lib (Rust):** ```rust use cbtc::active_contracts; let holdings = active_contracts::get(active_contracts::Params { ledger_host: ledger_host.clone(), party: party_id.clone(), access_token: access_token.clone(), instrument_id: cbtc::InstrumentId { admin: decentralized_party_id.clone(), id: cbtc::CBTC_TICKER.to_string(), }, account: None, // None reads every holding the party owns }).await?; println!("CBTC holdings: {} contract(s)", holdings.len()); ``` *** ## How to Burn CBTC: Redeem Wrapped Bitcoin for Native BTC ### How It Works ```mermaid sequenceDiagram participant Dev as Your App participant Canton as Canton Ledger API participant Att as Attestor Network participant BTC as Bitcoin Network Dev->>Canton: 1. Create WithdrawAccount (set BTC destination address) Dev->>Canton: 2. Submit withdrawal against WithdrawAccount Canton->>Att: 3. Attestors verify and approve withdrawal Att->>Att: 4. FROST threshold signing of BTC transaction Att->>BTC: 5. Broadcast signed transaction BTC-->>Dev: 6. BTC arrives after 6 confirmations ``` ### Step-by-Step Step 1: Initiate a Burn First, create a **WithdrawAccount** with your destination BTC address. The destination address is stored on the WithdrawAccount and can be updated later. Then submit the withdrawal against that account. Like deposit account creation, this requires your Minter credential contract IDs. **Using cbtc-lib (Rust):** ```rust use cbtc::mint_redeem::redeem; // Step 1: Create a withdraw account let withdraw_account = redeem::create_withdraw_account(redeem::CreateWithdrawAccountParams { ledger_host: ledger_host.clone(), party: party_id.clone(), user_name: username.clone(), access_token: access_token.clone(), account_rules_contract_id: rules.wa_rules.contract_id.clone(), account_rules_template_id: rules.wa_rules.template_id.clone(), account_rules_created_event_blob: rules.wa_rules.created_event_blob.clone(), destination_btc_address: btc_destination_address.clone(), credential_cids: minter_credential_cids.clone(), }).await?; // Step 2: Submit the withdrawal (burns CBTC, Attestor network processes BTC payout) let updated_account = redeem::submit_withdraw(redeem::SubmitWithdrawParams { ledger_host: ledger_host.clone(), party: party_id.clone(), user_name: username.clone(), access_token: access_token.clone(), api_url: api_url.clone(), withdraw_account_contract_id: withdraw_account.contract_id.clone(), amount: cbtc::DamlDecimal::parse("0.001")?, holding_contract_ids: holding_ids, credential_cids: Some(minter_credential_cids.clone()), }).await?; println!("Withdrawal submitted. Pending balance: {}", updated_account.pending_balance); ``` :::note[Amounts are `DamlDecimal`] Build them with `cbtc::DamlDecimal::parse`, which validates the value against Daml's decimal precision rules up front, so an unrepresentable amount fails locally instead of being rejected by the ledger. This applies to transfer and allocation amounts too. ::: Step 2: Attestor Verification and Signing The Attestor network: 1. Verifies the burn request on Canton 2. Constructs the Bitcoin withdrawal transaction 3. Coordinates FROST threshold signing across Attestors 4. Once the signing threshold is met, broadcasts the signed transaction to the Bitcoin network **This step is fully automated. No action required.** Step 3: Bitcoin Delivery After the signed transaction is broadcast, wait for 6 Bitcoin confirmations. Your BTC will arrive at the specified destination address. *** ## Error Handling and Recovery Patterns for CBTC Integrations :::note[Error handling is critical for production integrations] The CBTC system includes built-in resilience, but your application should handle these scenarios gracefully. ::: ### Failed Broadcast The system includes **automatic retry logic**. If a Bitcoin transaction fails to broadcast initially, the Coordinator detects the failure during subsequent periodic checks (every 60-120 seconds) and rebroadcasts using stored transaction data. **What your app should do:** Monitor withdrawal status. If status remains in `broadcasting` for more than 10 minutes, log an alert for investigation. ### Insufficient Confirmations If a deposit stalls below 6 confirmations (e.g., due to Bitcoin network congestion), the system simply waits. There is no timeout. **What your app should do:** Display the current confirmation count to the user. Consider showing an estimated time based on current Bitcoin block times. ### Idempotency Each withdrawal generates a **unique transaction ID** that prevents accidental double-spending, even if network issues cause retry attempts. The system is designed to be idempotent. **What your app should do:** Store the withdrawal request ID and use it for status checks rather than initiating duplicate requests. ### Attestor Timeout If governance approval is delayed (e.g., some Attestors are temporarily offline), the system continues to collect approvals. As long as the threshold can eventually be met, the operation will complete. **What your app should do:** If a mint or burn is pending for more than 2 hours, escalate to BitSafe support. ### Partial Failure If some Attestors approve but the threshold is not reached (e.g., too many Attestors offline simultaneously), the operation will remain pending until the threshold is met or the situation is resolved. **What your app should do:** Alert your operations team. Contact [support@bitsafe.finance](mailto:support@bitsafe.finance). *** ## CBTC UTXO Management: Consolidation and Best Practices :::caution[Important for high-volume integrations] Each CBTC transfer creates UTXOs. Canton recommends a maximum of **10 UTXOs per party**. Exceeding this causes increased load and fees on your node. ::: The cbtc-lib Rust library provides functions for managing UTXOs: ```rust use cbtc::consolidate; // Check UTXO count and consolidate if threshold exceeded let result = consolidate::check_and_consolidate(consolidate::CheckConsolidateParams { party: party_id.clone(), instrument_id: cbtc::InstrumentId { admin: decentralized_party_id.clone(), id: cbtc::CBTC_TICKER.to_string(), }, threshold: 10, // Canton's soft limit ledger_host: ledger_host.clone(), access_token: access_token.clone(), registry_url: registry_url.clone(), decentralized_party_id: decentralized_party_id.clone(), }).await?; if result.consolidated { println!("Consolidated {} UTXOs into {}", result.utxos_before, result.utxos_after); } ``` **Best practices:** * Monitor UTXO count per party and consolidate proactively * Batch transfers where possible to minimise UTXO creation * If creating many parties, use the Ledger API directly (not wallet UI/API) - see [Canton docs](https://docs.digitalasset.com/build/3.4/tutorials/json-api/canton_and_the_json_ledger_api_ts.html#allocating-a-party) *** ## Escalation Path | Situation | Action | | ------------------------- | ------------------------------------------------------------------------------- | | Mint pending > 2 hours | Check Bitcoin confirmations first. If 6+ confirmations reached, contact BitSafe | | Burn pending > 2 hours | Contact BitSafe engineering | | Unexpected error from API | Retry with exponential backoff. If persistent, contact BitSafe | | UTXO-related issues | Use cbtc-lib consolidation functions. If unresolved, contact BitSafe | **Support channels:** * **Email:** [support@bitsafe.finance](mailto:support@bitsafe.finance) *** --- # CBTC Authentication URL: https://docs.bitsafe.finance/developers/cbtc-authentication/ :::caution[API Disclaimer] CBTC APIs are subject to change. Authentication flows may evolve as Canton's identity layer matures. ::: *** ## Overview: How Authentication Works for CBTC on Canton All CBTC operations go through the Canton Ledger API, which requires a valid **JWT (JSON Web Token)** for every request. The JWT is issued by an **OIDC (OpenID Connect) provider** connected to your Canton participant node. This guide covers two authentication options for developers building with CBTC and the Canton Network: * **Keycloak** (officially supported by BitSafe) * **Auth0** (community example, not officially maintained) For deeper background on how Canton handles authentication and authorization at the platform level, see the [Canton Authorization Documentation](https://docs.digitalasset.com/build/3.4/sdlc-howtos/applications/secure/authorization.html). *** ## CBTC Authentication Flow: JWT and OIDC ```mermaid sequenceDiagram participant App as Your Application participant OIDC as OIDC Provider
(Keycloak / Auth0) participant Canton as Canton Participant
(Ledger API) App->>OIDC: 1. Request token (client credentials or auth code) OIDC-->>App: 2. JWT access token App->>Canton: 3. API call with Bearer token Canton-->>App: 4. Response ``` *** ## Set Up Keycloak for CBTC Authentication (Officially Supported) ✅ Keycloak is the **officially supported** OIDC provider for CBTC integrations. BitSafe engineering provides support for Keycloak-based authentication. ### Prerequisites * Keycloak instance running and accessible * A realm configured for your Canton participant * A client application registered in Keycloak ### Step 1: Register a Client In your Keycloak admin console: 1. Navigate to your realm → **Clients** → **Create client** 2. Set **Client type** to `OpenID Connect` 3. Set **Client ID** (e.g., `cbtc-minting-app`) 4. Enable **Client authentication** (for server-to-server flows) 5. Under **Service account roles**, enable as needed ### Step 2: Configure Your Canton Participant Your Canton participant must be configured to trust your OIDC provider. Participant configuration is complex and environment-specific. Refer to the official validator operator documentation: [**Canton Validator Operator Guide →**](https://docs.dev.sync.global/validator_operator/index.html) ### Step 3: Obtain a Token **Client Credentials flow** (for server-to-server / backend integrations): ```bash curl -X POST "https:///auth/realms//protocol/openid-connect/token" \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "grant_type=client_credentials" \ -d "client_id=cbtc-minting-app" \ -d "client_secret=$CLIENT_SECRET" ``` **Password grant flow** (for user-facing / interactive applications): ```bash curl -X POST "https:///auth/realms//protocol/openid-connect/token" \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "grant_type=password" \ -d "client_id=cbtc-minting-app" \ -d "username=$KEYCLOAK_USERNAME" \ -d "password=$KEYCLOAK_PASSWORD" ``` **Response** (both flows): ```json { "access_token": "eyJhbGciOiJSUzI1NiIs...", "expires_in": 300, "token_type": "Bearer" } ``` ### Step 4: Use the Token Include the token in all Canton Ledger API calls: ```bash curl -X POST "https:///v2/state/active-contracts" \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{... }' ``` ### Token Refresh Tokens expire (typically 5 minutes for Keycloak). Your application should: 1. Cache the token until near expiry 2. Request a new token before the current one expires 3. Retry failed requests with a fresh token if you receive a `401` *** ## Set Up Auth0 for CBTC Authentication (Community Example) ⚠️ :::note[Auth0 compatibility] Both Keycloak and Auth0 follow the OAuth2/OIDC standard, so the login flow and token usage are identical. There is one known caveat: Auth0 requires an extra `audience` parameter in the token request. The `cbtc-lib` and `canton-lib` libraries **do not pass this parameter by default**, so they won't work out of the box with Auth0. This is a straightforward fix on either the library side or the client side. See the workaround below. BitSafe engineering support covers **Keycloak-based authentication only**. For Auth0-specific configuration issues, refer to [Auth0's documentation](https://auth0.com/docs). ::: ### Prerequisites * Auth0 tenant and API configured * Application registered as **Machine to Machine** (for backend) or **Single Page Application** (for frontend) ### Step 1: Create an Auth0 API In the Auth0 dashboard: 1. Navigate to **Applications** → **APIs** → **Create API** 2. Set **Name** (e.g., `Canton Ledger API`) 3. Set **Identifier** to your participant's Ledger API URL 4. Set **Signing Algorithm** to `RS256` ### Step 2: Register a Machine-to-Machine Application 1. Navigate to **Applications** → **Create Application** 2. Select **Machine to Machine Applications** 3. Authorise the application to call your Canton Ledger API 4. Note the **Client ID** and **Client Secret** ### Step 3: Configure Your Canton Participant Point your participant to Auth0's JWKS endpoint. Participant configuration is complex and environment-specific. Refer to the official validator operator documentation: [**Canton Validator Operator Guide →**](https://docs.dev.sync.global/validator_operator/index.html) ### Step 4: Obtain a Token ```bash curl -X POST "https:///oauth/token" \ -H "Content-Type: application/json" \ -d '{ "client_id": "'$CLIENT_ID'", "client_secret": "'$CLIENT_SECRET'", "audience": "https:///v2/", "grant_type": "client_credentials" }' ``` :::caution[The `audience` parameter is required for Auth0] This is the key difference from Keycloak. Without it, Auth0 will return an opaque token that the Canton participant will reject. Set `audience` to your participant's Ledger API base URL. **If using cbtc-lib / canton-lib:** The Rust libraries' `keycloak::login::password` and `keycloak::login::client_credentials` functions do not pass an `audience` parameter. To use Auth0, you'll need to either: 1. Make the token request directly via HTTP (as shown above) instead of using the library helper 2. Patch the login functions to include the `audience` field, which is a small change A library-level fix may be shipped in a future release of `canton-lib`. ::: ### Step 5: Use the Token Same as Keycloak. Include the Bearer token in all API requests. *** ## Wallet-Based Authentication for Canton dApps For applications that use Canton-compatible wallets (Loop, Console/Zoro, Bron), authentication is handled by the wallet provider. Your application receives a JWT through the wallet's SDK or connect flow. Supported wallets: * **Loop Wallet** * **Console / Zoro Wallet** * **Bron Wallet** * **WalletConnect** (for dApp integrations) * **Node login** (direct participant authentication) See the [Integration Guides](https://docs.bitsafe.finance/developers/integration-guides) for wallet-specific connection patterns. *** ## Troubleshooting | Issue | Cause | Resolution | | ----------------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------- | | `401 Unauthorized` on every request | JWT not trusted by participant | Verify JWKS URL in participant config matches your OIDC provider | | Token expires immediately | Clock skew between OIDC provider and participant | Sync system clocks (NTP) | | CORS errors in browser | Ingress not configured for CORS | Add CORS annotations to your ingress - see Minting App Installation Guide | | `invalid_grant` from OIDC provider | Client secret rotated or incorrect | Regenerate and update client secret | *** ## JWT Security Best Practices for Canton Applications * **Never expose client secrets** in frontend code. Use the Client Credentials flow only from backend services. * **Rotate secrets regularly.** Update client secrets in both your OIDC provider and your application config. * **Use short-lived tokens.** The default 5-minute expiry is appropriate for most use cases. * **Restrict party access.** Configure your JWT claims to limit which Canton parties a token can act as. *** --- # CBTC API Reference URL: https://docs.bitsafe.finance/developers/cbtc-api-reference/ :::caution[API Stability Notice] All endpoints and interfaces are subject to change without notice. There is no formal versioning policy today. Breaking changes are communicated via the site changelog. ::: *** ## CBTC SDK Reference: cbtc-lib (Rust) For most integrations, we recommend using **cbtc-lib** (Rust) rather than raw API calls: * **Repository:** [github.com/DLC-link/cbtc-lib](https://github.com/DLC-link/cbtc-lib) * **Current version:** v0.9.0 * **Crate name:** `cbtc` (add via `cbtc = { git = "ssh://git@github.com/DLC-link/cbtc-lib.git", tag = "v0.9.0" }`) * **Lower-level library:** [github.com/DLC-link/canton-lib](https://github.com/DLC-link/canton-lib) (v0.11.0) * **Code examples:** [github.com/DLC-link/cbtc-lib/tree/main/examples](https://github.com/DLC-link/cbtc-lib/tree/main/examples) * **Setup guide:** [SDK Setup and Installation](https://docs.bitsafe.finance/developers/sdk-setup-and-installation) *** ## Overview: Canton Ledger API for CBTC Operations All CBTC operations (minting, burning, transferring wrapped Bitcoin) are performed through the **Canton Ledger API** (also called the JSON Ledger API). There is no separate "CBTC API." You interact with CBTC by exercising choices on Daml smart contracts running on your Canton participant node. **Base URL:** `https:///v2/` **Authentication:** Bearer token (JWT) from your OIDC provider. See the [Authentication Guide](https://docs.bitsafe.finance/developers/cbtc-authentication). **Content-Type:** `application/json` for all requests. *** ## Prerequisites Before calling any CBTC API: 1. **Canton participant node** running and connected to the network 2. **CBTC DAR files** installed on your participant - [download from GitHub](https://github.com/DLC-link/cbtc-lib/tree/v0.9.0/cbtc-dars) 3. **Valid JWT** from your OIDC provider (Keycloak officially supported) 4. **Party ID** allocated on your participant *** ## Canton Ledger API Endpoints For full endpoint documentation covering the Canton Ledger API (including all endpoints used by CBTC operations), refer to the official Canton documentation: [**Canton JSON Ledger API Documentation →**](https://docs.digitalasset.com/build/3.4/explanations/json-api/index.html) *** ## CBTC Instrument ID Management: Devnet, Testnet, and Mainnet CBTC uses the Canton Token Standard. To interact with CBTC programmatically, you need the correct **Instrument ID** for your target network. :::caution[Instrument IDs differ across networks] (devnet, testnet, mainnet). Always fetch the latest from the metadata URL rather than hardcoding. ::: ### Devnet ```json { "instrument_id": { "admin": "cbtc-network::12202a83c6f4082217c175e29bc53da5f2703ba2675778ab99217a5a881a949203ff", "id": "CBTC" }, "registry_url": "https://api.utilities.digitalasset-dev.com" } ``` **Metadata:** [View](https://api.utilities.digitalasset-dev.com/api/token-standard/v0/registrars/cbtc-network::12202a83c6f4082217c175e29bc53da5f2703ba2675778ab99217a5a881a949203ff/registry/metadata/v1/instruments) ### Testnet ```json { "instrument_id": { "admin": "cbtc-network::12201b1741b63e2494e4214cf0bedc3d5a224da53b3bf4d76dba468f8e97eb15508f", "id": "CBTC" }, "registry_url": "https://api.utilities.digitalasset-staging.com" } ``` **Metadata:** [View](https://api.utilities.digitalasset-staging.com/api/token-standard/v0/registrars/cbtc-network::12201b1741b63e2494e4214cf0bedc3d5a224da53b3bf4d76dba468f8e97eb15508f/registry/metadata/v1/instruments) ### Mainnet ```json { "instrument_id": { "admin": "cbtc-network::12205af3b949a04776fc48cdcc05a060f6bda2e470632935f375d1049a8546a3b262", "id": "CBTC" }, "registry_url": "https://api.utilities.digitalasset.com" } ``` **Metadata:** [View](https://api.utilities.digitalasset.com/api/token-standard/v0/registrars/cbtc-network::12205af3b949a04776fc48cdcc05a060f6bda2e470632935f375d1049a8546a3b262/registry/metadata/v1/instruments) **Token Standard API Reference:** [Canton Token Standard Docs](https://docs.dev.sync.global/app_dev/token_standard/index.html#api-references) :::note[Polling pattern] Instrument IDs can change due to network dynamics (e.g., DAR upgrades). Query the metadata URL periodically rather than hardcoding values. There is currently no push notification for ID changes - this is a known gap. ::: *** ## Rate Limits There are no BitSafe-imposed rate limits on the Canton Ledger API. However: * **Canton network throughput:** Transfers take a few seconds each. Approximately 500 transfers per 10-minute period is near the current practical limit. * **Your participant node:** Performance depends on your infrastructure. Monitor node resource usage under load. *** ## API Error Handling for CBTC Operations | Error | Cause | Resolution | | ------------------- | ----------------------------------- | --------------------------------------- | | `401 Unauthorized` | Invalid or expired JWT | Re-authenticate with your OIDC provider | | `404 Not Found` | Contract ID no longer active | Re-query for current contract IDs | | `409 Conflict` | Duplicate command ID | Use a unique `commandId` per request | | UTXO limit exceeded | Too many UTXOs for a party (max 10) | Consolidate UTXOs using cbtc-lib | *** --- # Instrument ID Management URL: https://docs.bitsafe.finance/developers/instrument-id-management/ --- ## What Are Instrument IDs? Every token on Canton is identified by an **Instrument ID**, a combination of an **admin** party ID and a token **id** string, plus a **registry URL**. These values let any CIP-56-compliant tool discover and interact with CBTC. --- ## Why IDs Change Instrument IDs can change due to network dynamics, including DAR upgrades, network migrations, or infrastructure changes. **Never hardcode Instrument IDs.** Fetch them dynamically from the metadata URL. :::caution There is currently **no push notification** when Instrument IDs change. Poll the metadata URL periodically. ::: --- ## Current IDs by Network ### Devnet * **Registry URL:** [`https://api.utilities.digitalasset-dev.com`](https://api.utilities.digitalasset-dev.com/) * **Coordinator URL:** [`https://devnet.dlc.link/attestor-2`](https://devnet.dlc.link/attestor-2) * **Metadata:** [View](https://api.utilities.digitalasset-dev.com/api/token-standard/v0/registrars/cbtc-network::12202a83c6f4082217c175e29bc53da5f2703ba2675778ab99217a5a881a949203ff/registry/metadata/v1/instruments) ```json { "instrument_id": { "admin": "cbtc-network::12202a83c6f4082217c175e29bc53da5f2703ba2675778ab99217a5a881a949203ff", "id": "CBTC" }, "registry_url": "https://api.utilities.digitalasset-dev.com" } ``` ### Testnet * **Registry URL:** [`https://api.utilities.digitalasset-staging.com`](https://api.utilities.digitalasset-staging.com/) * **Coordinator URL:** [`https://testnet.dlc.link/attestor-1`](https://testnet.dlc.link/attestor-1) * **Metadata:** [View](https://api.utilities.digitalasset-staging.com/api/token-standard/v0/registrars/cbtc-network::12201b1741b63e2494e4214cf0bedc3d5a224da53b3bf4d76dba468f8e97eb15508f/registry/metadata/v1/instruments) ```json { "instrument_id": { "admin": "cbtc-network::12201b1741b63e2494e4214cf0bedc3d5a224da53b3bf4d76dba468f8e97eb15508f", "id": "CBTC" }, "registry_url": "https://api.utilities.digitalasset-staging.com" } ``` ### Mainnet * **Registry URL:** [`https://api.utilities.digitalasset.com`](https://api.utilities.digitalasset.com/) * **Coordinator URL:** [`https://mainnet.dlc.link/attestor-1`](https://mainnet.dlc.link/attestor-1) * **Metadata:** [View](https://api.utilities.digitalasset.com/api/token-standard/v0/registrars/cbtc-network::12205af3b949a04776fc48cdcc05a060f6bda2e470632935f375d1049a8546a3b262/registry/metadata/v1/instruments) ```json { "instrument_id": { "admin": "cbtc-network::12205af3b949a04776fc48cdcc05a060f6bda2e470632935f375d1049a8546a3b262", "id": "CBTC" }, "registry_url": "https://api.utilities.digitalasset.com" } ``` --- ## Recommended Polling Pattern ```rust use std::time::Duration; // Poll every 5 minutes in production const POLL_INTERVAL: Duration = Duration::from_secs(300); async fn refresh_instrument_id(registry_url: &str, admin: &str) -> Result { let url = format!( "{}/api/token-standard/v0/registrars/{}/registry/metadata/v1/instruments", registry_url, admin ); let response = reqwest::get(&url).await?.json::().await?; Ok(response.instrument_id) } ``` **Best practices:** * Cache the Instrument ID locally and refresh on a schedule (every 5-15 minutes) * Log a warning if the ID changes between polls, as this may indicate a DAR upgrade * On startup, always fetch fresh rather than relying on cached values * Handle fetch failures gracefully and use the last known good value --- ## Token Standard API Reference Full documentation for the Canton Token Standard API: [Canton Token Standard Docs](https://docs.dev.sync.global/app_dev/token_standard/index.html#api-references) **Requirements:** CBTC is CIP-56 compliant. No special requirements for holding CBTC. --- --- # Integration Guides URL: https://docs.bitsafe.finance/developers/integration-guides/ :::caution[API Disclaimer] CBTC APIs are subject to change. Label all examples with the SDK version and DAR version they were tested against. ::: *** ## Overview This page provides integration patterns for common CBTC use cases. Each pattern includes architecture notes, key considerations, and pointers to relevant code. For API details, see the [API Reference](https://docs.bitsafe.finance/developers/cbtc-api-reference). For authentication setup, see the [Authentication Guide](https://docs.bitsafe.finance/developers/cbtc-authentication). *** ## Integration Pattern 1: DeFi Protocol **Use case:** Build a DEX, lending platform, or liquidity pool using CBTC as collateral. ### Architecture 1. Your protocol runs on a Canton participant node with CBTC DAR files installed 2. Users deposit CBTC into your protocol's Canton party via a `Transfer` choice 3. Your protocol logic (Daml contracts) manages positions, collateral, and settlement 4. Users withdraw CBTC back to their own party when exiting ### Key Considerations * **UTXO management:** Each transfer creates UTXOs. Keep below 10 per party. Use `cbtc-lib` consolidation functions. * **Instrument ID:** Fetch dynamically - see [Instrument ID Management](https://docs.bitsafe.finance/developers/instrument-id-management) * **Privacy:** Canton transactions are private by default. Only parties to a contract see its details. This eliminates MEV. * **Transfer costs:** \~$3-5 per CBTC transfer on Canton currently. Factor this into your protocol economics. ### Example Partners * **Bron** - BTC-CBTC and CC-CBTC swapping on Canton * **Elk Capital Markets / Triangle** - OTC and app-based CBTC trading * **Silvana** - DEX/trading venue on Canton _(coming soon)_ *** ## Integration Pattern 2: Wallet or Custody Solution **Use case:** Support CBTC in an institutional-grade wallet or custody platform. ### Architecture 1. Wallet connects to a Canton participant via the Ledger API 2. Authentication via OIDC (Keycloak supported, Auth0 community example available) 3. CBTC balances queried via `state-queries` endpoint 4. Transfers executed via `Transfer` choice on CBTC token contracts ### Supported Wallets (Current Ecosystem) * **Loop Wallet** - Canton-native wallet with CBTC support * **Console / Zoro Wallet** - Canton wallet with API access * **Bron Wallet** - Multi-party wallet with testnet support * **WalletConnect** - For dApp-to-wallet connections ### Key Considerations * **External signing:** Available for integration with custody providers (DFNS, Fordefi, Ledger) * **Party creation at scale:** If creating 10+ parties, use the Ledger API directly rather than wallet UI - see [Canton docs](https://docs.digitalasset.com/build/3.4/tutorials/json-api/canton_and_the_json_ledger_api_ts.html#allocating-a-party) * **CORS:** If your wallet makes browser-based API calls, configure CORS on your ingress *** ## Integration Pattern 3: Trading System **Use case:** Build spot trading, perpetual contracts, options, or structured products with CBTC. ### Why Canton for Trading * **No public mempool** - positions are not visible to other participants, eliminating front-running and sandwich attacks (MEV) * **Private transactions** - only parties to a trade see the details * **Audit-ready** - Canton's privacy model supports selective disclosure for compliance ### Architecture 1. Trading engine runs as Daml contracts on Canton 2. CBTC used as settlement or collateral asset 3. Counterparty discovery and matching handled by your protocol 4. Settlement is atomic - either both sides complete or neither does ### Example: Options on CBTC CBTC holders can write covered CALL options, earning premium income while maintaining BTC exposure. Settlement uses Canton's atomic dual-token transfer - the buyer receives the underlying asset while the seller receives payment, atomically. ### DvP Settlement Using Allocations For atomic delivery-versus-payment, `cbtc-lib` provides the `cbtc::allocation` module, which implements the Canton Token Standard allocation lifecycle. This is the mechanism behind the atomic settlement described above. **How it differs from a standard transfer.** The `transfer` / `accept` flow described in the [Quick Start](https://docs.bitsafe.finance/developers/cbtc-quick-start) is **free-of-payment (FOP)**: the sender sends CBTC, and nothing is exchanged in return. The registry either creates an offer that the receiver accepts, or settles the transfer on submission. There is no linkage to a second leg. An **allocation** instead locks CBTC into one leg of a multi-leg settlement that a third party settles atomically, so the CBTC only moves if the other leg moves too. | | FOP transfer (`cbtc::transfer` + `cbtc::accept`) | DvP allocation (`cbtc::allocation`) | | ---------------------- | -------------------------------------------------------- | ----------------------------------------------------- | | **Parties** | Sender, receiver | Sender, receiver, **settlement executor** (the venue) | | **Settled by** | The receiver by accepting, or the registry on submission | The executor, across all legs at once | | **Atomicity** | Single leg only | All legs settle together or none do | | **Sender can reclaim** | Cancel the offer (`cbtc::cancel_offers`) | Withdraw the allocation before settlement | | **Deadlines** | `execute_before` | `allocate_before`, then `settle_before` | **Lifecycle.** The sender locks their leg, then the executor settles: 1. **Allocate** - the leg sender calls `cbtc::allocation::allocate`, which exercises `AllocationFactory_Allocate` and locks the sender's holdings. If no input holdings are specified, the library auto-selects them. The call returns an `AllocationResult`. Its `outcome` is `Completed` with the allocation ID, or `Pending` with an allocation instruction ID. 2. **Execute** - the settlement executor calls `cbtc::allocation::execute_transfer` (`Allocation_ExecuteTransfer`). A coordinating app normally settles every leg together in a single transaction; the library exposes the single-leg choice for that purpose. 3. **Or unwind** - the sender can call `cbtc::allocation::withdraw` (`Allocation_Withdraw`) to reclaim locked holdings before settlement, and `cbtc::allocation::cancel` (`Allocation_Cancel`) releases them back to the sender. **Timing.** An allocation must be funded before `allocate_before` and settled before `settle_before`, which must be the later of the two. Allocating CBTC into a settlement leg: ```rust use cbtc::allocation; use cbtc::types::allocation as spec; let allocation_spec = spec::AllocationSpecification { settlement: spec::SettlementInfo { executor: executor_party_id.clone(), // the venue settling the legs settlement_ref: spec::Reference { id: settlement_ref_id.clone(), cid: None, }, requested_at: now.to_rfc3339(), allocate_before: (now + chrono::Duration::hours(24)).to_rfc3339(), settle_before: (now + chrono::Duration::hours(48)).to_rfc3339(), meta: spec::Metadata::default(), }, transfer_leg_id: "leg0".to_string(), transfer_leg: spec::TransferLeg { sender: sender_party_id.clone(), receiver: receiver_party_id.clone(), amount: cbtc::DamlDecimal::parse("0.1")?, instrument_id: cbtc::InstrumentId { admin: decentralized_party_id.clone(), id: cbtc::CBTC_TICKER.to_string(), }, meta: spec::Metadata::default(), }, }; let result = allocation::allocate(allocation::Params { allocation: allocation_spec, requested_at: now.to_rfc3339(), input_holding_cids: Vec::new(), // empty = library auto-selects the sender's holdings ledger_host: ledger_host.clone(), access_token: access_token.clone(), registry_url: registry_url.clone(), decentralized_party_id: decentralized_party_id.clone(), }).await?; // Keep the returned ID: nothing in the library can look it up afterwards. match result.outcome { allocation::AllocationOutcome::Completed { allocation_cid } => println!("Allocation: {allocation_cid}"), allocation::AllocationOutcome::Pending { allocation_instruction_cid } => println!("Instruction: {allocation_instruction_cid}"), } ``` Reclaiming an allocation before settlement: ```rust use cbtc::allocation; allocation::withdraw(allocation::ActionParams { allocation_contract_id: allocation_cid.clone(), actor_party: sender_party_id.clone(), ledger_host: ledger_host.clone(), access_token: access_token.clone(), registry_url: registry_url.clone(), decentralized_party_id: decentralized_party_id.clone(), }).await?; ``` :::note[No Minter credential needed] Allocations move existing CBTC rather than creating or destroying it, so they do not require the Minter credential that minting and burning do. ::: A complete runnable example is in the library: [`examples/allocate_cbtc.rs`](https://github.com/DLC-link/cbtc-lib/blob/v0.9.0/examples/allocate_cbtc.rs). To reclaim an allocation, see [`examples/withdraw_allocation.rs`](https://github.com/DLC-link/cbtc-lib/blob/v0.9.0/examples/withdraw_allocation.rs). For the underlying standard, see the [Canton Token Standard allocation docs](https://docs.dev.sync.global/app_dev/token_standard/index.html). *** ## Integration Pattern 4: Minting Integration **Use case:** Offer CBTC minting as a service to your users. ### Three Options | Option | Description | Effort | | -------------------------------- | --------------------------------------------------------- | ------------------------- | | **1. Direct API** | Install CBTC DAR, call Canton APIs to mint/redeem | Low - a few hours | | **2. Self-hosted UI** | Install DAR + BitSafe minting UI locally | Medium - more maintenance | | **3. Hosted UI** _(coming soon)_ | Use BitSafe's centrally hosted UI against your validator. | TBD | For Option 1, see the [Minting and Burning Guide](https://docs.bitsafe.finance/developers/cbtc-minting-and-burning) and [API Reference](https://docs.bitsafe.finance/developers/cbtc-api-reference). For Options 2 and 3, contact BitSafe for setup details. *** ## Getting Started 1. **Install the SDK and DAR files** - see [SDK Setup and Installation](https://docs.bitsafe.finance/developers/sdk-setup-and-installation) for `cbtc-lib`, `canton-lib`, DAR upload, and environment configuration 2. **Set up testnet first** - see [Testnet Guide](https://docs.bitsafe.finance/developers/cbtc-testnet-guide) 3. **Mint your first CBTC** - see [Quick Start](https://docs.bitsafe.finance/developers/cbtc-quick-start) 4. **Review examples** - [GitHub examples](https://github.com/DLC-link/cbtc-lib/tree/main/examples) **Need help?** Reach out via [support@bitsafe.finance](mailto:support@bitsafe.finance) *** --- # Technical Reference URL: https://docs.bitsafe.finance/developers/technical-reference/ :::caution ::: *** ## Token Details | Property | Value | | ----------------------- | ---------------------------------------------------------------------------------------------------------- | | **Name** | CBTC (Canton Bitcoin) | | **Standard** | CIP-56 (Token Standard V1) and CIP-112 (Token Standard V2) | | **Backing** | 1:1 with native BTC | | **Network** | Canton Network | | **Deposit requirement** | Taproot-compatible Bitcoin wallet (P2TR) | | **Transaction limits** | 0.0001 BTC minimum, 5 BTC maximum by default. Set per account and adjustable on request | | **Confirmations** | 6 Bitcoin blocks (\~60 minutes) | | **Audit** | [Quantstamp](https://certificate.quantstamp.com/full/cbtc/5d0d805e-8cf0-4a39-bf1a-0e94899b3c1c/index.html) | *** ## Network Environments | Environment | Registry URL | Coordinator URL | Bitcoin Network | | ----------- | --------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | --------------- | | **Devnet** | [`https://api.utilities.digitalasset-dev.com`](https://api.utilities.digitalasset-dev.com/) | [`https://devnet.dlc.link/attestor-2`](https://devnet.dlc.link/attestor-2) | Bitcoin Testnet | | **Testnet** | [`https://api.utilities.digitalasset-staging.com`](https://api.utilities.digitalasset-staging.com/) | [`https://testnet.dlc.link/attestor-1`](https://testnet.dlc.link/attestor-1) | Bitcoin Testnet | | **Mainnet** | [`https://api.utilities.digitalasset.com`](https://api.utilities.digitalasset.com/) | [`https://mainnet.dlc.link/attestor-1`](https://mainnet.dlc.link/attestor-1) | Bitcoin Mainnet | For full Instrument IDs per network, see [Instrument ID Management](https://docs.bitsafe.finance/developers/instrument-id-management). *** ## Canton Network Requirements To interact with CBTC you need: 1. **Canton participant node** - connected to the target network (devnet/testnet/mainnet) 2. **CBTC DAR files** - installed on your participant. All versions must be installed to access all live contract versions. * Download: [github.com/DLC-link/cbtc-lib/tree/v0.9.0/cbtc-dars](https://github.com/DLC-link/cbtc-lib/tree/v0.9.0/cbtc-dars) (latest DAR: `cbtc-1.2.1`) 1. **OIDC provider** - Keycloak (officially supported) or Auth0 (community example) 2. **Canton CLI** - version 3.3.0+ for DAR upload scripts 3. **Prerequisites for CLI:** `jq`, `curl`, `java` (11+) ### DAR Upload ```bash git clone https://github.com/DLC-link/cbtc-lib cd cbtc-lib/cbtc-dars # Edit misc/connect.conf to point to your participant canton run 00_UploadDars.sc -c ./misc/connect.conf ``` The upload script is **idempotent** - safe to re-run. *** ## Fee Structure :::tip[Confirmed: Mint and burn fees are 0%] There are no BitSafe fees on CBTC mint or burn operations. ::: ### Canton Transfer Costs * CBTC transfers on Canton cost approximately **$3-5 per transaction** (network gas, not BitSafe fees) * Cost varies based on payload size and UTXO count * Sending CBTC is generally more expensive than sending Canton Coin (CC) due to larger payload *** ## GitHub Repositories | Repository | Version | Description | Link | | -------------- | ------------ | --------------------------------------------------- | -------------------------------------------------------------------- | | **cbtc-lib** | `v0.9.0` | Rust SDK for CBTC operations (mint, burn, transfer) | [GitHub](https://github.com/DLC-link/cbtc-lib) | | **canton-lib** | `v0.11.0` | Lower-level Canton interaction library | [GitHub](https://github.com/DLC-link/canton-lib/) | | **CBTC DAR** | `cbtc-1.2.1` | Daml packages, upload scripts, connect config | [GitHub](https://github.com/DLC-link/cbtc-lib/tree/v0.9.0/cbtc-dars) | **Note:** The crate name is `cbtc`. DAR versions and crate versions are numbered independently: `cbtc-lib` v0.9.0 ships DAR `cbtc-1.2.1`. *** ## Transfer Speed * Canton transfers take **a few seconds each** * Practical throughput: \~**500 transfers per 10-minute period** * UTXO limit: **10 UTXOs per party** (Canton recommendation). Exceeding this increases load and fees. *** ## External Links * [CBTC Technical Documentation (live site)](https://docs.bitsafe.finance/bitsafe-documentation/product-suite/cbtc) * [Canton Network](https://www.canton.network/) * [Canton Developer Docs](https://docs.digitalasset.com/) * [FROST Whitepaper](https://eprint.iacr.org/2020/852) * [Quantstamp Audit Report](https://certificate.quantstamp.com/full/cbtc/5d0d805e-8cf0-4a39-bf1a-0e94899b3c1c/index.html) * [Canton Whitepaper](https://www.canton.network/whitepapers) * [Chainlink Proof of Reserve (CBTC)](https://data.chain.link/) *** --- # Security Deep Dive URL: https://docs.bitsafe.finance/developers/security-deep-dive/ --- ## Overview CBTC's security model is built on three pillars: **FROST threshold signatures** on the Bitcoin side, a **decentralised Attestor Network** bridging both chains, and **Daml smart contracts** governing all operations on Canton. This page covers each in detail. --- ## FROST Threshold Signatures CBTC uses **FROST** (Flexible Round-Optimised Schnorr Threshold Signatures), a cryptographic protocol formalised in [Komlo & Goldberg, 2020](https://eprint.iacr.org/2020/852) and enabled on Bitcoin via the **Taproot** upgrade. ### How FROST Works FROST is a **two-round signing protocol:** 1. **Round One (Commitment):** The Coordinator selects the message to be signed and the set of participating Attestors. Each Attestor generates fresh nonces and public commitments, sent to the Coordinator. 1. **Round Two (Signature Share):** The Coordinator broadcasts all commitments. Each Attestor verifies them, computes an individual signature share, and sends it back. The Coordinator aggregates shares into a single valid Schnorr signature. ### Why FROST for CBTC * **Taproot-native:** FROST signatures are standard Schnorr signatures, compatible with any Taproot (P2TR) wallet. No special wallet support needed. * **Indistinguishable on-chain:** A FROST threshold signature looks identical to a single-signer Schnorr signature. No one can determine from the blockchain that a threshold scheme was used. * **Smaller and cheaper:** One aggregated signature regardless of threshold size, versus N signatures for traditional on-chain multisig. Lower transaction fees. * **No single point of failure:** The signing key is never reconstructed. Each Attestor holds only a share. ### Security Properties * **Unforgeability:** No coalition below the threshold can produce a valid signature, even with adaptive corruption (formally proven in the ePrint paper) * **Robustness against forgery attacks:** FROST mitigates certain Schnorr-specific threshold forgery vectors * **Forget-and-Forgive protection:** The resharing protocol includes acknowledgement steps preventing split-group attacks during key rotation **Full paper:** [FROST: Flexible Round-Optimized Schnorr Threshold Signatures (ePrint 2020/852)](https://eprint.iacr.org/2020/852) --- ## Attestor Network The Attestor Network is the decentralised security backbone of CBTC. ### Composition * **3 external node operators** (Finoa, Nethermind, DSRV) * **1 BitSafe-operated node** (4 total) * Each Attestor runs nodes on **both** the Bitcoin and Canton networks ### Responsibilities Attestor responsibilities are **almost entirely automated:** * Independent verification of Bitcoin transactions reaching 6 confirmations * Submission of `ConfirmDepositAction` (for mints) and `ArchiveWithdrawRequest` (for burns) to the Canton governance module * Participation in FROST threshold signing for Bitcoin withdrawal transactions * Monitoring deposit accounts and withdrawal requests The only manual process is **governance** - adding or removing Attestor nodes, which requires coordination between operators. ### Threshold Governance * For critical actions (minting, burning), each Attestor submits confirmation **independently** * Confirmations are recorded as Canton contracts * Once the number of valid confirmations meets the **predefined threshold**, the Coordinator executes the action * **No single party** - including BitSafe or the Coordinator - can unilaterally mint, burn, or move BTC ### Coordinator Role The Coordinator is a service (which can be an Attestor or a separate non-signing entity) that: * Executes periodic checks every **60-120 seconds** * Monitors deposit accounts for new Bitcoin transactions * Constructs Bitcoin transactions for withdrawals * Submits governance actions to Canton * Coordinates the FROST signing rounds **The Coordinator cannot act unilaterally.** It facilitates the process but requires threshold approval for every action. --- ## Dual-Network Security Model CBTC's security spans two networks simultaneously: | Layer | Network | Security Mechanism | | --- | --- | --- | | **Bitcoin custody** | Bitcoin L1 | FROST threshold signatures (Taproot) | | **Governance and coordination** | Canton | Daml contracts with threshold confirmation | | **Token operations** | Canton | CIP-56 compliant Daml contracts | The same Attestor network secures both layers, creating seamless security across both blockchains. --- ## Reliability and Safeguards ### Automatic Retry If a Bitcoin transaction fails to broadcast, the Coordinator detects the failure during subsequent checks and rebroadcasts using stored transaction data. ### Idempotent Operations Each withdrawal generates a unique transaction ID preventing double-spending, even with network-induced retries. ### Distributed Verification No single Attestor can block or manipulate operations. The threshold system ensures continued operation even with some nodes offline. --- ## Trust and Threat Model The CBTC system assumes an honest majority of the Attestor network Key trust assumptions: * A threshold of Attestors must be honest and online for the system to operate * The Coordinator facilitates but cannot act unilaterally * BitSafe operates one Attestor node but has no special privileges * Canton's privacy model ensures transaction details are visible only to involved parties ### What Cannot Happen * No single party (including BitSafe) can mint CBTC without genuine BTC deposits * No single party can withdraw BTC without threshold approval * No front-running or MEV - Canton has no public mempool --- ## Audit Reports CBTC smart contracts have been audited by **Quantstamp:** [**View Full Audit Report →**](https://certificate.quantstamp.com/full/cbtc/5d0d805e-8cf0-4a39-bf1a-0e94899b3c1c/index.html) --- ## Further Reading * [FROST Whitepaper (ePrint 2020/852)](https://eprint.iacr.org/2020/852) * [Canton Network Whitepaper](https://www.canton.network/whitepapers) * [Canton Token Standard Docs](https://docs.dev.sync.global/app_dev/token_standard/index.html#api-references) --- --- # Resources URL: https://docs.bitsafe.finance/developers/resources/ --- ## Glossary | Term | Definition | | --- | --- | | **CBTC** | Canton Bitcoin - a 1:1 wrapped BTC token on the Canton Network, issued and redeemed via a decentralised bridge. | | **Canton Network** | A permissioned blockchain built by Digital Asset for institutional finance. Private transactions, no public mempool. | | **CIP-56** | Canton Instrument Protocol - the token standard CBTC complies with, enabling interoperability with any CIP-56-compliant tool. | | **Daml** | The smart contract language used on Canton. CBTC operations are Daml contract choices. | | **DAR file** | Daml Archive - a compiled Daml package that you install on your Canton participant to interact with CBTC contracts. | | **FROST** | Flexible Round-Optimised Schnorr Threshold Signatures - the cryptographic protocol securing CBTC's Bitcoin custody. | | **Attestor** | An independent node operator that verifies Bitcoin transactions and participates in threshold signing for CBTC mint/burn operations. | | **Coordinator** | A service that facilitates Attestor coordination, monitors deposits, and constructs Bitcoin transactions. Cannot act unilaterally. | | **Minter** | A credential granting the right to create deposit accounts and initiate CBTC minting. | | **Instrument ID** | The unique identifier for CBTC on a given Canton network (devnet/testnet/mainnet). Differs per environment. | | **Taproot (P2TR)** | A Bitcoin address type introduced with the Taproot upgrade. Required for CBTC deposit addresses. | | **UTXO** | Unspent Transaction Output. Each CBTC transfer creates UTXOs. Canton recommends max 10 per party. | | **Decentralized Party** | A Canton-native construct where multiple independent operators collectively control a party via threshold signing. | | **ERC-4626** | A tokenised vault standard. BitSafe Vaults implement ERC-4626 semantics on Canton. | | **Curator** | A professional asset manager who operates yield strategies within a BitSafe Vault. | | **LP (Liquidity Provider)** | An institutional depositor who provides capital to a Vault in exchange for shares and yield. | | **MEV** | Maximal Extractable Value - front-running and sandwich attacks possible on public blockchains. Canton eliminates this via private transactions. | --- ## GitHub Repositories * **cbtc-lib** (Rust SDK) - [github.com/DLC-link/cbtc-lib](https://github.com/DLC-link/cbtc-lib) * **canton-lib** (lower-level Canton library) - [github.com/DLC-link/canton-lib](https://github.com/DLC-link/canton-lib) * **cbtc-lib** (DAR files, scripts) - [github.com/DLC-link/cbtc-lib](https://github.com/DLC-link/cbtc-lib) * **Code examples** - [github.com/DLC-link/cbtc-lib/tree/main/examples](https://github.com/DLC-link/cbtc-lib/tree/main/examples) --- ## Audit Reports * [**Quantstamp Audit Report (CBTC)**](https://certificate.quantstamp.com/full/cbtc/5d0d805e-8cf0-4a39-bf1a-0e94899b3c1c/index.html) --- ## Whitepapers and Research * [**FROST: Flexible Round-Optimized Schnorr Threshold Signatures**](https://eprint.iacr.org/2020/852) - Komlo & Goldberg, 2020 * [**Canton Network Whitepaper**](https://www.canton.network/whitepapers) - Digital Asset --- ## Canton Ecosystem Links * [Canton Network](https://www.canton.network/) * [Canton Developer Documentation](https://docs.digitalasset.com/) * [Canton Token Standard API](https://docs.dev.sync.global/app_dev/token_standard/index.html#api-references) * [BitSafe Technical Docs (live site)](https://docs.bitsafe.finance/bitsafe-documentation/product-suite/cbtc) --- ## Support :::note[Developer support] [support@bitsafe.finance](mailto:support@bitsafe.finance) ::: --- ## Changelog --- --- # Changelog URL: https://docs.bitsafe.finance/developers/changelog/ This page records asset developer documentation changes and the software releases that affect integrations. Software release dates are separate from documentation publication dates. ### October 8, 2026: cbtc-lib v0.9.0 software release cbtc-lib v0.9.0 pins canton-lib v0.11.0 and canton-api-client 3.6.1-0.1.0. It works with Canton 3.6.1 participants. * Canton 3.6.1 rejects the `filter` and `verbose` fields of an active-contracts request. canton-lib v0.11.0 sends `eventFormat` in their place. * Earlier releases return an empty balance and no error on a Canton 3.6.1 participant. Mint and redeem fail with `post_v2_state_active_contracts failed`. * A holdings query that the Ledger API rejects now returns an error. The error text starts with `Ledger API returned`. * This release is breaking. An application that pins a canton-lib crate must move that pin to v0.11.0. * An application that depends on canton-api-client must move that dependency to 3.6.1-0.1.0. Mixed versions build two copies of the shared types. * Engineering tested this release on Canton 3.6.1 only. * The repository lockfile moves `h2` to 0.4.19 to fix RUSTSEC-2026-0258. Your application's own lockfile sets its `h2` version. This date identifies the software release, not the publication date of the documentation update. [Software changelog](https://github.com/DLC-link/cbtc-lib/blob/v0.9.0/CHANGELOG.md) · [Canonical upgrade path](https://docs.bitsafe.finance/cbtc/concepts-and-reference/sdk-api-and-integration-reference) ### October 1, 2026: cbtc-lib v0.8.0 software release cbtc-lib v0.8.0 pins canton-lib v0.9.0 and exposes returned operation results. * Transfer calls return a `TransferReceipt`. Read its `outcome` to distinguish an offer from immediate settlement. * The CSV batch helper returns its batch result. Callers must handle reported failures. * Allocation returns an `AllocationResult`. Its `outcome` field holds an `AllocationOutcome`, which distinguishes a completed allocation from a pending instruction. * Transfer guidance now requires acceptance only when an offer exists. Self-transfers and transfers to pre-approved receivers settle immediately. * V2 examples cover consolidation, splitting, batch distribution, and batch with callback. * Accept, reject, and cancel each retain one example because their V2 modules use the same parameter types. * No V1 split example exists. Allocation remains V1-only. This date identifies the software release, not the publication date of the documentation update. [Software changelog](https://github.com/DLC-link/cbtc-lib/blob/v0.8.0/CHANGELOG.md) · [Canonical upgrade path](https://docs.bitsafe.finance/cbtc/concepts-and-reference/sdk-api-and-integration-reference) ### September 24, 2026: cbtc-lib v0.7.0 software release This release introduces the CIP-0112 / Canton Token Standard V2 entry points and breaking integration changes. * Eight operations gain V2 entry points: accept, batch, cancel offers, consolidate, distribute, reject, split, and transfer. * Holding queries gain account configuration. TokenClient selects version-dependent writes and holding reads through `TokenClientConfig.version`. * Holding and offer filters match both the instrument name and administrator exactly. * Parameter structs and offer-helper arguments require explicit instrument identity. * `cbtc::holding::Holding` replaces the earlier mint/redemption holding type. * Split errors expose partial results. Holding parsing requires `registrar` and `label`. * `ENVIRONMENT` supplies standard network configuration. Explicit overrides remain supported. * Transfer-factory and accept-context routes use bounded transport retries. Allocation routes have no timeout and do not use those retries. * Keycloak authentication uses `token_url` without the obsolete `/auth` prefix. * The release pins canton-lib v0.8.0. The later cbtc-lib v0.8.0 release pins canton-lib v0.9.0. The eight V2 operations are available on Mainnet. Allocation remains V1-only. An upgrade from v0.6.4 crosses both v0.7.0 and v0.8.0. Follow one [canonical upgrade path](https://docs.bitsafe.finance/cbtc/concepts-and-reference/sdk-api-and-integration-reference). #### Affected reference pages * [Compatibility and release notes](https://docs.bitsafe.finance/cbtc/concepts-and-reference/compatibility-and-release-notes) * [Token standard and contract model](https://docs.bitsafe.finance/cbtc/concepts-and-reference/token-standard-and-contract-model) * [SDK setup and installation](https://docs.bitsafe.finance/developers/sdk-setup-and-installation) * [SDK, API, and integration reference](https://docs.bitsafe.finance/cbtc/concepts-and-reference/sdk-api-and-integration-reference) * [Transfer and receive CBTC](https://docs.bitsafe.finance/cbtc/guides/transfer-and-receive-cbtc) * [Environments and prerequisites](https://docs.bitsafe.finance/cbtc/get-started/environments-and-prerequisites) * [Errors, retries, and troubleshooting](https://docs.bitsafe.finance/cbtc/concepts-and-reference/errors-retries-and-troubleshooting) ### July 27, 2026 #### SDK and DAR version corrections Version references had drifted out of sync with released libraries. Three pages stated different cbtc-lib versions. This update aligned them with the released tags at that time. Corrected versions: * cbtc-lib to v0.6.4. Previous references included v0.3.1 on API Reference, v0.4.2 on SDK Setup and Technical Reference, and v0.3.0 on Quick Start. * canton-lib crates `keycloak`, `ledger`, `registry`, and `common` to v0.6.1. Previous references included v0.3.1 and v0.5.0. * Latest CBTC DAR to `cbtc-1.2.1`, shipped in cbtc-lib v0.6.4. Affected pages: SDK Setup and Installation, API Reference, Technical Reference. Other corrections: * Changed the API Reference installation snippet from HTTPS to SSH transport, matching repository access requirements at that time. * Repointed DAR download links from v0.3.1 and v0.4.2 to v0.6.4. * Corrected a duplicate cbtc-lib entry in the Technical Reference repository table to describe the CBTC DAR. * Clarified that DAR and crate versions use independent numbering. * Added dependency-pin guidance to avoid incompatible copies of shared types. #### December 2025 restructure guidance moved to history Removed the old restructure migration section from SDK Setup and the matching note from API Reference. Both pages describe the current release. The restructure changed module paths and function signatures, not runtime behavior. Earlier code needed updated imports. The historical guidance remains recorded here and in the cleanup pull request. ### March 2, 2026 #### PR #22: Code and API corrections The documentation update applied GitHub PR #22, “Fix CBTC docs to match actual cbtc-lib and canton-lib APIs.” The historical review recorded verification against cbtc v0.3.0 and canton-lib v0.3.0. Affected pages: Quick Start, Minting and Burning, API Reference, Authentication, SDK Setup, Technical Reference. **Version and crate corrections** * Updated SDK references from v0.0.1 to v0.3.0. * Corrected the Rust crate name from `cbtc-lib` or `cbtc_lib` to `cbtc`. * Described canton-lib as a workspace containing `keycloak`, `ledger`, `registry`, and `common`, then at v0.3.0. **Authentication corrections** * Replaced the older positional login call with `password(PasswordParams { ... })` and `client_credentials(ClientCredentialsParams { ... })`. * Corrected Auth0 callouts to use the corresponding struct-based helper names. * Replaced `KEYCLOAK_URL` with `KEYCLOAK_HOST` and `KEYCLOAK_REALM`. * Removed `KEYCLOAK_CLIENT_SECRET` from password-flow examples. * Removed `LEDGER_PORT`; curl examples used `LEDGER_HOST`. **Module and function corrections** | Earlier name | Replacement recorded in that update | | -------------------------------- | ----------------------------------------------------------------------- | | `cbtc_lib::deposit` | `cbtc::mint_redeem::mint` | | `cbtc_lib::balance` | `cbtc::active_contracts` | | `cbtc_lib::withdraw` | `cbtc::mint_redeem::redeem` | | `cbtc_lib::utxo` | `cbtc::consolidate` | | `get_deposit_address` | `get_bitcoin_address` | | `get_active_contracts` | `active_contracts::get` | | `transfer::send` | `transfer::submit` | | `accept::accept_transfer` | `accept::submit` | | `redeem::burn_and_withdraw` | `redeem::create_withdraw_account` followed by `redeem::submit_withdraw` | | `consolidate::check_consolidate` | `consolidate::check_and_consolidate` | Function signatures changed from positional arguments to parameter structs. **Infrastructure and template corrections** * Updated historical Attestor host references from `attestor.bitsafe.dev`, `attestor.bitsafe.testnet`, and `attestor.bitsafe.com` to the corresponding `devnet.dlc.link/attestor-1`, `testnet.dlc.link/attestor-1`, and `mainnet.dlc.link/attestor-1` hosts. * Corrected `CBTC.Issuance:DepositAccount` to `CBTC.DepositAccount:CBTCDepositAccount`. * Added `CBTC.WithdrawAccount:CBTCWithdrawAccount` to API Reference. These are historical corrections, not current endpoint configuration. Obtain current endpoints through approved onboarding. **SDK setup additions** * Added accept and cancel-offer modules to the module table. * Added the client-credentials authentication example. * Added a verification script, migration guide, and `.env` example. **Historical terminology and network notes** The March update changed “Attestor” to “Attester” in several pages following reviewer feedback. Current documentation uses **Attestor / Attestor Network**, following the current terminology guide. The same historical update changed the published operator description from nine external operators plus BitSafe to Finoa, Nethermind, DSRV, and BitSafe. This records the update at that time, not a permanent operator count. **Partner and feature notes** Integration Guides marked Silvana and the hosted UI as “coming soon,” pending confirmation. These entries describe their status at that time. **Fee note** Technical Reference recorded mint and burn fees at 0% in that review. Confirm current fee information before quoting it for a new integration. ### February 10, 2026 #### Initial publication * Published the first draft of CBTC developer documentation across 11 pages. * Pages included CBTC Overview, Quick Start, Minting and Burning, API Reference, Authentication, Integration Guides, Security Deep Dive, Technical Reference, Instrument ID Management, SDK Setup and Installation, and Testnet Guide. * Pinned SDK documentation to cbtc-lib v0.0.1 after the December 2025 restructure. * Published devnet, testnet, and mainnet instrument identifiers with metadata endpoint references. * Recorded gaps: Vaults documentation had not started, Home was in progress, and Error Codes Reference was deferred to v2. Historical identifiers and status notes are not current configuration instructions. --- # Overview URL: https://docs.bitsafe.finance/beth/ ### BETH brings native ETH into Canton workflows BETH is a wrapped native ETH token on Canton Network, built on BitSafe infrastructure and designed to represent ETH at a 1:1 ratio. It gives institutions and application teams a path to hold, transfer, mint, redeem, and integrate ETH-denominated value within Canton applications. This page explains the product and routes readers to the right task. Setup, lifecycle details, contract interfaces, backing evidence, and security controls have their own pages. ### What you can do * Hold and transfer BETH between authorized Canton parties using compatible applications. * Mint BETH following an eligible native ETH deposit to the Ethereum bridge. * Redeem BETH to an Ethereum address that can receive native ETH. * Integrate supported BETH workflows through pinned libraries, APIs, and the bridge interface. * Review bridge governance, privacy boundaries, backing evidence, and operational controls. Direct minting and redemption require onboarding and the BETH Minter credential. A deployed bridge does not, by itself, establish general availability or provider support. ### Choose a path | Goal | Canonical page | | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | Find a wallet, venue, or lending provider | [BETH Ecosystem](/beth/beth-ecosystem/) | | Understand the lifecycle | [How BETH works](/beth/how-beth-works/) | | Choose an operation | [Choose a BETH path](/beth/choose-a-beth-path/) | | Build an integration | [Developer quick start](/beth/get-started/developer-quick-start/) | | Review architecture and controls | [Architecture and trust boundaries](/beth/concepts-and-reference/architecture-and-trust-boundaries/); [Security](/beth/concepts-and-reference/security/) | | Check versions and upgrade requirements | [Compatibility and release notes](/beth/concepts-and-reference/compatibility-and-release-notes/) | ### Product boundaries BETH represents native ETH, not WETH or stETH. The current design does not stake reserve ETH or automatically provide staking rewards. ETH is held by the Ethereum bridge, while BETH holdings and transfers are recorded on Canton. A Canton transfer does not move ETH on Ethereum for each transfer. Canton's configurable sub-transaction privacy applies to entitled Canton contract data. Ethereum deposits, bridge balances, and redemptions remain visible on Ethereum. BETH's design links issuance to eligible ETH deposits and redemption to BETH burns. The evidence, accounting boundaries, pending-redemption treatment, and limitations belong in Proof of Reserve. Ethereum redemption authorization and bridge administration are separate trust boundaries. ### Technical sources * [BitSafe token library](https://github.com/DLC-link/bitsafe-token-lib) * [Shared Canton library](https://github.com/DLC-link/canton-lib) * [Ethereum bridge](https://github.com/DLC-link/evm-asset-bridge) * [BETH Faucet](https://faucet.bitsafe.finance/?network=devnet\&token=beth) ### Next step → **Understand the operating model:** [How BETH works](/beth/how-beth-works/). --- # BETH Ecosystem URL: https://docs.bitsafe.finance/beth/beth-ecosystem/ [BETH overview](/beth/) Use this page to evaluate third-party wallets, trading venues, and lending platforms for BETH. The current provider list distinguishes planned support from confirmed availability. :::caution Availability, supported environments, pairs, eligibility, fees, and product terms can change. Confirm current BETH support directly with the provider before transferring assets or integrating a service. Listings are informational, not a BitSafe endorsement. ::: ### Wallets Store, send, and receive BETH through a supported Canton wallet. | Wallet | Description | Website | | ------ | ---------------------------------------------------------------------------- | ----------------------------------------- | | Bron | Non-custodial wallet with MPC technology and configurable policy controls. | [bron.org](https://bron.org/) | | Loop | Self-custodial Canton wallet accessible through mobile and desktop browsers. | [cantonloop.com](https://cantonloop.com/) | ### Trading venues | Venue | Type | BETH availability | Website | | ------ | ------------------------ | ----------------- | ----------------------------------------------------------------- | | Temple | Central limit order book | BETH-USDCx | [app.templedigitalgroup.com](https://app.templedigitalgroup.com/) | | Kora | Request-for-quote venue | Live | [https://kora.so/](https://kora.so/) | ### Lending protocols | Platform | Description | BETH availability | Website | | -------- | -------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | | Alpend | On-ledger lending and borrowing market for supported digital assets. | Planned. Confirm listing approval, supported collateral and borrow markets, liquidation parameters, and opening date. | [app.alpend.com](https://app.alpend.com/) | ### Choose a provider Before using a third-party service: 1. Confirm BETH support in the intended Canton environment and Ethereum network where relevant. 2. Check regional, institutional, and onboarding eligibility. 3. Review custody, counterparty, bridge, smart-contract, liquidity, and operational risks. 4. Confirm current fees, pairs, collateral parameters, and withdrawal conditions. 5. Test the workflow with the smallest amount allowed by the environment and the organization's policy. ### Integrate BETH Wallets, trading venues, and lending platforms can use BitSafe’s open-source libraries as integration starting points: * [`bitsafe-token-lib`](https://github.com/DLC-link/bitsafe-token-lib) * [`canton-lib`](https://github.com/DLC-link/canton-lib) ### Related pages * [Overview](/beth/) * [Choose a BETH path](/beth/choose-a-beth-path/) * [Transfer and receive BETH](/beth/guides/transfer-and-receive-beth/) * [SDK, API, and integration reference](/beth/concepts-and-reference/sdk-api-and-integration-reference/) * [Security](/beth/concepts-and-reference/security/) ### Integrating BETH into an institutional product? Talk to BitSafe --- # How BETH works URL: https://docs.bitsafe.finance/beth/how-beth-works/ ### The short version BETH represents ETH on Canton Network. A mint starts with ETH deposited to the Ethereum bridge contract. The system verifies the deposit and creates the corresponding BETH for the intended Canton party. A redemption consumes BETH and releases ETH to the destination address of the party's withdrawal account. Transfers between Canton parties use Canton contracts and do not move the underlying ETH for each transfer. ### The system has two connected ledgers * **Ethereum:** holds the ETH that backs BETH in the bridge contract and records deposits and redemption transactions. * **Canton Network:** records BETH holdings, transfers, account workflows, and the parties authorized to act. The integration layer links an Ethereum event to its corresponding Canton workflow. It must prevent duplicate processing and preserve enough identifiers for reconciliation. ### Mint lifecycle 1. The Canton party obtains the required credential and current deposit-account rules. 2. The party creates a deposit account. 3. The deposit account ID identifies the account on Ethereum. 4. The depositor verifies the network and the bridge contract address, then calls `depositETH` with the deposit account ID and the ETH amount. 5. The system detects the deposit event and waits until Ethereum finalizes the block. 6. Independent Attestor Network participants verify the eligible Ethereum deposit. 7. The approved threshold authorizes the mint workflow. 8. BETH is created for the intended Canton party. 9. The Ethereum transaction, account, attestation, Canton update, and resulting holding are reconciled. ### Transfer lifecycle A Canton transfer does not redeem ETH. The sender creates a transfer offer for a receiver. The receiver inspects and accepts the intended offer unless an approved preapproval flow applies. Canton archives or updates the relevant contracts and creates the receiver’s new holding state. ### Redemption lifecycle 1. The party validates an Ethereum destination address. 2. The party creates or selects a withdrawal account using current rules. 3. The application selects sufficient BETH holdings. 4. The party submits the redemption. 5. The Canton contract flow consumes the applicable BETH state. 6. The approved threshold of attestors signs the redemption, and the Ethereum bridge contract releases ETH after it verifies the signatures. 7. The application tracks completion on Ethereum and Canton. 8. The records are reconciled to one request. ### Who does what | Role | Responsibility | Boundary | | ------------------------ | --------------------------------------------------------------------------------------- | --------------------------------------------------------- | | BETH holder | Owns Canton holdings and initiates supported actions | Can act only with the party’s authorization | | BitSafe services | Coordinate account and integration workflows | Cannot be described as able to move reserves unilaterally | | Attestor Network | Verifies eligible Ethereum deposits and signs redemptions under threshold authorization | No single operator is sufficient | | Ethereum bridge contract | Holds deposited ETH and releases it against a threshold of attestor signatures | Enforces its own limits and can be paused | | Canton participant | Hosts the party and submits or observes authorized Canton actions | Visibility follows Canton entitlements | | Ethereum network | Records deposits and redemption transactions | Finality and fee behavior are external to Canton | ### Backing and verification BETH is intended to remain backed 1:1 by ETH. Public documentation should distinguish: * ETH reserves visible in the Ethereum bridge contract. * BETH supply and contract state visible to entitled Canton parties. * Proof of Reserve evidence and its exact coverage. * Operational reconciliation performed by the system. ### Failure boundaries A workflow can pause because of Ethereum finality delays, bridge limits or a paused bridge, service availability, Canton connectivity, authentication, incompatible packages, insufficient approvals, or an ambiguous prior submission. Clients must query authoritative state before retrying. ### Related guides * [Mint BETH](/beth/guides/mint-beth/) * [Redeem BETH](/beth/guides/redeem-beth/) * [Transfer and receive BETH](/beth/guides/transfer-and-receive-beth/) * [BETH architecture and trust boundaries](/beth/concepts-and-reference/architecture-and-trust-boundaries/) ### Technical sources * [`bitsafe-token-lib` repository](https://github.com/DLC-link/bitsafe-token-lib) * [`canton-lib` repository](https://github.com/DLC-link/canton-lib) * [`evm-asset-bridge` repository](https://github.com/DLC-link/evm-asset-bridge) * [BETH Faucet](https://faucet.bitsafe.finance/?network=devnet\&token=beth) ### Next step → **Choose an operation:** [Choose a BETH path](/beth/choose-a-beth-path/). --- # Choose a BETH path URL: https://docs.bitsafe.finance/beth/choose-a-beth-path/ Choose the path that matches your role and immediate task. Start with a read-only check before any state-changing workflow. ### Institutions and trading firms Start with [BETH overview](/beth/), then review transfer operations and the security model. Use the mint or redemption guides only if your organization runs the required Canton infrastructure and has approved access. ### Application developers 1. Review [BETH environments and prerequisites](/beth/get-started/environments-and-prerequisites/). 2. Complete [BETH developer Quick Start](/beth/get-started/developer-quick-start/). 3. [Install and validate BETH DARs](/beth/get-started/install-and-validate-dars/). 4. Choose the [Transfer and receive BETH](/beth/guides/transfer-and-receive-beth/), [Mint BETH](/beth/guides/mint-beth/), or [Redeem BETH](/beth/guides/redeem-beth/) integration. 5. Add [BETH authentication](/beth/get-started/authentication/), reconciliation, and [BETH errors, retries, and troubleshooting](/beth/concepts-and-reference/errors-retries-and-troubleshooting/). ### Canton operators Start with [BETH compatibility and release notes](/beth/concepts-and-reference/compatibility-and-release-notes/), [Install and validate BETH DARs](/beth/get-started/install-and-validate-dars/), [BETH authentication](/beth/get-started/authentication/), monitoring, and recovery. Confirm the participant and package state before enabling an application team. ### Security reviewers Review [BETH architecture and trust boundaries](/beth/concepts-and-reference/architecture-and-trust-boundaries/), [BETH Attestor Network](/beth/concepts-and-reference/attestor-network-and-ethereum-signing/), [BETH Proof of Reserve](/beth/concepts-and-reference/proof-of-reserve/), [BETH authentication](/beth/get-started/authentication/), [BETH security](/beth/concepts-and-reference/security/), and [BETH compatibility and release notes](/beth/concepts-and-reference/compatibility-and-release-notes/). Match every claim to a release and approved evidence source. ### Task map | Goal | Start here | | ---------------------- | ------------------------------------------------------------------ | | Evaluate BETH | [How BETH works](/beth/how-beth-works/) | | Connect an application | [BETH developer Quick Start](/beth/get-started/developer-quick-start/) | | Mint | [Mint BETH](/beth/guides/mint-beth/) | | Redeem | [Redeem BETH](/beth/guides/redeem-beth/) | | Transfer | [Transfer and receive BETH](/beth/guides/transfer-and-receive-beth/) | | Review security | [BETH security](/beth/concepts-and-reference/security/) | ### Next step → **New to BETH development?** [BETH developer Quick Start](/beth/get-started/developer-quick-start/). --- # Environments and prerequisites URL: https://docs.bitsafe.finance/beth/get-started/environments-and-prerequisites/ [BETH overview](/beth/) ### Before you start Choose the BETH operation you need to perform before configuring an environment. Balance queries, transfers, minting, redemption, batch distribution, and UTXO management do not all share the same prerequisites. ### Choose an environment | Environment | Use it for | Before proceeding | | ----------- | ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | Development | Local development and early workflow testing | Confirm the current participant, registry, BitSafe API, credential, and test-asset setup. | | Testnet | Integration testing against shared infrastructure | Confirm endpoint ownership, faucet availability, reset policy, and differences from production. | | Mainnet | Production workloads | Use only an Engineering-approved compatibility row, production credentials, monitoring, recovery procedures, and security review. | Obtain current endpoints, party identifiers, and package identifiers from the maintained environment reference. Check its owner and last-verified date before use. #### Ethereum bridge contracts Canton Devnet and Testnet both use Ethereum Sepolia, with a separate bridge contract for each. Canton Mainnet uses Ethereum Mainnet. | Environment | Ethereum network | Bridge contract | | ----------- | ----------------------------- | -------------------------------------------- | | Devnet | Sepolia (chain ID `11155111`) | `0xaAafDA111EAf5a49359e5C15B9B58DED7313f979` | | Testnet | Sepolia (chain ID `11155111`) | `0x5D60b6C3eC2FD5E4227AE0008BABE95Be86dD172` | | Mainnet | Ethereum (chain ID `1`) | `0xb5d425d678B10949dD0f7bB0dd0427C47451D57E` | Each address is an upgradeable proxy, so the address stays the same when the contract code is upgraded. `bitsafe-token-lib` `v0.5.0` uses these addresses, and the `ENVIRONMENT` value selects one. ### Core prerequisites All BETH development paths require: * Access to a supported Canton participant. * A Canton party authorized for the intended operation. * A supported authentication configuration and a safe method for storing credentials. * A compatible Rust toolchain when using the current Rust library. * A pinned `bitsafe-token-lib` release and compatible shared `canton-lib` crates. * Network access to the required Canton and external service endpoints. * A test plan that states the expected ledger and application result. ### Operation-specific prerequisites | Operation | Additional prerequisites | | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | Check balances or contracts | Ledger host, authenticated party, and compatible query interface. | | Send, receive, accept, reject, or cancel | Digital Asset Registry Utility components, receiver party details, required transfer context, and sufficient holdings. | | Mint BETH | BitSafe API access, required Minter credential, compatible BETH DAR packages, account rules, and an Ethereum deposit flow. | | Redeem BETH | BitSafe API access, required Minter credential, compatible BETH DAR packages, sufficient holdings, and a valid Ethereum destination address. | | Batch distribution | Transfer prerequisites plus recipient input validation, limits, callbacks or result capture, and reconciliation. | | UTXO management | Current holdings, approved split or consolidation policy, and a clear reason for changing the holding layout. | ### Install compatible components The examples on this page use: * `bitsafe-token` package version `0.5.0`. * `canton-lib` dependencies pinned to `v0.12.0`. * A Canton API client generated from Canton `3.6.1` specifications. For deployment, use the approved compatibility matrix for the BitSafe token library, shared Canton library, Canton version, DAR packages, API behavior, and target environment. ### Configure safely Configuration falls into four groups: 1. **Canton connection:** ledger host and party identity. 2. **Authentication:** approved identity-provider host, realm or audience, client identity, and secret-handling method. 3. **BETH network:** the `ENVIRONMENT` value (`devnet`, `testnet`, or `mainnet`). It selects the Decentralized Party, the registry, the BitSafe API, and the Ethereum bridge for the target network. 4. **Mint and redeem:** BitSafe API selection and Ethereum destination details where needed. Never commit `.env` files, tokens, passwords, client secrets, party-specific credentials, or production addresses. Use placeholders in public examples and document how readers obtain real values through approved channels. ### Preflight checklist * [ ] The target environment is approved for the intended test. * [ ] The Canton participant is reachable. * [ ] Authentication succeeds for the intended party. * [ ] The pinned library set builds successfully. * [ ] Required DAR packages are installed and validated. * [ ] Registry and BitSafe services required by the operation are reachable. * [ ] The party has the required credential and holdings. * [ ] The expected result and rollback or recovery path are documented. * [ ] Logs and identifiers needed for support can be collected without exposing secrets. ### Verify the setup Start with a read-only operation such as a connection or balance check. A successful preflight should confirm: * Authentication completed. * The intended party was used. * The ledger query returned a valid response. * The application can parse the response with the pinned library set. Continue to a state-changing operation only after the read-only check passes. ### Technical sources * [`bitsafe-token-lib` `v0.5.0`](https://github.com/DLC-link/bitsafe-token-lib/tree/v0.5.0) * [`bitsafe-token-lib` environment example](https://github.com/DLC-link/bitsafe-token-lib/blob/v0.5.0/.env.example) * [BETH DAR guidance](https://github.com/DLC-link/bitsafe-token-lib/tree/v0.5.0/dars) * [`canton-lib` `v0.12.0`](https://github.com/DLC-link/canton-lib/tree/v0.12.0) * [BETH network values in `bitsafe-token-lib` `v0.5.0`](https://github.com/DLC-link/bitsafe-token-lib/blob/v0.5.0/src/tokens/beth/mod.rs#L39-L64) ### Related pages * [BETH developer Quick Start](/beth/get-started/developer-quick-start/) * [Install and validate BETH DARs](/beth/get-started/install-and-validate-dars/) * [BETH authentication](/beth/get-started/authentication/) * [Mint BETH](/beth/guides/mint-beth/) * [Redeem BETH](/beth/guides/redeem-beth/) * [Transfer and receive BETH](/beth/guides/transfer-and-receive-beth/) * [BETH compatibility and release notes](/beth/concepts-and-reference/compatibility-and-release-notes/) ### Next step → **Verify your setup:** [BETH developer Quick Start](/beth/get-started/developer-quick-start/). --- # Developer quick start URL: https://docs.bitsafe.finance/beth/get-started/developer-quick-start/ [BETH overview](/beth/) · [BETH environments and prerequisites](/beth/get-started/environments-and-prerequisites/) ### What you will do 1. Prepare a supported Rust environment. 2. Check out a pinned `bitsafe-token-lib` release. 3. Configure Canton and authentication values without committing secrets. 4. Run the balance-check example. 5. Verify that the response belongs to the intended party. This read-only outcome is intentionally smaller than minting or transferring BETH. It verifies the core connection before you create accounts or submit ledger changes. ### Prerequisites * Access to an approved development or test environment. * A supported Canton participant and party. * Approved authentication credentials for that party. * Git and a compatible Rust toolchain. * Network access to the Canton participant and identity provider. * A secure local method for storing environment values. ### 1. Check out the reviewed source ```bash git clone https://github.com/DLC-link/bitsafe-token-lib.git cd bitsafe-token-lib git checkout v0.5.0 ``` Use an approved release tag. Do not use `main` in production instructions. ### 2. Create local configuration ```bash cp .env.example .env ``` Fill only the values required for the balance check: * Canton JSON Ledger API host, including the API path. * Target Canton party. * Approved identity-provider and client values required by the selected authentication flow. * The `ENVIRONMENT` value: `devnet`, `testnet`, or `mainnet`. * The `ASSET` value: `beth`. Do not paste real credentials into documentation, issue reports, shell history, or source control. ### 3. Build the example ```bash cargo build --example check_balance ``` A successful build confirms that the selected Rust toolchain can resolve the pinned BETH and shared Canton dependencies. ### 4. Run the balance check ```bash cargo run --example check_balance ``` ### Expected result The command should: * Authenticate successfully. * Query active BETH holdings for the configured party. The query keeps only holdings whose instrument ID and admin both match the BETH instrument. * Report the party’s balance and holding count, including a valid zero-balance result where applicable. * Exit without exposing access tokens or passwords. :::note Output fields vary by supported release and environment. Verify the response belongs to the intended party, and never substitute a fabricated balance or contract identifier when testing an integration. ::: ### If the check fails | Symptom | Check | Next action | | ------------------------ | ------------------------------------------------------------------------- | --------------------------------------------------------------------------- | | Authentication fails | Provider URL, realm or audience, client, grant type, secret, token claims | Use the canonical Authentication guide and confirm the party authorization. | | Connection fails | Ledger host, DNS, TLS, proxy, and network access | Verify the participant endpoint with the environment owner. | | No holdings are returned | Target party, environment, and whether zero balance is valid | Confirm the configured party before attempting a state-changing operation. | | Build or type errors | Checked-out tag, Rust toolchain, lockfile, and shared library access | Return to the approved compatibility matrix. | | Response parsing fails | Canton and library compatibility | Capture sanitized output and escalate with the version set. | ### Next steps After the balance check passes, choose one task: * [Transfer and receive BETH](/beth/guides/transfer-and-receive-beth/). * Create a deposit account and follow [Mint BETH](/beth/guides/mint-beth/). * Create a withdrawal account and follow [Redeem BETH](/beth/guides/redeem-beth/). * Use [BETH SDK, API, and integration reference](/beth/concepts-and-reference/sdk-api-and-integration-reference/) to integrate balance and transfer behavior into a wallet or application. ### Technical sources * [`bitsafe-token-lib` `v0.5.0`](https://github.com/DLC-link/bitsafe-token-lib/tree/v0.5.0) * [Balance-check example](https://github.com/DLC-link/bitsafe-token-lib/blob/v0.5.0/examples/check_balance.rs) * [Examples guide](https://github.com/DLC-link/bitsafe-token-lib/blob/v0.5.0/examples/README.md) ### Related pages * [Install and validate BETH DARs](/beth/get-started/install-and-validate-dars/) * [BETH authentication](/beth/get-started/authentication/) * [Mint BETH](/beth/guides/mint-beth/) * [Redeem BETH](/beth/guides/redeem-beth/) * [Transfer and receive BETH](/beth/guides/transfer-and-receive-beth/) * [BETH SDK, API, and integration reference](/beth/concepts-and-reference/sdk-api-and-integration-reference/) * [BETH errors, retries, and troubleshooting](/beth/concepts-and-reference/errors-retries-and-troubleshooting/) ### Next step → **Build your first workflow:** [Transfer and receive BETH](/beth/guides/transfer-and-receive-beth/). --- # Install and validate DARs URL: https://docs.bitsafe.finance/beth/get-started/install-and-validate-dars/ [BETH environments and prerequisites](/beth/get-started/environments-and-prerequisites/) ### Outcome Upload the BETH DAR packages required for minting and redemption to a Canton participant, then confirm that the expected BETH packages are present. :::note BETH DAR packages are required for minting and redemption, according to the `bitsafe-token-lib` `v0.5.0` DAR guidance. They are not required for sending or receiving BETH or for UTXO management. ::: ### Before you start You need: * Administrative access to the target Canton participant. * An approved connection to the participant Admin API. The repository examples use `localhost:5002`; use the endpoint and connection method documented for the target environment. * A participant administrator JWT if the Admin API requires authentication. * `grpcurl`, `jq`, and `base64` for the recommended upload path. * A Rust toolchain for the `check_dars` validation example. * The pinned [`bitsafe-token-lib` `v0.5.0` release](https://github.com/DLC-link/bitsafe-token-lib/releases/tag/v0.5.0). * The current compatibility row for the target Canton version, BETH DAR release, and environment. :::note Treat administrator tokens as secrets. Retrieve them through the approved secret-management process. Do not commit tokens, add them to documentation, or leave them in a modified copy of the upload script. ::: ### 1. Get the pinned DAR release ```bash git clone https://github.com/DLC-link/bitsafe-token-lib.git cd bitsafe-token-lib git checkout v0.5.0 ``` Confirm that the repository contains `dars/upload_dars.sh`, `dars/dependencies/`, and `dars/beth/`. ### 2. Confirm the Admin API connection Establish the approved port-forward or network path to the participant Admin API. If the target differs from the repository default `localhost:5002`, set the `canton_admin_api_url` environment variable: ```bash export canton_admin_api_url="" ``` Do not proceed until the endpoint is confirmed to belong to the intended participant and environment. ### 3. Configure authentication If the Admin API requires authentication, expose the administrator token to the script through the `jwt_token` environment variable: ```bash export jwt_token="" ``` If the Admin API does not require authentication, leave `jwt_token` empty. Follow the authentication flow documented for the target environment. ### 4. Upload the DARs The recommended repository path uses the gRPC upload script. Pass the asset name to the script: ```bash dars/upload_dars.sh beth ``` The script uploads: 1. Dependency DARs from `dars/dependencies/`. 2. BETH DARs from `dars/beth/`. For every upload, the script requests package vetting and synchronized vetting. The script stops at the first DAR that fails to upload. Canton skips a DAR that is already present, so the repository guidance describes the script as safe to run again. :::note Verify the upload response itself. Do not treat the script's printed success line as sufficient proof that the Admin API accepted every package. ::: ### 5. Check the installed BETH DARs The repository includes a Rust example that compares the DARs in `dars/dependencies/` and `dars/beth/` with the packages on the participant: ```bash ASSET=beth cargo run --example check_dars ``` The example reads `LEDGER_HOST` and the Keycloak values from `.env`. It does not need `ENVIRONMENT` or `PARTY_ID`. The example prints `PASS` when every required package is present. Otherwise, it prints `FAIL`, lists each missing package, and exits with a non-zero code. Record this output with the environment and release tag used for the installation. Remove tokens and other sensitive values before sharing diagnostic output. ### 6. Verify the result A successful installation should meet all of these checks: * [ ] Every expected dependency upload returned an accepted or already-present result. * [ ] Every expected BETH upload returned an accepted or already-present result. * [ ] `check_dars` reports `PASS` for the BETH DAR set. * [ ] The recorded package set matches the Engineering-approved release manifest for the target environment. * [ ] A read-only BETH preflight succeeds before any mint or redemption is attempted. :::note The `check_dars` example is a presence check, not a complete compatibility test. It does not verify application behavior or compatibility with the participant version. Complete the release-specific acceptance test after checking the maintained package manifest. ::: ### Expected result The target participant contains the approved BETH and dependency DAR set for the selected environment. The `check_dars` result shows every expected package as present, and the environment passes the approved read-only preflight. ### Troubleshooting | Symptom | Check | Next action | | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | | Connection refused or unavailable | Port-forward, host, port, participant identity, and Admin API availability. | Restore the approved Admin API connection. Do not switch environments or ports by trial and error. | | Unauthenticated or permission denied | Whether the Admin API requires a token and whether the token has participant administrator permissions. | Obtain a new token through the approved process. Do not paste the token into a support ticket. | | `check_dars` reports missing packages | Target participant, upload responses, the `ASSET` value, and the ledger connection. | Stop before minting or redemption. Collect redacted logs and escalate with the release tag and environment. | | Some packages appear but the release set is incomplete | Dependency and BETH upload responses, release manifest, and package vetting status. | Do not mix releases. Reconcile against the approved manifest before retrying. | ### Alternative Canton upload path The repository also includes the Canton console scripts `00_UploadDars.sc` and `00_ValidateDars.sc`. In `v0.5.0`, these scripts upload and list CBTC DARs only. Use the recommended gRPC path for BETH. ### Technical sources * [`bitsafe-token-lib` `v0.5.0` DAR guidance](https://github.com/DLC-link/bitsafe-token-lib/blob/v0.5.0/dars/README.md) * [Recommended gRPC upload script](https://github.com/DLC-link/bitsafe-token-lib/blob/v0.5.0/dars/upload_dars.sh) * [DAR check example](https://github.com/DLC-link/bitsafe-token-lib/blob/v0.5.0/examples/check_dars.rs) * [DAR inventory script](https://github.com/DLC-link/bitsafe-token-lib/blob/v0.5.0/dars/00_ValidateDars.sc) * [Alternative Canton upload script](https://github.com/DLC-link/bitsafe-token-lib/blob/v0.5.0/dars/00_UploadDars.sc) * [Scala prerequisites](https://github.com/DLC-link/bitsafe-token-lib/blob/v0.5.0/dars/scala-prerequisites.md) ### Related pages * [BETH environments and prerequisites](/beth/get-started/environments-and-prerequisites/) * [BETH authentication](/beth/get-started/authentication/) * [Mint BETH](/beth/guides/mint-beth/) * [Redeem BETH](/beth/guides/redeem-beth/) * [BETH compatibility and release notes](/beth/concepts-and-reference/compatibility-and-release-notes/) ### Next step → **Configure access:** [BETH authentication](/beth/get-started/authentication/). --- # Authentication URL: https://docs.bitsafe.finance/beth/get-started/authentication/ [BETH developer Quick Start](/beth/get-started/developer-quick-start/) ### Authentication surfaces BETH integrations can authenticate to more than one service: * **Canton Ledger API:** submit commands and query contract state for an authorized party. * **Canton Admin API:** perform privileged participant operations such as package management. Most BETH clients should not need this surface. * **BitSafe APIs:** obtain account rules and participate in approved mint or redemption workflows. * **Ethereum account:** initiate deposits to the Ethereum bridge and receive redemptions on the Ethereum network. * **Source and artifact systems:** access approved repositories or private release artifacts where required. ### Use separate identities Use distinct clients and credentials for development, test, and production. Separate administrative credentials from application credentials. Grant only the party rights and API scopes required for the workflow. ### Configuration categories A client can require an identity-provider URL, realm or audience, client identifier, client secret or approved key, grant type, token endpoint, Canton user, and target party. Exact variable names belong in the versioned configuration reference. ### Safe setup 1. Create or obtain the approved service identity. 2. Assign the minimum Canton `actAs` and `readAs` rights. 3. Configure the approved audience and scopes. 4. Store secrets in a secret manager or protected local store. 5. Request a token through the approved flow. 6. Validate issuer, audience, expiry, and party authorization. 7. Run a read-only balance query before submitting a command. ### Operational rules * Never place tokens or secrets in documentation, screenshots, logs, shell history, or source control. * Rotate credentials under an approved process. * Treat authentication success and party authorization as separate checks. * Do not retry a state-changing command only because token refresh or transport failed. * Sanitize support evidence before sharing it. ### Common failures | Failure | Check | | ------------------------------- | ---------------------------------------------------------------------- | | Token request rejected | Provider URL, client, secret, grant, realm, and network access | | Token accepted but query denied | Audience, scopes, Canton user rights, and party | | Works in one environment only | Environment-specific client, endpoints, trust store, and party mapping | | Intermittent failures | Clock skew, token expiry, refresh behavior, and connection reuse | ### Related pages * [BETH environments and prerequisites](/beth/get-started/environments-and-prerequisites/) * [BETH developer Quick Start](/beth/get-started/developer-quick-start/) * [Install and validate BETH DARs](/beth/get-started/install-and-validate-dars/) * [BETH SDK, API, and integration reference](/beth/concepts-and-reference/sdk-api-and-integration-reference/) * [BETH security](/beth/concepts-and-reference/security/) ### Next step → **Test the connection:** [BETH developer Quick Start](/beth/get-started/developer-quick-start/). --- # Integrating BETH URL: https://docs.bitsafe.finance/beth/guides/integrating-beth/ Integrate BETH into a Canton wallet, DEX, or protocol. Use the same asset identifiers and registry URLs for each integration. Minting and redemption are separate workflows. ### Asset information Use the fields for the intended environment. In Canton Token Standard calls, use the Registrar as `InstrumentId.admin` and `BETH` as `InstrumentId.id`. Do not use the Operator as the instrument administrator. Confirm current configuration before production use. Fields marked “Confirm with BitSafe” need confirmation before publication. #### DevNet * **ID:** `BETH` * **Operator:** `auth0_007c65f857f1c3d599cb6df73775::1220d2d732d042c281cee80f483ab80f3cbaa4782860ed5f4dc228ab03dedd2ee8f9` * **Provider:** `beth-network::12207547956b2fbcc5c7b85ee3eeb13705b641e233fb17cebb4057d14e1a3f81bea6` * **Registrar:** `beth-network::12207547956b2fbcc5c7b85ee3eeb13705b641e233fb17cebb4057d14e1a3f81bea6` Registry URL: `https://api.utilities.digitalasset-dev.com` #### TestNet * **ID:** `BETH` * **Operator:** `DigitalAsset-UtilityOperator::12202679f2bbe57d8cba9ef3cee847ac8239df0877105ab1f01a77d47477fdce1204` * **Provider:** `beth-network::122027d91679105c721435c6f08f8d0cd684e6679f385731f5b3691cb9bf93cd126e` * **Registrar:** `beth-network::122027d91679105c721435c6f08f8d0cd684e6679f385731f5b3691cb9bf93cd126e` Registry URL: `https://api.utilities.digitalasset-staging.com` #### MainNet * **ID:** `BETH` * **Operator:** `auth0_007c6643538f2eadd3e573dd05b9::12205bcc106efa0eaa7f18dc491e5c6f5fb9b0cc68dc110ae66f4ed6467475d7c78e` * **Provider:** `beth-network::1220704c3cebc23916785557ebe79a5c7f68d034890a5b15690ea7ce050c7d463075` * **Registrar:** `beth-network::1220704c3cebc23916785557ebe79a5c7f68d034890a5b15690ea7ce050c7d463075` Registry URL: `https://api.utilities.digitalasset.com` ### Test the integration [Open the BitSafe faucet](https://faucet.bitsafe.finance/?network=devnet\&token=cbtc). The faucet supports BitSafe assets on DevNet and TestNet. The link opens with DevNet and CBTC selected. 1. Select the intended network. 2. Select BETH. 3. Enter the recipient's Canton party ID. 4. Request test tokens. 5. Accept the faucet transfer as the recipient. 6. Check the recipient's BETH balance. The recipient node must have the DA Utility Registry installed. Faucet tokens are not MainNet assets. Test sending and receiving with the [Transfer and receive BETH guide](https://docs.bitsafe.finance/beth/guides/transfer-and-receive-beth). Support both pending offers and completed transfers. A completed transfer does not require acceptance. ### DEX and protocol integrations DEXs and protocols use the same BETH instrument ID and administrator listed above. The additional work depends on the application's workflow. | Integration | Additional work | | ------------------------- | ------------------------------------------------------------------------ | | Wallet | Display balances and support sending and receiving tokens. | | DEX or trading venue | Connect asset transfers to the venue's trade-settlement workflow. | | Lending or other protocol | Define how the application manages deposits, positions, and withdrawals. | For a trade that exchanges two assets, an ordinary transfer does not link the two legs. Canton Token Standard allocations support delivery-versus-payment settlement: both legs settle together or neither does. Confirm supported APIs and the required settlement permissions before using this workflow. For lending, confirm the price source and collateral, borrowing, and liquidation rules before enabling the asset. Token support alone does not configure those rules. See the [Canton Token Standard documentation](https://docs.dev.sync.global/app_dev/token_standard/index.html) for allocation and application integration details. [Minting information](/beth/guides/mint-beth/) can be found here. ### Technical resources * [`bitsafe-token-lib`](https://github.com/DLC-link/bitsafe-token-lib) * [`canton-lib`](https://github.com/DLC-link/canton-lib) ### Artwork and support Use approved asset artwork from the [BitSafe brand kit](https://bitsafe.finance/brand-kit). Contact BitSafe if the required artwork is unavailable. For additional party fields or configuration questions, [contact BitSafe](https://bitsafe.typeform.com/helloBitSafe). ## Reach out to BitSafe Integrating one of our assets? Reach out to the team on Slack or to sales@bitsafe.finance to coordinate go-lives, marketing, and liquidity. --- # Mint BETH URL: https://docs.bitsafe.finance/beth/guides/mint-beth/ [BETH overview](/beth/) · [BETH environments and prerequisites](/beth/get-started/environments-and-prerequisites/) ### Outcome Create a BETH deposit account, select its deposit account ID, deposit ETH to the Ethereum bridge, and verify that the corresponding BETH becomes available to the intended Canton party. ### Before you start * Complete the BETH environment preflight. * Use a supported Canton participant and authenticated party. * [Install and validate the BETH DAR packages](/beth/get-started/install-and-validate-dars/) required for minting. * Confirm that the party has the required Minter credential. * Confirm that the BitSafe API of the selected environment is reachable. * Use a pinned `bitsafe-token-lib` release and compatible shared Canton libraries. * Confirm the approved Ethereum network and the bridge contract address. For Devnet and Testnet, get Sepolia ETH from a Sepolia faucet. * Use an Ethereum account that can call a contract and that holds ETH for the deposit and for gas. Minting has additional prerequisites beyond ordinary BETH transfers. Do not begin from the Send BETH setup alone. ### 1. Confirm the Minter credential Use the credential example or the approved application interface to: 1. Check whether the party already holds the required credential. 2. Find an eligible pending credential offer if none exists. 3. Accept only the intended offer through the approved flow. 4. Record the resulting credential contract identifier securely for the current operation. Do not copy a real credential contract identifier into documentation or support tickets. ### 2. Retrieve current account rules Retrieve the deposit and withdrawal account rules from the BitSafe API of the selected environment: ```http GET /beth/v1/account-contract-rules ``` The response holds `da_rules` for deposit accounts and `wa_rules` for withdrawal accounts. Each rule has a `template_id`, a `contract_id`, and a `created_event_blob`. Verify that: * The response belongs to the selected environment. * The package and template references match the approved DAR set. * The returned rules are current for the intended party and operation. Treat rules as runtime data. Do not hard-code them into a long-lived integration. ### 3. Create a deposit account Create a deposit account using: * The authenticated Canton party. * The approved Minter credential. * The current deposit-account rules. * A unique command or request identifier where the interface supports one. Verify that the resulting account is owned by the intended party before continuing. ### 4. Select the deposit account ID BETH doesn't have a separate deposit address for each account. Instead, every deposit goes to the one Ethereum bridge contract of the environment. The deposit account ID tells the attestors which account to credit. Select the deposit account ID: * If the deposit account has an `id` value, use that value. * Otherwise, use the contract ID of the deposit account. The ID stays the same when a completed deposit recreates the account contract. Use the same ID for every deposit to the account. Do not replace it with the newest contract ID. :::caution A deposit with the wrong deposit account ID does not mint BETH, and the ETH can become stuck in the bridge. Pay extra attention to the ID before sending a deposit. If a finalized deposit does not mint BETH, contact support with the transaction hash and the ID. Do not send a second deposit. ::: Before depositing ETH: * Confirm the Ethereum network and chain ID. * Confirm the bridge contract address for the selected environment. * Confirm the ID belongs to the expected deposit account. * Record the account and ID association in the integration’s reconciliation data. ### 5. Deposit ETH Call `depositETH(bytes depositAccountId)` on the bridge contract. Pass the deposit account ID as UTF-8 bytes, and send the approved test amount as the transaction value. Use the transaction hash to monitor Ethereum finality. :::caution **Encode the deposit account ID as UTF-8 bytes.** The ledger API returns the ID as a hex string. Do not pass that hex string as raw bytes. Pass the UTF-8 bytes of the text. ``` Deposit account ID from the ledger: 00a1b2c3… Wrong depositAccountId: 0x00a1b2c3… Correct depositAccountId: 0x3030613162326333… ``` ::: The amount must be a whole multiple of `100000000` wei (`0.0000000001` ETH), because BETH has 10 decimal places. The bridge rejects any other amount. The bridge also rejects a plain ETH transfer, so a deposit must call `depositETH`. The amount must also be within the deposit account's own limits. `beth::mint::deposit_call` checks these limits. :::note Check the bridge's current `depositLimits()` and `paused()` state before sending. Check the current environment and compatibility reference for fees, timing, and timeout behavior. Do not rely on historical values. ::: ### 6. Monitor the mint lifecycle Track the deposit account and BETH state until the approved completion condition is met. Monitor: * `Deposit` event emitted by the bridge contract. The bridge emits the five-field layout after its upgrade. `bitsafe-token-lib` 0.5.0 decodes only that layout. * Ethereum block finalized. * Verification or attestation state. * Mint submitted on Canton. * BETH holding created for the intended party. * Terminal failure or escalation state. ### 7. Verify the result A successful mint should be verified in two places: 1. The deposit workflow shows the approved completed state. 2. The intended Canton party’s BETH balance or holdings increase by the expected amount. Reconcile the Ethereum transaction, deposit account, mint result, Canton update, and resulting holdings without exposing secrets. ### Source example The repository includes a guided example: ```bash cargo run --example beth_credentials cargo run --example beth_mint_flow ``` The `beth_mint_flow` example does not send ETH. It prints the `depositETH` transaction, which you sign and send with your own Ethereum wallet. Use these commands only with the reviewed source tag and an approved environment. Link to the source for exhaustive implementation details rather than duplicating the full code. ### Troubleshooting | Symptom | Check | Safe next action | | ----------------------------------- | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | | No eligible credential | Party, environment, registrar, and pending offers | Stop and use the approved credential-request path. | | Account rules unavailable | BitSafe API, authentication, environment, and service status | Do not reuse cached rules unless the support policy permits it. | | Deposit account creation fails | DAR compatibility, credential, party rights, rule identifiers, and Canton response | Capture sanitized identifiers and the version set. | | Deposit transaction fails | Bridge pause state, deposit limits, amount unit, and `depositETH` call data | Correct the input before another attempt. | | ETH deposit is not detected | Chain ID, bridge contract address, deposit account ID, transaction hash, finality state, and event topic0 | Do not send a second deposit until the first transaction is reconciled. | | Deposit is final but BETH is absent | Deposit account ID, verification state, mint status, Canton update, and target party | Escalate with sanitized account, transaction, and update identifiers. | Read topic0 from the deposit transaction's receipt at the proxy address before choosing a filter or decoder. The [SDK event reference](/beth/concepts-and-reference/sdk-api-and-integration-reference/#deposit-event-layout) explains topics and historical log decoding. ### Technical sources * [Mint flow example](https://github.com/DLC-link/bitsafe-token-lib/blob/v0.5.0/examples/beth/mint_flow.rs) * [Credential example](https://github.com/DLC-link/bitsafe-token-lib/blob/v0.5.0/examples/beth/credentials.rs) * [Examples guide](https://github.com/DLC-link/bitsafe-token-lib/blob/v0.5.0/examples/README.md) * [BETH DAR guidance](https://github.com/DLC-link/bitsafe-token-lib/tree/v0.5.0/dars) * [Ethereum bridge contract](https://github.com/DLC-link/evm-asset-bridge) ### Related pages * [Install and validate BETH DARs](/beth/get-started/install-and-validate-dars/) * [BETH authentication](/beth/get-started/authentication/) * [BETH errors, retries, and troubleshooting](/beth/concepts-and-reference/errors-retries-and-troubleshooting/) * [BETH compatibility and release notes](/beth/concepts-and-reference/compatibility-and-release-notes/) ### Next step → **Prepare for failures safely:** [BETH errors, retries, and troubleshooting](/beth/concepts-and-reference/errors-retries-and-troubleshooting/). --- # Redeem BETH URL: https://docs.bitsafe.finance/beth/guides/redeem-beth/ [BETH overview](/beth/) · [BETH environments and prerequisites](/beth/get-started/environments-and-prerequisites/) ### Outcome Create or select a withdrawal account, redeem BETH, and verify delivery of ETH to the intended Ethereum address. ### Before you start * Complete the BETH environment preflight. * Confirm the party holds enough BETH for the intended test. * [Install and validate the DAR packages](/beth/get-started/install-and-validate-dars/) required for redemption. * Confirm the required Minter credential. * Configure the approved BitSafe API. * Obtain a valid Ethereum destination address for the selected network. The address must accept native ETH. * Understand the approved minimums, limits, fees, and recovery path. ### 1. Validate the Ethereum destination Before creating a withdrawal account: * Confirm the destination address format and Ethereum network. * Confirm that the address can receive native ETH. A contract address that rejects ETH makes the redemption fail. * Confirm ownership or authorization under the organization’s controls. * Use a second-person or system control for production destinations where required. The account owner can change the destination address after account creation. A change does not affect a redemption that is already in progress. A wrong-network or wrong-recipient destination may be irreversible. ### 2. Retrieve current withdrawal rules Retrieve the current account rules from the BitSafe API of the selected environment: ```http GET /beth/v1/account-contract-rules ``` Use the `wa_rules` entry for withdrawal accounts. Confirm that the response matches the selected environment, current DAR set, and intended operation. ### 3. Create or select a withdrawal account Create a withdrawal account using the authenticated party, approved credential, current rules, and verified Ethereum destination. If reusing an existing account, confirm its destination and current status before selecting it. A withdrawal account allows one withdrawal at a time. A second redemption from the same account fails until the first one is processed. Created deposit and withdrawal accounts stay on the ledger until someone closes them. Do not create duplicate accounts as an automatic retry strategy. ### 4. Select BETH holdings Query current BETH holdings and select sufficient inputs to cover the requested redemption according to the approved holding-selection policy. Before submission: * Confirm the total selected amount. * Confirm the requested withdrawal amount. * Check applicable limits. * Preserve enough information for reconciliation. * Avoid using holdings involved in another pending operation. ### 5. Submit the withdrawal Submit the redemption through the supported BETH interface. Use a unique request or command identifier where available and retain the resulting Canton update or contract identifiers securely. :::note Do not retry blindly after a timeout. First determine whether the original command committed, failed, or remains pending. ::: ### 6. Monitor the lifecycle Monitor the authoritative states for: * Withdrawal submitted. * BETH burned or otherwise consumed by the approved contract flow. * Withdrawal account pending balance updated. * Ethereum redemption transaction submitted. * Ethereum block finalized. * Completed, failed, cancelled, or escalated. ### 7. Verify and reconcile A successful redemption should show: 1. The intended BETH amount no longer appears in the party’s available holdings. 2. The withdrawal account reflects the approved state transition. 3. ETH is delivered to the verified destination. 4. The Canton and Ethereum records reconcile to one redemption request. The ETH arrives as an internal transfer from the bridge contract. The outer Ethereum transaction shows zero ETH value. Check the bridge `Withdraw` event or the internal transfers of the transaction. ### Source example ```bash cargo run --example beth_credentials cargo run --example beth_redeem_flow ``` ### Troubleshooting | Symptom | Check | Safe next action | | ------------------------------------- | -------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | | Destination rejected | Network, format, rule set, and account state | Stop; do not substitute an address without repeating validation. | | Insufficient selectable holdings | Available balance, pending operations, UTXO layout, and limits | Reconcile holdings before consolidating or splitting. | | Second redemption fails | Whether the account has a redemption in progress | Wait until the first redemption is processed. | | Submission times out | Canton update status and withdrawal-account state | Determine commitment before retrying. | | BETH decreases but ETH is pending | Withdrawal state, bridge pause state and limits, Ethereum finality, and service health | Follow the approved pending-withdrawal escalation path. | | ETH arrives with an unexpected amount | Requested amount, approved fees, bridge `Withdraw` event, and reconciliation record | Escalate; do not make an offsetting transaction automatically. | | Destination does not accept ETH | Whether the destination is a contract that rejects ETH | Escalate with sanitized account, transaction, and update identifiers. | ### Technical sources * [Redeem flow example](https://github.com/DLC-link/bitsafe-token-lib/blob/v0.5.0/examples/beth/redeem_flow.rs) * [Examples guide](https://github.com/DLC-link/bitsafe-token-lib/blob/v0.5.0/examples/README.md) * [Ethereum bridge contract](https://github.com/DLC-link/evm-asset-bridge) ### Related pages * [Install and validate BETH DARs](/beth/get-started/install-and-validate-dars/) * [BETH authentication](/beth/get-started/authentication/) * [BETH batch transfers and UTXO management](/beth/guides/batch-transfers-and-management/) * [BETH errors, retries, and troubleshooting](/beth/concepts-and-reference/errors-retries-and-troubleshooting/) * [BETH compatibility and release notes](/beth/concepts-and-reference/compatibility-and-release-notes/) ### Next step → **Prepare for failures safely:** [BETH errors, retries, and troubleshooting](/beth/concepts-and-reference/errors-retries-and-troubleshooting/). --- # Transfer and receive BETH URL: https://docs.bitsafe.finance/beth/guides/transfer-and-receive-beth/ [BETH overview](/beth/) · [BETH environments and prerequisites](/beth/get-started/environments-and-prerequisites/) · [Transfer and receive BETH](/beth/guides/transfer-and-receive-beth/) ### Outcome Send BETH from one Canton party to another, read the result of the transfer, and accept, reject, or cancel a transfer offer. ### Before you start * Use an Engineering-approved `bitsafe-token-lib`, `canton-lib`, DAR, and Canton compatibility row. This guide describes `bitsafe-token-lib` `v0.5.0`. * Confirm authentication, the sender party, the receiver party, and the registry URL for the intended environment. * Confirm the BETH instrument identifier. The identifier is the instrument ID `BETH` and the administrator party. The library matches both values exactly. * Query the sender's holdings, and confirm that the sender has enough available BETH. ### How a transfer settles A transfer has one of two outcomes: * **Offer:** the registry creates a transfer instruction. The receiver accepts or rejects it, or it expires at `execute_before`. The sender can cancel it before the receiver acts. * **Settled on submission:** the registry moves the BETH at once, and no offer exists. The registry does this for a self-transfer and for a receiver that pre-approved the sender. The library tells you which outcome occurred. Do not assume that the receiver must accept. ### 1. Send BETH Call `bitsafe_token::transfer::submit` as the sender. The call returns a `TransferReceipt`. ```rust let receipt = bitsafe_token::transfer::submit(bitsafe_token::transfer::Params { transfer: bitsafe_token::Transfer { sender: sender_party.clone(), receiver: receiver_party.clone(), amount: bitsafe_token::DamlDecimal::parse("0.01")?, instrument_id: bitsafe_token::InstrumentId { admin: decentralized_party_id.clone(), id: bitsafe_token::tokens::beth::TICKER.to_string(), }, requested_at: chrono::Utc::now().to_rfc3339(), execute_before: (chrono::Utc::now() + chrono::Duration::hours(168)).to_rfc3339(), input_holding_cids: None, // None lets the library select the sender's holdings meta: None, }, ledger_host: ledger_host.clone(), access_token: sender_token.clone(), registry_url: registry_url.clone(), decentralized_party_id: decentralized_party_id.clone(), }).await?; ``` Run the repository example with `ASSET=beth cargo run --example send`. ### 2. Read the transfer receipt The receipt contains three fields: | Field | Meaning | | -------------------- | ------------------------------------------------------------------------------------------------ | | `outcome` | `TransferOutcome::Pending` for an offer, or `TransferOutcome::Completed` for a settled transfer. | | `sender_change_cids` | The sender holdings that remain after the transfer. | | `update_id` | The Canton update identifier of the transaction. | `receipt.outcome.transfer_offer_cid()` returns the offer contract ID for a pending transfer. It returns `None` for a settled transfer. Record the offer ID, because the receiver and the sender need it in the next steps. ### 3. Receive BETH Skip this step when the outcome is `Completed`. The receiver already holds the BETH. For a pending transfer, the receiver authenticates as the receiver party and does one of these actions: * **Accept one offer:** call `bitsafe_token::accept::submit` with the offer contract ID and the receiver party. * **Accept all offers:** call `bitsafe_token::accept::accept_all`. It returns one result for each offer and the successful and failed counts. Read `failed_count` before you treat the step as done. * **Reject an offer:** call `bitsafe_token::reject::submit` with the offer contract ID and the receiver party. The BETH returns to the sender. To list the receiver's pending offers, run `ASSET=beth cargo run --example list_incoming_offers`. ### 4. Cancel an outgoing offer The sender can withdraw an offer that the receiver has not accepted or rejected: * `bitsafe_token::cancel_offers::submit` withdraws one offer. * `bitsafe_token::cancel_offers::withdraw_batch` withdraws a list of offers. * `bitsafe_token::cancel_offers::withdraw_all` withdraws all pending offers of the instrument. To list the sender's pending offers, run `ASSET=beth cargo run --example list_outgoing_offers`. To withdraw them, run `ASSET=beth cargo run --example cancel_offers`. ### Token Standard V2 Each operation in this guide also has a Token Standard V2 form in a `v2` submodule, such as `bitsafe_token::transfer::v2::submit`. The V2 transfer takes the sender and the receiver as `bitsafe_token::Account` values instead of party strings. The accept, reject, and cancel V2 forms take the same parameters as V1. Run the V2 transfer example with `ASSET=beth cargo run --example send_v2`. ### Expected result * The sender has a `TransferReceipt` and a recorded outcome for each transfer. * For a settled transfer, the receiver holds the BETH. * For an offer, the receiver accepted or rejected it, the sender cancelled it, or it expired. ### Troubleshooting | Symptom | Check | | ------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | | The receiver sees no offer. | Read the sender's receipt. A `Completed` outcome creates no offer, and the receiver already holds the BETH. | | The receiver's balance does not change. | Confirm the instrument ID and the administrator. The library ignores holdings of another administrator. | | Accept or reject fails. | Confirm that the token authenticates the receiver party and that the offer is still active. | | The transfer fails with insufficient funds. | Query the sender's holdings. Holdings locked in another offer are not available. | ### Technical sources * [`bitsafe-token-lib` README at `v0.5.0`](https://github.com/DLC-link/bitsafe-token-lib/blob/v0.5.0/README.md) * [Transfer implementation and receipt model](https://github.com/DLC-link/canton-lib/blob/v0.12.0/crates/token/src/transfer.rs) * [Accept implementation](https://github.com/DLC-link/canton-lib/blob/v0.12.0/crates/token/src/accept.rs) * [Reject implementation](https://github.com/DLC-link/canton-lib/blob/v0.12.0/crates/token/src/reject.rs) * [Cancel implementation](https://github.com/DLC-link/canton-lib/blob/v0.12.0/crates/token/src/cancel_offers.rs) * [Send example](https://github.com/DLC-link/bitsafe-token-lib/blob/v0.5.0/examples/send.rs) * [Reject example](https://github.com/DLC-link/bitsafe-token-lib/blob/v0.5.0/examples/reject_transfer.rs) ### Related pages * [Batch transfers and UTXO management](/beth/guides/batch-transfers-and-management/) * [Token standard and contract model](/beth/concepts-and-reference/token-standard-and-contract-model/) ### Next step → **Send to many receivers:** [Batch transfers and UTXO management](/beth/guides/batch-transfers-and-management/). --- # Batch transfers and management URL: https://docs.bitsafe.finance/beth/guides/batch-transfers-and-management/ [BETH overview](/beth/) · [BETH environments and prerequisites](/beth/get-started/environments-and-prerequisites/) · [Transfer and receive BETH](/beth/guides/transfer-and-receive-beth/) ### Outcome Distribute BETH to multiple Canton parties, record one result for each sender-side transfer, and manage BETH holdings without creating an unsafe retry or consolidation workflow. ### Terminology This guide uses **UTXO** as shorthand used by the current library for an active BETH holding contract. A BETH holding is a contract on Canton Network. Ethereum has no UTXOs. ### Before you start * Complete one sender-to-receiver transfer and receiver acceptance in the intended environment. * Use an Engineering-approved `bitsafe-token-lib`, `canton-lib`, DAR, and Canton compatibility row. * Confirm authentication, the sender party, the BETH instrument identifier, the registry service, and the intended environment. * Query the sender’s current holdings and outgoing offers. * Confirm the sender has enough available BETH for the full distribution. * Define a durable application-side row identifier and reconciliation record for every recipient. * Stop other processes from spending or restructuring the same sender’s holdings during the run. :::note A batch is not one atomic transfer. In `v0.5.0`, the library submits sender-side transfers sequentially. Each successful submission either creates a transfer offer that the receiver must accept, or settles the transfer on submission. The registry settles a self transfer, and a transfer to a receiver that pre-approved the sender. ::: ### Choose the batch interface | Interface | Use | Result handling | | ----------------------------------------- | --------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `bitsafe_token::batch::submit_from_csv()` | Read `receiver,amount` rows from a CSV file and submit a sequential distribution. | Returns successful and failed counts plus one result per row. `Ok` means that the batch ran, not that every row succeeded. Read `failed_count` before you treat the batch as done. It does not accept a callback. | | `bitsafe_token::distribute::submit()` | Submit an in-memory recipient list. | Returns successful and failed counts plus one result per row. It can call an asynchronous callback after each row completes. | For production-style reconciliation, prefer `bitsafe_token::distribute::submit()`, because only that interface accepts a durable callback. Each interface also has a Token Standard V2 form: `bitsafe_token::batch::v2::submit_from_csv()` and `bitsafe_token::distribute::v2::submit()`. The V2 forms take the sender as a `bitsafe_token::Account` instead of a party string. ### How the current sequential flow works At `v0.5.0`, the distribution flow: 1. Authenticates and refreshes the access token when required. 2. Queries all active sender holdings once at the start. 3. Uses those holding contract identifiers as the first transfer’s inputs. 4. Fetches transfer-factory context once and reuses it for the run. 5. Submits one transfer at a time. 6. Uses the sender change holdings returned by a successful row as the next row’s inputs. When a self transfer settles on submission, the new sender holdings also join those inputs. 7. Records success or failure for each row and then attempts the next row. This is a sequential chained flow. It is not concurrent, and it does not pre-split holdings. ### 1. Prepare and validate recipient input The repository example accepts this CSV shape: ``` receiver,amount receiver1-party::1220...,5.0 receiver2-party::1220...,3.5 ``` Before passing data to the library: * Reject empty receiver identifiers. * Validate every receiver against the intended environment. * Parse every amount as the supported decimal type. * Reject zero, negative, or amounts outside the documented policy limits. * Reject duplicate application-side row identifiers. * Review repeated receiver identifiers intentionally. Do not assume one receiver appears only once. * Sum all amounts and compare the total with the sender’s available balance. The CSV helper rejects malformed amounts and an empty recipient list. The reviewed source does not implement business-reference deduplication or complete recipient-policy validation. Perform those checks in the calling application. ### 2. Create a run record Create a durable run record before submission. Store: * Application run identifier. * Application row identifier. * Row index. * Receiver. * Amount. * Intended environment. * Submission state. * Transfer-offer contract identifier when available. * Canton update identifier when available. * Library reference when available. * Error and raw-response location, with secrets removed. #### Reference limitation in `v0.5.0` The optional `reference_base` generates a reference from the base value, sender, and receiver. It does not include the row index or amount. Repeated rows for the same receiver can therefore produce the same generated reference. Do not treat this generated value as a guaranteed per-row idempotency key. Keep a separate application-side row identifier and reconcile state before replay. ### 3. Check holdings and pending work Immediately before submission: 1. Query active BETH holdings for the sender. 2. Record the holding contract identifiers and total available amount. 3. Query pending outgoing offers and unresolved withdrawals. 4. Confirm no other batch, split, consolidation, redemption, or transfer process can consume the same holdings. 5. Apply the holding-count and transaction-size limits documented for the supported release. The batch implementation fetches holdings once. Concurrent mutations can make its chained input set stale. ### 4. Run a batch The simple repository example uses: ```bash ASSET=beth RECIPIENTS_CSV=recipients.csv cargo run --example batch_distribute ``` The callback example uses: ```bash ASSET=beth RECIPIENTS_CSV=recipients.csv cargo run --example batch_with_callback ``` Use placeholders for credentials and environment values. Never commit `.env` files, access tokens, passwords, or production party identifiers. ### 5. Record each callback result The callback receives one result after each sender-side submission attempt. | Field | Use | | -------------------- | ------------------------------------------------------------------------------------------------------------ | | `success` | Whether the library classified the sender-side submission and response parsing as successful. | | `transfer_index` | Zero-based position in the submitted recipient list. | | `receiver`, `amount` | Match the result to the intended row. Also verify the application-side row identifier. | | `transfer_offer_cid` | Track the created transfer instruction or offer. The value is empty when the transfer settled on submission. | | `update_id` | Correlate the result with the Canton update. | | `reference` | Store as supporting metadata. Do not assume uniqueness under the limitation above. | | `raw_response` | Retain securely for diagnostics when policy permits. Remove secrets before support escalation. | | `error` | Classify the row as failed or ambiguous and apply the approved recovery procedure. | Make the callback durable and safe to call once per completed attempt. If writing to a database, protect the application row from duplicate callback processing. ### 6. Reconcile the run Classify each row separately: * **Submitted:** The callback includes a transfer-offer contract identifier and Canton update identifier. This confirms sender-side submission, not receiver acceptance. * **Settled on submission:** The callback includes a Canton update identifier and no transfer-offer contract identifier. The receiver already holds the amount, and no acceptance step follows. * **Accepted:** The receiver accepted the intended offer, and both parties’ holdings reflect the completed transfer. * **Failed before submission:** Evidence proves that no ledger update committed. * **Ambiguous:** The request may have committed, but the client lacks a parseable or authoritative result. * **Rejected, cancelled, or expired:** The offer reached the corresponding terminal state. Use the versioned reference for exact state names and expiry policy. After the sender-side run, verify incoming offers with each receiver or the approved receiving service. Do not mark a distribution complete from `successful_count` alone. ### Partial failure and safe resume The reviewed implementation continues to later rows after a failed submission or response-parsing error. It preserves the last known input-holding list in memory. For production recovery: 1. Stop the run when an outcome is ambiguous. 2. Requery active holdings and outgoing offers from authoritative sources. 3. Match receiver, amount, application row identifier, offer identifier, update identifier, and available reference metadata. 4. Mark already-created offers as submitted. Do not create replacements for them. 5. Resume only rows proven not to have committed. 6. Build a new run from fresh holdings. Do not reuse a stale in-memory holding list. 7. Keep accepted, pending, failed, and ambiguous rows in separate states. Never rerun the complete CSV after partial success. ### Concurrency policy `bitsafe-token-lib` `v0.5.0` processes one distribution sequentially. Do not run parallel distributions, transfers, redemptions, splits, or consolidations from the same sender without an application-level lock and fresh-state strategy. Use the supported release limits for recipient count, total amount, execution duration, timeouts, and rate limits. ### Manage BETH holdings #### Inspect holdings Use the active-contract query or the consolidation count helper to record: * Holding count. * Holding contract identifiers. * Total amount. * Pending operations that reference those holdings. * Last successful reconciliation time. A high holding count can increase transaction size and operational complexity. Use the current operational limits when deciding whether to consolidate. #### Consolidate holdings The `v0.5.0` consolidation function performs a self-transfer with merge-split metadata. It can consolidate all active holdings or a selected set. If the party has fewer holdings than the supplied threshold, `check_and_consolidate()` does nothing. If the threshold is met or exceeded, it consolidates all queried holdings and returns the resulting holding contract identifiers. The repository example uses a configurable threshold and defaults that example to `10`. Treat this as example behavior, not a production limit. Use the threshold documented for the target environment. Run the example only after review: ```bash ASSET=beth CONSOLIDATION_THRESHOLD= cargo run --example consolidate_utxos ``` Before consolidation: * Reconcile pending transfers and withdrawals. * Confirm the selected holdings are still active. * Stop concurrent operations for the party. * Estimate the expected resulting holding count and transaction impact. * Record the input holding identifiers. After consolidation, query the party again and verify the total amount and returned holding identifiers. #### Split holdings The `v0.5.0` split function uses sequential self-transfers. It separates each requested amount in order, then feeds the returned change holdings into the next split. It returns output holding identifiers and remaining change identifiers. If a step fails, the function returns a `split::Error`. Its `partial` field lists the holdings that the earlier steps created. Use split only when an approved downstream workflow requires specific holding sizes. Confirm: * The requested amounts and order. * The selected input holdings. * The expected remaining change. * Behavior when requested amounts consume the exact available total. * The release-specific recovery procedure if a later split step fails. Do not split solely to prepare the sequential batch flow. The current batch implementation is designed to chain change holdings without pre-splitting. ### Expected result A completed operation has: * One durable record per recipient. * A reconciled sender-side result for every row. * Receiver acceptance or another approved terminal state for every created offer. * No ambiguous row left queued for automatic retry. * A final sender balance and holding set that match the reconciled run. * A recorded before-and-after holding set for every split or consolidation. ### Troubleshooting
SymptomCheckSafe next action
No recipients foundCSV path, header, and parsed row countCorrect the file. Do not submit an unreviewed replacement.
Invalid amountDecimal syntax and business amount rulesReject the row before any submission.
No holdings availableSender party, environment, active holdings, and pending operationsStop and reconcile the sender. Do not retry with another party implicitly.
Some rows succeed and later rows failPer-item results, current holdings, token refresh, and errorsDo not rerun the complete CSV. Requery authoritative state and resume only proven-uncommitted rows.
Ledger response exists but parsing failsRaw response, update visibility, outgoing offers, and client compatibilityTreat the row as ambiguous. Reconcile before any retry.
Sender-side success but receiver balance is unchangedIncoming offer, receiver acceptance, preapproval policy, rejection, cancellation, and expiryComplete or resolve the receiver-side flow. Do not duplicate the sender submission.
Generated references repeatRepeated receiver identifiers and shared reference_baseUse application-side row identifiers. Escalate before relying on the library reference for replay protection.
Consolidation returns an unexpected holding setInput holdings, concurrent operations, transaction response, and final active holdingsStop new operations and reconcile total amount and contract identifiers.
Split stops after creating earlier outputsCompleted split steps, current change holdings, and remaining requested amountsRequery holdings. Do not restart from the original input identifiers.
### Technical sources * [`bitsafe-token-lib` README at `v0.5.0`](https://github.com/DLC-link/bitsafe-token-lib/blob/v0.5.0/README.md) * [CSV batch helper](https://github.com/DLC-link/canton-lib/blob/v0.12.0/crates/token/src/batch.rs) * [Sequential distribution flow](https://github.com/DLC-link/canton-lib/blob/v0.12.0/crates/token/src/distribute.rs) * [Sequential chained transfer and result model](https://github.com/DLC-link/canton-lib/blob/v0.12.0/crates/token/src/transfer.rs) * [Batch CSV example](https://github.com/DLC-link/bitsafe-token-lib/blob/v0.5.0/examples/batch_distribute.rs) * [Callback example](https://github.com/DLC-link/bitsafe-token-lib/blob/v0.5.0/examples/batch_with_callback.rs) * [Consolidation implementation](https://github.com/DLC-link/canton-lib/blob/v0.12.0/crates/token/src/consolidate.rs) * [Consolidation example](https://github.com/DLC-link/bitsafe-token-lib/blob/v0.5.0/examples/consolidate_utxos.rs) * [Split implementation](https://github.com/DLC-link/canton-lib/blob/v0.12.0/crates/token/src/split.rs) ### Related pages * [Transfer and receive BETH](/beth/guides/transfer-and-receive-beth/) * [BETH authentication](/beth/get-started/authentication/) * [BETH errors, retries, and troubleshooting](/beth/concepts-and-reference/errors-retries-and-troubleshooting/) * [BETH compatibility and release notes](/beth/concepts-and-reference/compatibility-and-release-notes/) * [BETH SDK, API, and integration reference](/beth/concepts-and-reference/sdk-api-and-integration-reference/) ### Next step → **Plan safe recovery:** [BETH errors, retries, and troubleshooting](/beth/concepts-and-reference/errors-retries-and-troubleshooting/). --- # Architecture and trust boundaries URL: https://docs.bitsafe.finance/beth/concepts-and-reference/architecture-and-trust-boundaries/ [How BETH works](/beth/how-beth-works/) ### Architecture at a glance BETH connects ETH custody in the Ethereum bridge contract and event verification with private Canton contract workflows. This page owns the component map and trust boundaries. Lifecycle steps belong in [How BETH works](/beth/how-beth-works/); control requirements belong in [BETH security](/beth/concepts-and-reference/security/). ### Component map
ComponentResponsibilityPrimary boundary
Ethereum bridge contractReceive eligible deposits and release approved redemptionsContract logic, signature threshold, limits, upgrade governance, and Ethereum finality
Attestor NetworkVerify eligible events and participate in threshold authorizationIndependent operation, policy, and signing keys
BETH workflow servicesAssociate accounts and events, coordinate workflows, and reconcile stateAuthentication, availability, and correct state handling
Canton participants and partiesHost parties, contracts, and authorized commandsCanton identity, rights, topology, and privacy
BETH Daml packagesDefine holdings, transfers, accounts, credentials, and administrative behaviorApproved package versions and contract authorization
Client libraries and applicationsExpose supported workflows and submit authorized requestsPinned releases, credentials, validation, and retries
Proof of Reserve and reconciliationProvide scoped evidence about reserves and system stateCompleteness, freshness, source integrity, and stated limitations
### Trust boundaries #### ETH custody The Ethereum bridge contract holds the underlying ETH. The contract releases ETH only when it verifies signatures from a threshold of independent Attestor Network operators. Each operator signs with its own Ethereum key. The threshold is configurable, and the operator set can change. Safe multisig wallets hold the admin roles of the bridge contract. These roles can change the attestor set and the signature threshold, upgrade the contract through a timelock, set deposit and withdrawal limits, and pause the bridge. #### Attestor Network Event verification and signing authorization are separate responsibilities. No single operator should be presented as sufficient to authorize a custody action. The detailed signing model belongs in [BETH Attestor Network](/beth/concepts-and-reference/attestor-network-and-ethereum-signing/). #### Canton Canton records BETH contract state and applies authorization through parties, participant rights, package logic, and topology. Configurable sub-transaction privacy limits contract visibility to entitled parties; it does not hide Ethereum transactions. #### Integration services Clients authenticate separately to Canton and approved BETH services. They must validate networks, parties, addresses, package compatibility, and authoritative state before retrying an ambiguous request. #### Evidence Proof of Reserve demonstrates only the evidence and observation scope documented on [BETH Proof of Reserve](/beth/concepts-and-reference/proof-of-reserve/). It does not prove every application, custody, operational, or redemption property. ### Architecture limits This architecture does not by itself guarantee instant Ethereum confirmation, every external service’s availability, correct integrator configuration, protection from an authorized request containing the wrong destination, or complete coverage by one evidence source. ### Technical sources * [BitSafe token library](https://github.com/DLC-link/bitsafe-token-lib) * [Shared Canton library](https://github.com/DLC-link/canton-lib) * [Ethereum bridge](https://github.com/DLC-link/evm-asset-bridge) ### Related pages * [BETH token standard and contract model](/beth/concepts-and-reference/token-standard-and-contract-model/) * [BETH Attestor Network](/beth/concepts-and-reference/attestor-network-and-ethereum-signing/) * [BETH Proof of Reserve](/beth/concepts-and-reference/proof-of-reserve/) * [BETH security](/beth/concepts-and-reference/security/) ### Next step → **Review the control model:** [BETH security](/beth/concepts-and-reference/security/). --- # Token standard and contract model URL: https://docs.bitsafe.finance/beth/concepts-and-reference/token-standard-and-contract-model/ ### Purpose Use this page to understand how BETH represents tokens and workflows on Canton Network, which contracts participate in transfers and Ethereum bridge operations, and where integration responsibilities sit. This page explains the model. For implementation steps, use the dedicated mint, redeem, transfer, authentication, and SDK guides. ### Current token-standard boundary The reviewed `bitsafe-token-lib` `v0.5.0` release interacts with the Canton Token Standard V1 interfaces (CIP-0056) and V2 interfaces (CIP-0112). Eight operations have a V2 form in a `v2` submodule, such as `bitsafe_token::transfer::v2::submit`. The library uses token-standard holdings and transfer instructions for ordinary BETH movement, while BETH-specific account contracts coordinate mint and redemption workflows. The observed instrument identifier has two parts: * **Administrator:** the BETH registrar party for the selected environment. * **Instrument name:** `BETH`. Do not hard-code a registrar party, package ID, contract ID, or environment endpoint from an example. These values differ by environment and can change with upgrades. Use the discovery flow and token-standard naming documented for the supported release. :::note **Version boundary:** `bitsafe-token-lib` `v0.5.0` has Token Standard V2 (CIP-0112) entry points for eight operations. Allocation remains V1-only in this release. Confirm that the target registry supports the selected version before submitting a command. Use the compatibility reference for current token-standard support and migration guidance. ::: ### Contract model at a glance | Layer | Primary contracts or interfaces | Responsibility | | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | Token-standard layer | `Holding`, `TransferFactory`, `TransferInstruction`, `InstrumentConfiguration`, `Credential` (Minter role), `BurnMintFactory` | Represents BETH holdings, creates and resolves transfer instructions, identifies the instrument, and supplies governed mint or burn primitives. | | BETH bridge layer | `BETHDepositAccountRules`, `BETHDepositAccount`, `BETHWithdrawAccountRules`, `BETHWithdrawAccount`, `BETHWithdrawRequest` | Coordinates deposit account IDs, withdrawal destinations, pending redemption balances, and the asynchronous handoff between Canton and Ethereum workflows. | | Registry and service layer | Registry choice contexts, disclosed contracts, BETH account-rule responses and token-standard contract responses | Returns the contracts and context an authenticated client needs to exercise the intended ledger choice. | ### Holdings A BETH balance is represented by one or more active holding contracts rather than one mutable balance field. Integrations therefore need to: 1. Query active holdings for the authenticated party. 2. Confirm that each selected holding belongs to the intended BETH instrument. 3. Exclude holdings already locked or consumed by another workflow. 4. Select enough inputs for the operation. 5. Reconcile output and change holdings after submission. This contract-based model is why transfer, split, consolidation, mint, and redemption flows return or create new contract identifiers. Applications should treat those identifiers as operation state, not as permanent account numbers. ### Transfer contracts The reviewed V1 flow is instruction based: 1. The sender selects active BETH holdings. 2. The client requests a transfer choice context from the registry. 3. The client exercises `TransferFactory_Transfer` with the sender, receiver, amount, instrument identifier, selected holdings, execution window, and supplied context. 4. The ledger returns sender change holdings and one of two results. The registry creates a transfer-instruction contract, or it settles the transfer and creates the receiver’s holdings. 5. The receiver resolves an instruction through the supported acceptance flow. A settled transfer has no instruction to resolve. 6. Both parties reconcile active holdings and the transaction update identifier. A submitted transfer and a completed receipt are not necessarily the same event. User interfaces should distinguish an outgoing instruction from a holding that the receiver has accepted. Check the supported release for expiry, rejection, cancellation, preapproval, and safe retry behavior. ### Mint contracts Minting uses BETH-specific deposit-account contracts around the token-standard mint primitive. 1. The client obtains the current deposit-account rules from the BitSafe API. 2. The authenticated party exercises `BETHDepositAccountRules_CreateDepositAccount` with the intended owner and required credentials. 3. The ledger creates a `BETHDepositAccount` contract. 4. The client passes the deposit account ID to `depositETH` on the Ethereum bridge contract. 5. Ethereum deposit verification occurs outside `bitsafe-token-lib`. 6. After the approved verification and governance flow completes, token-standard holdings become available to the intended Canton party. The reviewed library creates the deposit account, queries its status, and builds the `depositETH` call. It does not send or monitor Ethereum transactions itself. Use the current operational reference for required credentials, Ethereum finality, completion states, timing, and recovery behavior. :::caution Use the `id` of the `BETHDepositAccount` as the `depositAccountId` parameter of the `depositETH` call. Use the contract ID only if the account has no `id` yet. A deposit with the wrong `depositAccountId` does not mint BETH, and the ETH can become stuck in the bridge. ::: ### Redemption contracts Redemption uses a withdrawal account and an asynchronous withdrawal request. 1. The client obtains the current withdrawal-account rules. 2. The authenticated party exercises `BETHWithdrawAccountRules_CreateWithdrawAccount` with the intended owner, Ethereum destination address, and required credentials. 3. The ledger creates a `BETHWithdrawAccount` contract. 4. The client selects eligible BETH holdings and exercises `BETHWithdrawAccount_Withdraw` with the owner's Minter credential. 5. The withdrawal choice checks the owner's Minter credential and the selected holdings. It then exercises `BurnMintFactory_BurnMint`, which burns the selected holdings and returns any change to the owner. 6. The updated withdrawal account records a pending balance. 7. The Attestor Network later creates a `BETHWithdrawRequest` and processes the Ethereum redemption. The withdrawal request is not created atomically with the initial ledger submission. Integrations must monitor the asynchronous request and verify Ethereum delivery before treating the workflow as complete. Use the current operational reference for credentials, address rules, minimums, fees, request states, polling, retries, and completion timing. ### Disclosed contracts and choice context Canton choices can require contracts that are not directly visible to the submitting party. The registry and BitSafe API return those contracts with the created-event data needed for disclosure. The client submits them alongside the exercise command. Redemption also uses a namespaced `ExtraArgs` context. The library supplies the instrument configuration contract and a withdrawal reason. The issuer-credentials list is empty, because BETH needs no issuer credential. Integrators should obtain this context from the supported source rather than reconstructing identifiers from copied examples. ### Package references and upgrades The reviewed client uses package-name template references for BETH account choices rather than pinning the concrete package ID that created an older contract. This allows Canton to resolve a commonly vetted package version during smart-contract upgrades. That behavior does not remove the need for compatibility checks. Before production use, validate the supported combination of: * Canton environment and participant release. * BETH DAR packages. * Digital Asset Registry Utility packages. * `bitsafe-token-lib` and shared `canton-lib` releases. * BitSafe API and authentication configuration. Use the maintained compatibility matrix as the source for supported component combinations. ### Responsibility boundaries | Component | Owns | Does not by itself prove | | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | | Canton participant and ledger | Contract state, authorization, transaction submission, and participant-visible events | Ethereum deposit or redemption completion | | Digital Asset Registry Utility | Token-standard factories, choice context, instrument configuration, and related disclosures used by the observed V1 and V2 flows | BETH-specific Ethereum bridge completion | | BETH account contracts | Deposit and withdrawal account state, owner and registrar roles, pending balances, and bridge request records | Ethereum finality without external verification | | BitSafe API | Current account rules and token-standard contracts used by the reviewed client | Authorization to bypass ledger choices or governance | | Attestor Network | Independent verification and threshold-governed Ethereum bridge processing under the approved production design | A fixed operator count, named operator list, or fixed threshold in durable public documentation | ### What integrators should record For each production operation, retain the minimum diagnostic evidence permitted by the organization’s security policy: * Environment and reviewed component versions. * Authenticated party and intended instrument, without exposing credentials. * Command or request identifier. * Input holding contract identifiers. * Resulting transfer, account, request, update, and change-holding identifiers where applicable. * Ethereum transaction hash for completed mint or redemption verification when available. * Timestamp and the last observed lifecycle state. Never place access tokens, passwords, private keys, or unredacted credential payloads in documentation, logs, or support tickets. ### Related implementation guides * [BETH environments and prerequisites](/beth/get-started/environments-and-prerequisites/) * [Mint BETH](/beth/guides/mint-beth/) * [Redeem BETH](/beth/guides/redeem-beth/) * [Transfer and receive BETH](/beth/guides/transfer-and-receive-beth/) * [BETH developer Quick Start](/beth/get-started/developer-quick-start/) ### Technical sources * [`DLC-link/bitsafe-token-lib` `v0.5.0` README](https://github.com/DLC-link/bitsafe-token-lib/blob/v0.5.0/README.md) * [`canton-lib` `crates/token/src/transfer.rs` at `v0.12.0`](https://github.com/DLC-link/canton-lib/blob/v0.12.0/crates/token/src/transfer.rs) * [`src/flows/canton_bridge_v1/deposit.rs` at `v0.5.0`](https://github.com/DLC-link/bitsafe-token-lib/blob/v0.5.0/src/flows/canton_bridge_v1/deposit.rs) * [`src/flows/canton_bridge_v1/withdraw.rs` at `v0.5.0`](https://github.com/DLC-link/bitsafe-token-lib/blob/v0.5.0/src/flows/canton_bridge_v1/withdraw.rs) * [`src/kits/evm/evm_asset_bridge.rs` at `v0.5.0`](https://github.com/DLC-link/bitsafe-token-lib/blob/v0.5.0/src/kits/evm/evm_asset_bridge.rs) * [`beth::mint::deposit_call` at `v0.5.0`](https://github.com/DLC-link/bitsafe-token-lib/blob/v0.5.0/src/tokens/beth/mod.rs#L225-L231) ### Related pages * [Mint BETH](/beth/guides/mint-beth/) * [Redeem BETH](/beth/guides/redeem-beth/) * [Transfer and receive BETH](/beth/guides/transfer-and-receive-beth/) * [BETH authentication](/beth/get-started/authentication/) * [BETH SDK, API, and integration reference](/beth/concepts-and-reference/sdk-api-and-integration-reference/) ### Next step → **Implement the model:** [BETH SDK, API, and integration reference](/beth/concepts-and-reference/sdk-api-and-integration-reference/). --- # Attestor Network and Ethereum signing URL: https://docs.bitsafe.finance/beth/concepts-and-reference/attestor-network-and-ethereum-signing/ [BETH architecture and trust boundaries](/beth/concepts-and-reference/architecture-and-trust-boundaries/) ### Attestor Network The Attestor Network is the set of independent institutional operators that verify eligible Ethereum events and sign redemptions for BETH custody workflows. Operator membership and signing policy can change, so check the maintained security reference for current operating details. ### How attestors sign a redemption Each attestor holds its own Ethereum signing key. For a redemption, each attestor signs a typed EIP-712 message. The message names the redemption, the destination address, the amount, and a deadline. The Ethereum bridge contract releases ETH only when it receives valid signatures from at least the threshold number of different attestors. The contract checks each signer against its list of attestors. No shared key or key share exists. The security benefit comes from the signature check in the contract, not from a special transaction type. ### What threshold signing does not do Threshold signing does not by itself: * Verify that a deposit or redemption request is valid. * Decide which redemption should be signed. * Protect a compromised operator application from approving bad input. * Guarantee service availability. * Replace monitoring, policy, access control, or incident response. ### Workflow boundary 1. The system identifies an eligible Ethereum deposit or redemption event. 2. Operators independently receive the approved signing context. 3. Each participant applies the current verification and authorization policy. 4. The required threshold of attestors signs the redemption. 5. An attestor submits the signatures to the Ethereum bridge contract, which checks them and releases ETH. 6. The redemption result proceeds through the workflow. ### Key lifecycle Each attestor generates, stores, backs up, and rotates its own Ethereum key. The bridge contract holds the list of attestor addresses. Adding, removing, or replacing an attestor is a role change on the contract. It does not need a key ceremony or a new contract. ### Availability and failure The network can continue only while enough eligible participants and required services are available under the active policy. One unavailable operator does not necessarily stop the network. Check the current service reference for applicable availability targets. ### Operator trust boundary Each operator must protect its infrastructure, credentials, signing key, software supply chain, and verification process. Independent operation reduces unilateral control. It does not remove the need to evaluate correlated failures or common software dependencies. ### Related pages * [BETH architecture and trust boundaries](/beth/concepts-and-reference/architecture-and-trust-boundaries/) * [BETH Proof of Reserve](/beth/concepts-and-reference/proof-of-reserve/) * [BETH security](/beth/concepts-and-reference/security/) ### Next step → **Review the complete control model:** [BETH security](/beth/concepts-and-reference/security/). --- # Proof of Reserve URL: https://docs.bitsafe.finance/beth/concepts-and-reference/proof-of-reserve/ ### What this page helps you do Use this page to: * Check BETH backing from public data. * Understand how the reserve total can be calculated independently from Ethereum data. * Identify what the evidence proves and what it does not prove. * Stop safely when data is stale, incomplete, or inconsistent. ### The reserve claim BETH is designed as an ETH-backed asset on Canton Network. The reserve claim is that the ETH held by the Ethereum bridge contract covers circulating BETH on a 1:1 basis. Use the maintained circulating-supply source, coverage formula, and freshness policy when evaluating the 1:1 reserve claim. A Chainlink Proof of Reserve feed for BETH is in development. BitSafe will announce it when it is available. ### Check BETH backing To perform a reserve check: 1. Read the ETH balance of the Mainnet bridge contract `0xb5d425d678B10949dD0f7bB0dd0427C47451D57E`. Use your own Ethereum node or a block explorer. Record the balance and the block number. 2. Read the circulating BETH supply from the BitSafe API: ```http GET /beth/v1/total-supply ``` The response is the supply in whole BETH, as a plain decimal number with up to 10 decimal places, for example `0.01`. Record the value and the time of the request. 3. Convert the balance from wei to ETH. One ETH is 10^18 wei. 4. Compare the reserve with the supply. The reserve covers the supply when the ETH balance is equal to or larger than the BETH supply. 5. Save the balance, block number, supply value, request time, and source links with your review record. **Expected outcome:** the ETH balance is equal to or larger than the BETH supply. The reserve and the supply can differ for a short time while a deposit or a redemption is pending. In that case, the reserve is larger than the supply. The baseline is 1:1 backing. If the reserve is smaller than the supply, stop and follow the support and incident path in [Security and trust index](/security-and-trust/). ### What this evidence proves When the inputs are complete and current, the check can show: * The ETH held by the bridge contract at the observed block. * The circulating BETH supply that the BitSafe API reports at the request time. * Whether the observed reserve amount is consistent with the fully backed claim. ### What this evidence does not prove Proof of Reserve is one control. It does not, by itself, prove: * That the reported BETH supply is correct. The BitSafe API reports the supply. For an independent read of the supply, use, for instance, the token metadata endpoint of the Digital Asset Utility registry. * Future reserve coverage. The result is valid only for its observation time and data freshness. * That redemption will complete within a specific time or at a specific cost. * That contracts, signing software, operators, APIs, or operational processes are free of defects. * That one Ethereum data provider is correct. High-assurance checks should compare independent sources. ### Handle stale, missing, or inconsistent data * Do not interpret missing data as a zero balance. * Do not treat a stale observation as current reserve evidence. * Do not compare a balance and a supply value from far apart in time. * Record the balance, block number, supply value, and request time before escalating. * Re-run the check with a second approved Ethereum data source. * Escalate through the approved support and incident path if the reserve is smaller than the supply or independent sources disagree. Use the maintained security and support references for the current freshness threshold, severity levels, contact, incident path, and retry interval. ### Technical sources * [Ethereum bridge](https://github.com/DLC-link/evm-asset-bridge) * [Digital Asset Utility registry: instrument metadata API](https://docs.digitalasset.com/api-reference/public/get-apitoken-standardv0registrars-registrymetadatav1instruments) ### Related pages * [How BETH works](/beth/how-beth-works/) * [BETH architecture and trust boundaries](/beth/concepts-and-reference/architecture-and-trust-boundaries/) * [BETH Attestor Network](/beth/concepts-and-reference/attestor-network-and-ethereum-signing/) * [BETH security](/beth/concepts-and-reference/security/) ### Next step → **Put the evidence in context:** [Security and trust index](/security-and-trust/). --- # Security URL: https://docs.bitsafe.finance/beth/concepts-and-reference/security/ [BETH architecture and trust boundaries](/beth/concepts-and-reference/architecture-and-trust-boundaries/) ### Security model BETH combines ETH custody in a threshold-signed Ethereum bridge contract, independent event verification, Canton authorization and privacy, versioned Daml packages, authenticated service integrations, and reserve evidence. No single control should be presented as the entire security model. ### Security layers | Layer | Primary control | Review focus | | ------------------ | ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | | ETH custody | Bridge contract that releases ETH only with threshold attestor signatures | Contract code, upgrade governance, limits, pause, attestor key lifecycle, and correlated risk | | Event verification | Attestor Network policy and evidence | Duplicate prevention, transaction validity, and authorization | | Canton contracts | Daml authorization and party rights | Package versions, choices, privacy, and migration | | Client integration | Authentication, least privilege, validation, and idempotency | Secrets, wrong-party risk, retries, and logs | | Backing evidence | Proof of Reserve and reconciliation | Scope, cadence, stale data, and exclusions | | Operations | Monitoring, change control, incident response, and support | Ownership, escalation, and recovery testing | ### Integrator responsibilities Integrators must verify parties, deposit account IDs, and Ethereum destination addresses, pin compatible releases, protect credentials, validate contract state, reconcile ambiguous submissions, and use approved support channels. BETH infrastructure cannot protect an application that sends an authorized command with incorrect inputs. ### Privacy boundary Canton limits contract visibility through sub-transaction privacy. Ethereum transactions remain visible on Ethereum. Application logs, support exports, and external systems can reveal information if operators do not protect them. ### Audits Each audit report identifies the contracts, services, release tags, and dates within its scope. An audit is evidence about reviewed components at a point in time. It is not a guarantee that every deployment or future release is secure. ### Vulnerability reporting Report suspected vulnerabilities through the private security contact listed in [Security and trust index](/security-and-trust/). Do not post unpatched vulnerabilities in public issues. Include the affected release, impact, reproduction steps, and safe contact details. ### Known limitations Check [BETH compatibility and release notes](/beth/concepts-and-reference/compatibility-and-release-notes/) for supported versions, operational dependencies, known issues, and applicable audit scope. ### Related pages * [BETH architecture and trust boundaries](/beth/concepts-and-reference/architecture-and-trust-boundaries/) * [BETH Attestor Network](/beth/concepts-and-reference/attestor-network-and-ethereum-signing/) * [BETH Proof of Reserve](/beth/concepts-and-reference/proof-of-reserve/) * [BETH authentication](/beth/get-started/authentication/) * [BETH compatibility and release notes](/beth/concepts-and-reference/compatibility-and-release-notes/) * [Security and trust index](/security-and-trust/) ### Next step → **Confirm the evidence and reporting path:** [Security and trust index](/security-and-trust/). --- # SDK, API, and integration reference URL: https://docs.bitsafe.finance/beth/concepts-and-reference/sdk-api-and-integration-reference/ ### Supported source libraries * [`bitsafe-token-lib`](https://github.com/DLC-link/bitsafe-token-lib): Workflows and examples for BitSafe assets. * [`canton-lib`](https://github.com/DLC-link/canton-lib): shared Canton API clients, utilities, and the Token Standard operations that `bitsafe-token-lib` re-exports. Pin approved release tags and keep their compatibility row together. ### Integration layers | Layer | Use | | ------------------------ | -------------------------------------------------------------------------- | | Generated Canton clients | Authenticate, query contracts, submit commands, and read updates | | BETH workflow functions | Balance, transfer, mint, redeem, account, and credential operations | | BitSafe API client | Retrieve approved account rules and token-standard contracts | | Ethereum bridge call | [Build the `depositETH` transaction for a deposit](/beth/guides/mint-beth/) | | Examples | Executable references for supported tasks | ### Recommended integration pattern 1. Load configuration through a typed layer. 2. Create authenticated Canton and BitSafe API clients. 3. Verify the party with a read-only query. 4. Query current contracts and runtime rules. 5. Validate the business request. 6. Submit one command with a unique reference where supported. 7. Read the authoritative result. 8. Reconcile Canton, application, and Ethereum identifiers. ### API reference policy Generated type and method documentation should remain in the repository or generated reference site. Public task guides should link to exact release documentation instead of copying full schemas. ### Examples to preserve Balance checks, sending, incoming and outgoing offers, accepting or cancelling offers, credentials, minting, redemption, account inspection, batch transfers, and UTXO management. ### Deposit event layout The `mint::Deposit` type in `bitsafe-token-lib` 0.5.0 uses this shared EVM event layout: ```solidity event Deposit( bytes32 indexed depositAccountIdHash, bytes depositAccountId, address indexed sender, uint256 amount, uint256 prevDepositBlock ); ``` `prevDepositBlock` identifies the previous deposit block for the same account. A zero value means no earlier deposit exists since deployment or the upgrade that adds this field. Two deposits for one account can share a block. The second then has `prevDepositBlock` equal to its own block number. The bridge view `lastDepositBlock(bytes32 depositAccountIdHash)` returns the block of the last deposit. The log filter must include the proxy address, topic0, and topic1 for the account. `mint::deposit_id_topic` computes topic1 from the deposit account ID. Read all matching logs in each block and use their lowest `prevDepositBlock` as the next link. The [bridge's deposit-link guide](https://github.com/DLC-link/evm-asset-bridge/blob/e6c3be776586054eeb43c33d33664788c2b88ed5/README.md#the-deposit-links) describes the complete walk. This view belongs to the bridge contract; the library provides no wrapper for it. Callers that construct `Deposit` values must supply the new field. `mint::DEPOSIT_EVENT_TOPIC` now matches only the five-field event: ```text 0xf3ca88974ec5963addc617fe6c0c359d7196759e318be6ab0cade940986e30e2 ``` Callers that scan historical deposits must also filter on the old topic: ```text 0xacaea730ea841fae3326f72a7ff746b6e06c646840526bcaf5dabee5fd887ef8 ``` Declare the old four-field layout in a separate `sol!` block to decode those logs. The new `Deposit` decoder rejects logs with the old topic. Decoding old data without checking the topic can silently produce an incorrect `prevDepositBlock` value. The library provides one event binding; callers select the decoder by the log topic. Check the bridge ABI for the deployment and block range that you query. ### Technical sources * [Shared EVM event binding at `v0.5.0`](https://github.com/DLC-link/bitsafe-token-lib/blob/v0.5.0/src/kits/evm/evm_asset_bridge.rs) * [`bitsafe-token-lib` examples guide at `v0.5.0`](https://github.com/DLC-link/bitsafe-token-lib/blob/v0.5.0/examples/README.md) * [Ethereum bridge contract](https://github.com/DLC-link/evm-asset-bridge) ### Related pages * [BETH developer Quick Start](/beth/get-started/developer-quick-start/) * [BETH authentication](/beth/get-started/authentication/) * [Transfer and receive BETH](/beth/guides/transfer-and-receive-beth/) * [Mint BETH](/beth/guides/mint-beth/) * [Redeem BETH](/beth/guides/redeem-beth/) * [BETH errors, retries, and troubleshooting](/beth/concepts-and-reference/errors-retries-and-troubleshooting/) * [BETH compatibility and release notes](/beth/concepts-and-reference/compatibility-and-release-notes/) ### Next step → **Validate the integration:** [BETH developer Quick Start](/beth/get-started/developer-quick-start/). --- # Errors, retries, and troubleshooting URL: https://docs.bitsafe.finance/beth/concepts-and-reference/errors-retries-and-troubleshooting/ ### First rule After a timeout or transport error, do not assume the command failed. Query the authoritative Canton, account, transfer-offer, or Ethereum state before retrying. ### Error classes | Class | Examples | Response | | ------------------ | --------------------------------------------- | ---------------------------------------------- | | Configuration | Wrong endpoint, party, package, network | Stop and correct configuration | | Authentication | Expired token, wrong audience, missing rights | Refresh or correct access, then re-query state | | Validation | Bad amount, destination, offer, or contract | Do not retry unchanged | | Conflict | Archived contract or concurrent action | Refresh active state and rebuild | | Transport | Timeout, disconnect, unavailable service | Determine commitment before retrying | | External lifecycle | Ethereum finality or attestation delay | Monitor the existing workflow | ### Idempotency pattern Use one business reference and command identifier for one intent where supported. Persist it before submission. On uncertainty, search by that reference and resulting contract or update identifiers. ### Retry policy Retry only operations documented as safe. Use bounded exponential backoff with jitter for read-only transport failures. Do not automatically retry mint, redemption, transfer acceptance, cancellation, or account creation without checking state. ### Support evidence Collect the environment, UTC time, release set, party, sanitized request reference, Canton update or contract identifiers, Ethereum transaction hash where relevant, error code, and logs with secrets removed. ### Related pages * [BETH authentication](/beth/get-started/authentication/) * [Mint BETH](/beth/guides/mint-beth/) * [Redeem BETH](/beth/guides/redeem-beth/) * [Transfer and receive BETH](/beth/guides/transfer-and-receive-beth/) * [BETH batch transfers and UTXO management](/beth/guides/batch-transfers-and-management/) * [Support and developer resources](/support-and-developer-resources/) ### Next step → **Still blocked?** [Support and developer resources](/support-and-developer-resources/). --- # Compatibility and release notes URL: https://docs.bitsafe.finance/beth/concepts-and-reference/compatibility-and-release-notes/ [BETH environments and prerequisites](/beth/get-started/environments-and-prerequisites/) ### 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. * Review [the chrono advisory follow-up](https://github.com/DLC-link/bitsafe-token-lib/issues/20) before adopting this release. * 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.5.0` | The release package manifest reports version `0.5.0`. | Repository baseline. Verify the target environment and support window. | | `canton-lib` | `v0.12.0` | `bitsafe-token-lib` `v0.5.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.5.0` package manifest. | Wire-client baseline. Verify the approved participant range. | | Canton participant | `3.6.1` for `bitsafe-token-lib` `v0.5.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.5.0`: `beth-0.2.0.dar` | The `v0.5.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.5.0` | `v0.12.0` | Verify in the maintained matrix | Bundled candidate: `0.2.0` | Verify in the maintained matrix | 18 November 2026, source review and local build | 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 :::note Release notes summarize public repository releases. They are not deployment announcements and do not prove that every environment supports the released files. ::: Each library publishes its release notes on GitHub: * [`bitsafe-token-lib` `v0.5.0` release notes](https://github.com/DLC-link/bitsafe-token-lib/releases/tag/v0.5.0) * [`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 | | ---------------------------------------------------------------------------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | | Four-field EVM `Deposit` in BETH and CHYPE | Five-field `Deposit` with `prevDepositBlock` | Update struct literals and event filters. Decode historical logs with a separate four-field binding and the old topic. | Breaking change in `bitsafe-token-lib` `v0.5.0`. CBTC APIs remain unchanged. | | Version-pinned UserService template ID in `AcceptCredentialOfferParams` | Package-name template ID that the library sets | Remove the `user_service_template_id` field from each `credentials::accept_credential_offer` call. | Removed in `canton-lib` `v0.12.0`. A participant that does not vet the old package version rejects the old accept. | | `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.5.0`](https://github.com/DLC-link/bitsafe-token-lib/releases/tag/v0.5.0) * [`bitsafe-token-lib` package manifest at `v0.5.0`](https://github.com/DLC-link/bitsafe-token-lib/blob/v0.5.0/Cargo.toml) * [`bitsafe-token-lib` changelog at `v0.5.0`](https://github.com/DLC-link/bitsafe-token-lib/blob/v0.5.0/CHANGELOG.md) * [BETH DAR guidance at `v0.5.0`](https://github.com/DLC-link/bitsafe-token-lib/tree/v0.5.0/dars) * [`canton-lib` changelog at `v0.12.0`](https://github.com/DLC-link/canton-lib/blob/v0.12.0/CHANGELOG.md) * [`canton-lib` package manifest at `v0.12.0`](https://github.com/DLC-link/canton-lib/blob/v0.12.0/Cargo.toml) ### Related pages * [BETH environments and prerequisites](/beth/get-started/environments-and-prerequisites/) * [Install and validate BETH DARs](/beth/get-started/install-and-validate-dars/) * [BETH SDK, API, and integration reference](/beth/concepts-and-reference/sdk-api-and-integration-reference/) * [BETH errors, retries, and troubleshooting](/beth/concepts-and-reference/errors-retries-and-troubleshooting/) * [Support and developer resources](/support-and-developer-resources/) ### Next step → **Use a supported path:** [BETH developer Quick Start](/beth/get-started/developer-quick-start/). --- # Overview URL: https://docs.bitsafe.finance/chype/ ### CHYPE brings native HYPE into Canton workflows CHYPE is a wrapped native HYPE token on Canton Network, built on BitSafe infrastructure and designed to represent HYPE at a 1:1 ratio. It gives institutions and application teams a path to hold, transfer, mint, redeem, and integrate HYPE-denominated value within Canton applications. This page explains the product and routes readers to the right task. Setup, lifecycle details, contract interfaces, backing evidence, and security controls have their own pages. ### What you can do * Hold and transfer CHYPE between authorized Canton parties using compatible applications. * Mint CHYPE following an eligible native HYPE deposit to the HyperEVM bridge. * Redeem CHYPE to a HyperEVM address that can receive native HYPE. * Integrate supported CHYPE workflows through pinned libraries, APIs, and the bridge interface. * Review bridge governance, privacy boundaries, backing evidence, and operational controls. Direct minting and redemption require onboarding and the CHYPE Minter credential. A deployed bridge does not, by itself, establish general availability or provider support. ### Choose a path | Goal | Canonical page | | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | Find a wallet, venue, or lending provider | [CHYPE Ecosystem](/chype/chype-ecosystem/) | | Understand the lifecycle | [How CHYPE works](/chype/how-chype-works/) | | Choose an operation | [Choose a CHYPE path](/chype/choose-a-chype-path/) | | Build an integration | [Developer quick start](/chype/get-started/developer-quick-start/) | | Review architecture and controls | [Architecture and trust boundaries](/chype/concepts-and-reference/architecture-and-trust-boundaries/); [Security](/chype/concepts-and-reference/security/) | | Check versions and upgrade requirements | [Compatibility and release notes](/chype/concepts-and-reference/compatibility-and-release-notes/) | ### Product boundaries CHYPE represents native HYPE. The current design does not stake reserve HYPE or automatically provide staking rewards. HYPE is held by the HyperEVM bridge, while CHYPE holdings and transfers are recorded on Canton. A Canton transfer does not move HYPE on HyperEVM for each transfer. Canton's configurable sub-transaction privacy applies to entitled Canton contract data. HyperEVM deposits, bridge balances, and redemptions remain visible on HyperEVM. CHYPE's design links issuance to eligible HYPE deposits and redemption to CHYPE burns. The evidence, accounting boundaries, pending-redemption treatment, and limitations belong in Proof of Reserve. HyperEVM redemption authorization and bridge administration are separate trust boundaries. ### Technical sources * [BitSafe token library](https://github.com/DLC-link/bitsafe-token-lib) * [Shared Canton library](https://github.com/DLC-link/canton-lib) * [HyperEVM bridge](https://github.com/DLC-link/evm-asset-bridge) * [CHYPE Faucet](https://faucet.bitsafe.finance/?network=devnet\&token=chype) ### Next step → **Understand the operating model:** [How CHYPE works](/chype/how-chype-works/). --- # CHYPE Ecosystem URL: https://docs.bitsafe.finance/chype/chype-ecosystem/ [CHYPE overview](/chype/) Use this page to evaluate third-party wallets, trading venues, and lending platforms for CHYPE. CHYPE support requires confirmation with each provider. :::caution Availability, supported environments, pairs, eligibility, fees, and product terms can change. Confirm current CHYPE support directly with the provider before transferring assets or integrating a service. Listings are informational, not a BitSafe endorsement. ::: ### Wallets CHYPE wallet availability requires confirmation with each provider. ### Trading venues CHYPE trading pairs and venue availability require confirmation with each provider. ### Lending protocols CHYPE collateral and borrowing support require confirmation with each provider. ### Choose a provider Before using a third-party service: 1. Confirm CHYPE support in the intended Canton environment and HyperEVM network where relevant. 2. Check regional, institutional, and onboarding eligibility. 3. Review custody, counterparty, bridge, smart-contract, liquidity, and operational risks. 4. Confirm current fees, pairs, collateral parameters, and withdrawal conditions. 5. Test the workflow with the smallest amount allowed by the environment and the organization's policy. ### Integrate CHYPE Wallets, trading venues, and lending platforms can use BitSafe’s open-source libraries as integration starting points: * [`bitsafe-token-lib`](https://github.com/DLC-link/bitsafe-token-lib) * [`canton-lib`](https://github.com/DLC-link/canton-lib) ### Related pages * [Overview](/chype/) * [Choose a CHYPE path](/chype/choose-a-chype-path/) * [Transfer and receive CHYPE](/chype/guides/transfer-and-receive-chype/) * [SDK, API, and integration reference](/chype/concepts-and-reference/sdk-api-and-integration-reference/) * [Security](/chype/concepts-and-reference/security/) ### Integrating CHYPE into an institutional product? Talk to BitSafe --- # How CHYPE works URL: https://docs.bitsafe.finance/chype/how-chype-works/ ### The short version CHYPE represents HYPE on Canton Network. A mint starts with HYPE deposited to the HyperEVM bridge contract. The system verifies the deposit and creates the corresponding CHYPE for the intended Canton party. A redemption consumes CHYPE and releases HYPE to the destination address of the party's withdrawal account. Transfers between Canton parties use Canton contracts and do not move the underlying HYPE for each transfer. ### The system has two connected ledgers * **HyperEVM:** holds the HYPE that backs CHYPE in the bridge contract and records deposits and redemption transactions. * **Canton Network:** records CHYPE holdings, transfers, account workflows, and the parties authorized to act. The integration layer links a HyperEVM event to its corresponding Canton workflow. It must prevent duplicate processing and preserve enough identifiers for reconciliation. ### Mint lifecycle 1. The Canton party obtains the required credential and current deposit-account rules. 2. The party creates a deposit account. 3. The deposit account ID identifies the account on HyperEVM. 4. The depositor verifies the network and the bridge contract address, then calls `depositETH` with the deposit account ID and the HYPE amount. 5. The system detects the deposit event and waits until HyperEVM finalizes the block. 6. Independent Attestor Network participants verify the eligible HyperEVM deposit. 7. The approved threshold authorizes the mint workflow. 8. CHYPE is created for the intended Canton party. 9. The HyperEVM transaction, account, attestation, Canton update, and resulting holding are reconciled. ### Transfer lifecycle A Canton transfer does not redeem HYPE. The sender creates a transfer offer for a receiver. The receiver inspects and accepts the intended offer unless an approved preapproval flow applies. Canton archives or updates the relevant contracts and creates the receiver’s new holding state. ### Redemption lifecycle 1. The party validates a HyperEVM destination address. 2. The party creates or selects a withdrawal account using current rules. 3. The application selects sufficient CHYPE holdings. 4. The party submits the redemption. 5. The Canton contract flow consumes the applicable CHYPE state. 6. The approved threshold of attestors signs the redemption, and the HyperEVM bridge contract releases HYPE after it verifies the signatures. 7. The application tracks completion on HyperEVM and Canton. 8. The records are reconciled to one request. ### Who does what | Role | Responsibility | Boundary | | ------------------------ | --------------------------------------------------------------------------------------- | --------------------------------------------------------- | | CHYPE holder | Owns Canton holdings and initiates supported actions | Can act only with the party’s authorization | | BitSafe services | Coordinate account and integration workflows | Cannot be described as able to move reserves unilaterally | | Attestor Network | Verifies eligible HyperEVM deposits and signs redemptions under threshold authorization | No single operator is sufficient | | HyperEVM bridge contract | Holds deposited HYPE and releases it against a threshold of attestor signatures | Enforces its own limits and can be paused | | Canton participant | Hosts the party and submits or observes authorized Canton actions | Visibility follows Canton entitlements | | HyperEVM network | Records deposits and redemption transactions | Finality and fee behavior are external to Canton | ### Backing and verification CHYPE is intended to remain backed 1:1 by HYPE. Public documentation should distinguish: * HYPE reserves visible in the HyperEVM bridge contract. * CHYPE supply and contract state visible to entitled Canton parties. * Proof of Reserve evidence and its exact coverage. * Operational reconciliation performed by the system. ### Failure boundaries A workflow can pause because of HyperEVM finality delays, bridge limits or a paused bridge, service availability, Canton connectivity, authentication, incompatible packages, insufficient approvals, or an ambiguous prior submission. Clients must query authoritative state before retrying. ### Related guides * [Mint CHYPE](/chype/guides/mint-chype/) * [Redeem CHYPE](/chype/guides/redeem-chype/) * [Transfer and receive CHYPE](/chype/guides/transfer-and-receive-chype/) * [CHYPE architecture and trust boundaries](/chype/concepts-and-reference/architecture-and-trust-boundaries/) ### Technical sources * [`bitsafe-token-lib` repository](https://github.com/DLC-link/bitsafe-token-lib) * [`canton-lib` repository](https://github.com/DLC-link/canton-lib) * [`evm-asset-bridge` repository](https://github.com/DLC-link/evm-asset-bridge) * [CHYPE Faucet](https://faucet.bitsafe.finance/?network=devnet\&token=chype) ### Next step → **Choose an operation:** [Choose a CHYPE path](/chype/choose-a-chype-path/). --- # Choose a CHYPE path URL: https://docs.bitsafe.finance/chype/choose-a-chype-path/ Choose the path that matches your role and immediate task. Start with a read-only check before any state-changing workflow. ### Institutions and trading firms Start with [CHYPE overview](/chype/), then review transfer operations and the security model. Use the mint or redemption guides only if your organization runs the required Canton infrastructure and has approved access. ### Application developers 1. Review [CHYPE environments and prerequisites](/chype/get-started/environments-and-prerequisites/). 2. Complete [CHYPE developer Quick Start](/chype/get-started/developer-quick-start/). 3. [Install and validate CHYPE DARs](/chype/get-started/install-and-validate-dars/). 4. Choose the [Transfer and receive CHYPE](/chype/guides/transfer-and-receive-chype/), [Mint CHYPE](/chype/guides/mint-chype/), or [Redeem CHYPE](/chype/guides/redeem-chype/) integration. 5. Add [CHYPE authentication](/chype/get-started/authentication/), reconciliation, and [CHYPE errors, retries, and troubleshooting](/chype/concepts-and-reference/errors-retries-and-troubleshooting/). ### Canton operators Start with [CHYPE compatibility and release notes](/chype/concepts-and-reference/compatibility-and-release-notes/), [Install and validate CHYPE DARs](/chype/get-started/install-and-validate-dars/), [CHYPE authentication](/chype/get-started/authentication/), monitoring, and recovery. Confirm the participant and package state before enabling an application team. ### Security reviewers Review [CHYPE architecture and trust boundaries](/chype/concepts-and-reference/architecture-and-trust-boundaries/), [CHYPE Attestor Network](/chype/concepts-and-reference/attestor-network-and-hyperevm-signing/), [CHYPE Proof of Reserve](/chype/concepts-and-reference/proof-of-reserve/), [CHYPE authentication](/chype/get-started/authentication/), [CHYPE security](/chype/concepts-and-reference/security/), and [CHYPE compatibility and release notes](/chype/concepts-and-reference/compatibility-and-release-notes/). Match every claim to a release and approved evidence source. ### Task map | Goal | Start here | | ---------------------- | ------------------------------------------------------------------ | | Evaluate CHYPE | [How CHYPE works](/chype/how-chype-works/) | | Connect an application | [CHYPE developer Quick Start](/chype/get-started/developer-quick-start/) | | Mint | [Mint CHYPE](/chype/guides/mint-chype/) | | Redeem | [Redeem CHYPE](/chype/guides/redeem-chype/) | | Transfer | [Transfer and receive CHYPE](/chype/guides/transfer-and-receive-chype/) | | Review security | [CHYPE security](/chype/concepts-and-reference/security/) | ### Next step → **New to CHYPE development?** [CHYPE developer Quick Start](/chype/get-started/developer-quick-start/). --- # Environments and prerequisites URL: https://docs.bitsafe.finance/chype/get-started/environments-and-prerequisites/ [CHYPE overview](/chype/) ### Before you start Choose the CHYPE operation you need to perform before configuring an environment. Balance queries, transfers, minting, redemption, batch distribution, and UTXO management do not all share the same prerequisites. ### Choose an environment | Environment | Use it for | Before proceeding | | ----------- | ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | Development | Local development and early workflow testing | Confirm the current participant, registry, BitSafe API, credential, and test-asset setup. | | Testnet | Integration testing against shared infrastructure | Confirm endpoint ownership, faucet availability, reset policy, and differences from production. | | Mainnet | Production workloads | Use only an Engineering-approved compatibility row, production credentials, monitoring, recovery procedures, and security review. | Obtain current endpoints, party identifiers, and package identifiers from the maintained environment reference. Check its owner and last-verified date before use. #### HyperEVM bridge contracts Canton Devnet and Testnet both use HyperEVM testnet, with a separate bridge contract for each. Canton Mainnet uses HyperEVM Mainnet. | Environment | HyperEVM network | Bridge contract | | ----------- | ----------------------------- | -------------------------------------------- | | Devnet | HyperEVM testnet (chain ID `998`) | `0xfBC38458ffb91D6Fd731151D46345E89ffc42358` | | Testnet | HyperEVM testnet (chain ID `998`) | `0x1E5439257A314d11e6b0779297Ca92887Ed56087` | | Mainnet | HyperEVM (chain ID `999`) | `0x2940FcBb3C32901Df405da0E96fd97D1E2a53f34` | Each address is an upgradeable proxy, so the address stays the same when the contract code is upgraded. `bitsafe-token-lib` `v0.5.0` uses these addresses, and the `ENVIRONMENT` value selects one. ### Core prerequisites All CHYPE development paths require: * Access to a supported Canton participant. * A Canton party authorized for the intended operation. * A supported authentication configuration and a safe method for storing credentials. * A compatible Rust toolchain when using the current Rust library. * A pinned `bitsafe-token-lib` release and compatible shared `canton-lib` crates. * Network access to the required Canton and external service endpoints. * A test plan that states the expected ledger and application result. ### Operation-specific prerequisites | Operation | Additional prerequisites | | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | Check balances or contracts | Ledger host, authenticated party, and compatible query interface. | | Send, receive, accept, reject, or cancel | Digital Asset Registry Utility components, receiver party details, required transfer context, and sufficient holdings. | | Mint CHYPE | BitSafe API access, required Minter credential, compatible CHYPE DAR packages, account rules, and a HyperEVM deposit flow. | | Redeem CHYPE | BitSafe API access, required Minter credential, compatible CHYPE DAR packages, sufficient holdings, and a valid HyperEVM destination address. | | Batch distribution | Transfer prerequisites plus recipient input validation, limits, callbacks or result capture, and reconciliation. | | UTXO management | Current holdings, approved split or consolidation policy, and a clear reason for changing the holding layout. | ### Install compatible components The examples on this page use: * `bitsafe-token` package version `0.5.0`. * `canton-lib` dependencies pinned to `v0.12.0`. * A Canton API client generated from Canton `3.6.1` specifications. For deployment, use the approved compatibility matrix for the BitSafe token library, shared Canton library, Canton version, DAR packages, API behavior, and target environment. ### Configure safely Configuration falls into four groups: 1. **Canton connection:** ledger host and party identity. 2. **Authentication:** approved identity-provider host, realm or audience, client identity, and secret-handling method. 3. **CHYPE network:** the `ENVIRONMENT` value (`devnet`, `testnet`, or `mainnet`). It selects the Decentralized Party, the registry, the BitSafe API, and the HyperEVM bridge for the target network. 4. **Mint and redeem:** BitSafe API selection and HyperEVM destination details where needed. Never commit `.env` files, tokens, passwords, client secrets, party-specific credentials, or production addresses. Use placeholders in public examples and document how readers obtain real values through approved channels. ### Preflight checklist * [ ] The target environment is approved for the intended test. * [ ] The Canton participant is reachable. * [ ] Authentication succeeds for the intended party. * [ ] The pinned library set builds successfully. * [ ] Required DAR packages are installed and validated. * [ ] Registry and BitSafe services required by the operation are reachable. * [ ] The party has the required credential and holdings. * [ ] The expected result and rollback or recovery path are documented. * [ ] Logs and identifiers needed for support can be collected without exposing secrets. ### Verify the setup Start with a read-only operation such as a connection or balance check. A successful preflight should confirm: * Authentication completed. * The intended party was used. * The ledger query returned a valid response. * The application can parse the response with the pinned library set. Continue to a state-changing operation only after the read-only check passes. ### Technical sources * [`bitsafe-token-lib` `v0.5.0`](https://github.com/DLC-link/bitsafe-token-lib/tree/v0.5.0) * [`bitsafe-token-lib` environment example](https://github.com/DLC-link/bitsafe-token-lib/blob/v0.5.0/.env.example) * [CHYPE DAR guidance](https://github.com/DLC-link/bitsafe-token-lib/tree/v0.5.0/dars) * [`canton-lib` `v0.12.0`](https://github.com/DLC-link/canton-lib/tree/v0.12.0) * [CHYPE network values in `bitsafe-token-lib` `v0.5.0`](https://github.com/DLC-link/bitsafe-token-lib/blob/v0.5.0/src/tokens/chype/mod.rs#L40-L67) ### Related pages * [CHYPE developer Quick Start](/chype/get-started/developer-quick-start/) * [Install and validate CHYPE DARs](/chype/get-started/install-and-validate-dars/) * [CHYPE authentication](/chype/get-started/authentication/) * [Mint CHYPE](/chype/guides/mint-chype/) * [Redeem CHYPE](/chype/guides/redeem-chype/) * [Transfer and receive CHYPE](/chype/guides/transfer-and-receive-chype/) * [CHYPE compatibility and release notes](/chype/concepts-and-reference/compatibility-and-release-notes/) ### Next step → **Verify your setup:** [CHYPE developer Quick Start](/chype/get-started/developer-quick-start/). --- # Developer quick start URL: https://docs.bitsafe.finance/chype/get-started/developer-quick-start/ [CHYPE overview](/chype/) · [CHYPE environments and prerequisites](/chype/get-started/environments-and-prerequisites/) ### What you will do 1. Prepare a supported Rust environment. 2. Check out a pinned `bitsafe-token-lib` release. 3. Configure Canton and authentication values without committing secrets. 4. Run the balance-check example. 5. Verify that the response belongs to the intended party. This read-only outcome is intentionally smaller than minting or transferring CHYPE. It verifies the core connection before you create accounts or submit ledger changes. ### Prerequisites * Access to an approved development or test environment. * A supported Canton participant and party. * Approved authentication credentials for that party. * Git and a compatible Rust toolchain. * Network access to the Canton participant and identity provider. * A secure local method for storing environment values. ### 1. Check out the reviewed source ```bash git clone https://github.com/DLC-link/bitsafe-token-lib.git cd bitsafe-token-lib git checkout v0.5.0 ``` Use an approved release tag. Do not use `main` in production instructions. ### 2. Create local configuration ```bash cp .env.example .env ``` Fill only the values required for the balance check: * Canton JSON Ledger API host, including the API path. * Target Canton party. * Approved identity-provider and client values required by the selected authentication flow. * The `ENVIRONMENT` value: `devnet`, `testnet`, or `mainnet`. * The `ASSET` value: `chype`. Do not paste real credentials into documentation, issue reports, shell history, or source control. ### 3. Build the example ```bash cargo build --example check_balance ``` A successful build confirms that the selected Rust toolchain can resolve the pinned CHYPE and shared Canton dependencies. ### 4. Run the balance check ```bash cargo run --example check_balance ``` ### Expected result The command should: * Authenticate successfully. * Query active CHYPE holdings for the configured party. The query keeps only holdings whose instrument ID and admin both match the CHYPE instrument. * Report the party’s balance and holding count, including a valid zero-balance result where applicable. * Exit without exposing access tokens or passwords. :::note Output fields vary by supported release and environment. Verify the response belongs to the intended party, and never substitute a fabricated balance or contract identifier when testing an integration. ::: ### If the check fails | Symptom | Check | Next action | | ------------------------ | ------------------------------------------------------------------------- | --------------------------------------------------------------------------- | | Authentication fails | Provider URL, realm or audience, client, grant type, secret, token claims | Use the canonical Authentication guide and confirm the party authorization. | | Connection fails | Ledger host, DNS, TLS, proxy, and network access | Verify the participant endpoint with the environment owner. | | No holdings are returned | Target party, environment, and whether zero balance is valid | Confirm the configured party before attempting a state-changing operation. | | Build or type errors | Checked-out tag, Rust toolchain, lockfile, and shared library access | Return to the approved compatibility matrix. | | Response parsing fails | Canton and library compatibility | Capture sanitized output and escalate with the version set. | ### Next steps After the balance check passes, choose one task: * [Transfer and receive CHYPE](/chype/guides/transfer-and-receive-chype/). * Create a deposit account and follow [Mint CHYPE](/chype/guides/mint-chype/). * Create a withdrawal account and follow [Redeem CHYPE](/chype/guides/redeem-chype/). * Use [CHYPE SDK, API, and integration reference](/chype/concepts-and-reference/sdk-api-and-integration-reference/) to integrate balance and transfer behavior into a wallet or application. ### Technical sources * [`bitsafe-token-lib` `v0.5.0`](https://github.com/DLC-link/bitsafe-token-lib/tree/v0.5.0) * [Balance-check example](https://github.com/DLC-link/bitsafe-token-lib/blob/v0.5.0/examples/check_balance.rs) * [Examples guide](https://github.com/DLC-link/bitsafe-token-lib/blob/v0.5.0/examples/README.md) ### Related pages * [Install and validate CHYPE DARs](/chype/get-started/install-and-validate-dars/) * [CHYPE authentication](/chype/get-started/authentication/) * [Mint CHYPE](/chype/guides/mint-chype/) * [Redeem CHYPE](/chype/guides/redeem-chype/) * [Transfer and receive CHYPE](/chype/guides/transfer-and-receive-chype/) * [CHYPE SDK, API, and integration reference](/chype/concepts-and-reference/sdk-api-and-integration-reference/) * [CHYPE errors, retries, and troubleshooting](/chype/concepts-and-reference/errors-retries-and-troubleshooting/) ### Next step → **Build your first workflow:** [Transfer and receive CHYPE](/chype/guides/transfer-and-receive-chype/). --- # Install and validate DARs URL: https://docs.bitsafe.finance/chype/get-started/install-and-validate-dars/ [CHYPE environments and prerequisites](/chype/get-started/environments-and-prerequisites/) ### Outcome Upload the CHYPE DAR packages required for minting and redemption to a Canton participant, then confirm that the expected CHYPE packages are present. :::note CHYPE DAR packages are required for minting and redemption, according to the `bitsafe-token-lib` `v0.5.0` DAR guidance. They are not required for sending or receiving CHYPE or for UTXO management. ::: ### Before you start You need: * Administrative access to the target Canton participant. * An approved connection to the participant Admin API. The repository examples use `localhost:5002`; use the endpoint and connection method documented for the target environment. * A participant administrator JWT if the Admin API requires authentication. * `grpcurl`, `jq`, and `base64` for the recommended upload path. * A Rust toolchain for the `check_dars` validation example. * The pinned [`bitsafe-token-lib` `v0.5.0` release](https://github.com/DLC-link/bitsafe-token-lib/releases/tag/v0.5.0). * The current compatibility row for the target Canton version, CHYPE DAR release, and environment. :::note Treat administrator tokens as secrets. Retrieve them through the approved secret-management process. Do not commit tokens, add them to documentation, or leave them in a modified copy of the upload script. ::: ### 1. Get the pinned DAR release ```bash git clone https://github.com/DLC-link/bitsafe-token-lib.git cd bitsafe-token-lib git checkout v0.5.0 ``` Confirm that the repository contains `dars/upload_dars.sh`, `dars/dependencies/`, and `dars/chype/`. ### 2. Confirm the Admin API connection Establish the approved port-forward or network path to the participant Admin API. If the target differs from the repository default `localhost:5002`, set the `canton_admin_api_url` environment variable: ```bash export canton_admin_api_url="" ``` Do not proceed until the endpoint is confirmed to belong to the intended participant and environment. ### 3. Configure authentication If the Admin API requires authentication, expose the administrator token to the script through the `jwt_token` environment variable: ```bash export jwt_token="" ``` If the Admin API does not require authentication, leave `jwt_token` empty. Follow the authentication flow documented for the target environment. ### 4. Upload the DARs The recommended repository path uses the gRPC upload script. Pass the asset name to the script: ```bash dars/upload_dars.sh chype ``` The script uploads: 1. Dependency DARs from `dars/dependencies/`. 2. CHYPE DARs from `dars/chype/`. For every upload, the script requests package vetting and synchronized vetting. The script stops at the first DAR that fails to upload. Canton skips a DAR that is already present, so the repository guidance describes the script as safe to run again. :::note Verify the upload response itself. Do not treat the script's printed success line as sufficient proof that the Admin API accepted every package. ::: ### 5. Check the installed CHYPE DARs The repository includes a Rust example that compares the DARs in `dars/dependencies/` and `dars/chype/` with the packages on the participant: ```bash ASSET=chype cargo run --example check_dars ``` The example reads `LEDGER_HOST` and the Keycloak values from `.env`. It does not need `ENVIRONMENT` or `PARTY_ID`. The example prints `PASS` when every required package is present. Otherwise, it prints `FAIL`, lists each missing package, and exits with a non-zero code. Record this output with the environment and release tag used for the installation. Remove tokens and other sensitive values before sharing diagnostic output. ### 6. Verify the result A successful installation should meet all of these checks: * [ ] Every expected dependency upload returned an accepted or already-present result. * [ ] Every expected CHYPE upload returned an accepted or already-present result. * [ ] `check_dars` reports `PASS` for the CHYPE DAR set. * [ ] The recorded package set matches the Engineering-approved release manifest for the target environment. * [ ] A read-only CHYPE preflight succeeds before any mint or redemption is attempted. :::note The `check_dars` example is a presence check, not a complete compatibility test. It does not verify application behavior or compatibility with the participant version. Complete the release-specific acceptance test after checking the maintained package manifest. ::: ### Expected result The target participant contains the approved CHYPE and dependency DAR set for the selected environment. The `check_dars` result shows every expected package as present, and the environment passes the approved read-only preflight. ### Troubleshooting | Symptom | Check | Next action | | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | | Connection refused or unavailable | Port-forward, host, port, participant identity, and Admin API availability. | Restore the approved Admin API connection. Do not switch environments or ports by trial and error. | | Unauthenticated or permission denied | Whether the Admin API requires a token and whether the token has participant administrator permissions. | Obtain a new token through the approved process. Do not paste the token into a support ticket. | | `check_dars` reports missing packages | Target participant, upload responses, the `ASSET` value, and the ledger connection. | Stop before minting or redemption. Collect redacted logs and escalate with the release tag and environment. | | Some packages appear but the release set is incomplete | Dependency and CHYPE upload responses, release manifest, and package vetting status. | Do not mix releases. Reconcile against the approved manifest before retrying. | ### Alternative Canton upload path The repository also includes the Canton console scripts `00_UploadDars.sc` and `00_ValidateDars.sc`. In `v0.5.0`, these scripts upload and list CBTC DARs only. Use the recommended gRPC path for CHYPE. ### Technical sources * [`bitsafe-token-lib` `v0.5.0` DAR guidance](https://github.com/DLC-link/bitsafe-token-lib/blob/v0.5.0/dars/README.md) * [Recommended gRPC upload script](https://github.com/DLC-link/bitsafe-token-lib/blob/v0.5.0/dars/upload_dars.sh) * [DAR check example](https://github.com/DLC-link/bitsafe-token-lib/blob/v0.5.0/examples/check_dars.rs) * [DAR inventory script](https://github.com/DLC-link/bitsafe-token-lib/blob/v0.5.0/dars/00_ValidateDars.sc) * [Alternative Canton upload script](https://github.com/DLC-link/bitsafe-token-lib/blob/v0.5.0/dars/00_UploadDars.sc) * [Scala prerequisites](https://github.com/DLC-link/bitsafe-token-lib/blob/v0.5.0/dars/scala-prerequisites.md) ### Related pages * [CHYPE environments and prerequisites](/chype/get-started/environments-and-prerequisites/) * [CHYPE authentication](/chype/get-started/authentication/) * [Mint CHYPE](/chype/guides/mint-chype/) * [Redeem CHYPE](/chype/guides/redeem-chype/) * [CHYPE compatibility and release notes](/chype/concepts-and-reference/compatibility-and-release-notes/) ### Next step → **Configure access:** [CHYPE authentication](/chype/get-started/authentication/). --- # Authentication URL: https://docs.bitsafe.finance/chype/get-started/authentication/ [CHYPE developer Quick Start](/chype/get-started/developer-quick-start/) ### Authentication surfaces CHYPE integrations can authenticate to more than one service: * **Canton Ledger API:** submit commands and query contract state for an authorized party. * **Canton Admin API:** perform privileged participant operations such as package management. Most CHYPE clients should not need this surface. * **BitSafe APIs:** obtain account rules and participate in approved mint or redemption workflows. * **HyperEVM account:** initiate deposits to the HyperEVM bridge and receive redemptions on the HyperEVM network. * **Source and artifact systems:** access approved repositories or private release artifacts where required. ### Use separate identities Use distinct clients and credentials for development, test, and production. Separate administrative credentials from application credentials. Grant only the party rights and API scopes required for the workflow. ### Configuration categories A client can require an identity-provider URL, realm or audience, client identifier, client secret or approved key, grant type, token endpoint, Canton user, and target party. Exact variable names belong in the versioned configuration reference. ### Safe setup 1. Create or obtain the approved service identity. 2. Assign the minimum Canton `actAs` and `readAs` rights. 3. Configure the approved audience and scopes. 4. Store secrets in a secret manager or protected local store. 5. Request a token through the approved flow. 6. Validate issuer, audience, expiry, and party authorization. 7. Run a read-only balance query before submitting a command. ### Operational rules * Never place tokens or secrets in documentation, screenshots, logs, shell history, or source control. * Rotate credentials under an approved process. * Treat authentication success and party authorization as separate checks. * Do not retry a state-changing command only because token refresh or transport failed. * Sanitize support evidence before sharing it. ### Common failures | Failure | Check | | ------------------------------- | ---------------------------------------------------------------------- | | Token request rejected | Provider URL, client, secret, grant, realm, and network access | | Token accepted but query denied | Audience, scopes, Canton user rights, and party | | Works in one environment only | Environment-specific client, endpoints, trust store, and party mapping | | Intermittent failures | Clock skew, token expiry, refresh behavior, and connection reuse | ### Related pages * [CHYPE environments and prerequisites](/chype/get-started/environments-and-prerequisites/) * [CHYPE developer Quick Start](/chype/get-started/developer-quick-start/) * [Install and validate CHYPE DARs](/chype/get-started/install-and-validate-dars/) * [CHYPE SDK, API, and integration reference](/chype/concepts-and-reference/sdk-api-and-integration-reference/) * [CHYPE security](/chype/concepts-and-reference/security/) ### Next step → **Test the connection:** [CHYPE developer Quick Start](/chype/get-started/developer-quick-start/). --- # Integrating CHYPE URL: https://docs.bitsafe.finance/chype/guides/integrating-chype/ Integrate CHYPE into a Canton wallet, DEX, or protocol. Use the same asset identifiers and registry URLs for each integration. Minting and redemption are separate workflows. ### Asset information Use the fields for the intended environment. In Canton Token Standard calls, use the Registrar as `InstrumentId.admin` and `CHYPE` as `InstrumentId.id`. Do not use the Operator as the instrument administrator. The registrar and registry values below match `bitsafe-token-lib` `v0.5.0`. The library does not define the Utility operator identity. Your registry provider supplies the operator identity when an integration requires it. Confirm the target environment before submitting a command. #### DevNet * **ID:** `CHYPE` * **Provider:** `chype-network::1220806e3c909f4a07c1131f42163fbceb3fbd1bbcbb90e8fe5a266d629ed49d2c52` * **Registrar:** `chype-network::1220806e3c909f4a07c1131f42163fbceb3fbd1bbcbb90e8fe5a266d629ed49d2c52` Registry URL: `https://api.utilities.digitalasset-dev.com` #### TestNet * **ID:** `CHYPE` * **Provider:** `chype-network::12204c05b237be2bfafe7b46f6934858adc1561e9ad1a6996f4d1e1d24612e3b1db0` * **Registrar:** `chype-network::12204c05b237be2bfafe7b46f6934858adc1561e9ad1a6996f4d1e1d24612e3b1db0` Registry URL: `https://api.utilities.digitalasset-staging.com` #### MainNet * **ID:** `CHYPE` * **Provider:** `chype-network::1220cc3b5ad1ada1b7748a17414bf1473e2de0cf9dc7bc820be1cc441b78c0b15956` * **Registrar:** `chype-network::1220cc3b5ad1ada1b7748a17414bf1473e2de0cf9dc7bc820be1cc441b78c0b15956` Registry URL: `https://api.utilities.digitalasset.com` ### Test the integration [Open the BitSafe faucet](https://faucet.bitsafe.finance/?network=devnet\&token=chype). The faucet supports BitSafe assets on DevNet and TestNet. The link opens with DevNet and CHYPE selected. 1. Select the intended network. 2. Confirm that CHYPE is selected. 3. Enter the recipient's Canton party ID. 4. Request test tokens. 5. Accept the faucet transfer as the recipient. 6. Check the recipient's CHYPE balance. The recipient node must have the DA Utility Registry installed. Faucet tokens are not MainNet assets. Test sending and receiving with the [Transfer and receive CHYPE guide](https://docs.bitsafe.finance/chype/guides/transfer-and-receive-chype). Support both pending offers and completed transfers. A completed transfer does not require acceptance. ### DEX and protocol integrations DEXs and protocols use the same CHYPE instrument ID and administrator listed above. The additional work depends on the application's workflow. | Integration | Additional work | | ------------------------- | ------------------------------------------------------------------------ | | Wallet | Display balances and support sending and receiving tokens. | | DEX or trading venue | Connect asset transfers to the venue's trade-settlement workflow. | | Lending or other protocol | Define how the application manages deposits, positions, and withdrawals. | For a trade that exchanges two assets, an ordinary transfer does not link the two legs. Canton Token Standard allocations support delivery-versus-payment settlement: both legs settle together or neither does. Confirm supported APIs and the required settlement permissions before using this workflow. For lending, confirm the price source and collateral, borrowing, and liquidation rules before enabling the asset. Token support alone does not configure those rules. See the [Canton Token Standard documentation](https://docs.dev.sync.global/app_dev/token_standard/index.html) for allocation and application integration details. [Minting information](/chype/guides/mint-chype/) can be found here. ### Technical resources * [`bitsafe-token-lib`](https://github.com/DLC-link/bitsafe-token-lib) * [`canton-lib`](https://github.com/DLC-link/canton-lib) ### Artwork and support Use approved asset artwork from the [BitSafe brand kit](https://bitsafe.finance/brand-kit). Contact BitSafe if the required artwork is unavailable. For additional party fields or configuration questions, [contact BitSafe](https://bitsafe.typeform.com/helloBitSafe). ## Reach out to BitSafe Integrating one of our assets? Reach out to the team on Slack or to sales@bitsafe.finance to coordinate go-lives, marketing, and liquidity. --- # Mint CHYPE URL: https://docs.bitsafe.finance/chype/guides/mint-chype/ [CHYPE overview](/chype/) · [CHYPE environments and prerequisites](/chype/get-started/environments-and-prerequisites/) ### Outcome Create a CHYPE deposit account, select its deposit account ID, deposit HYPE to the HyperEVM bridge, and verify that the corresponding CHYPE becomes available to the intended Canton party. ### Before you start * Complete the CHYPE environment preflight. * Use a supported Canton participant and authenticated party. * [Install and validate the CHYPE DAR packages](/chype/get-started/install-and-validate-dars/) required for minting. * Confirm that the party has the required Minter credential. * Confirm that the BitSafe API of the selected environment is reachable. * Use a pinned `bitsafe-token-lib` release and compatible shared Canton libraries. * Confirm the approved HyperEVM network and the bridge contract address. For Devnet and Testnet, get HyperEVM testnet HYPE from a HyperEVM testnet faucet. * Use a HyperEVM account that can call a contract and that holds HYPE for the deposit and for gas. Minting has additional prerequisites beyond ordinary CHYPE transfers. Do not begin from the Send CHYPE setup alone. ### 1. Confirm the Minter credential Use the credential example or the approved application interface to: 1. Check whether the party already holds the required credential. 2. Find an eligible pending credential offer if none exists. 3. Accept only the intended offer through the approved flow. 4. Record the resulting credential contract identifier securely for the current operation. Do not copy a real credential contract identifier into documentation or support tickets. ### 2. Retrieve current account rules Retrieve the deposit and withdrawal account rules from the BitSafe API of the selected environment: ```http GET /chype/v1/account-contract-rules ``` The response holds `da_rules` for deposit accounts and `wa_rules` for withdrawal accounts. Each rule has a `template_id`, a `contract_id`, and a `created_event_blob`. Verify that: * The response belongs to the selected environment. * The package and template references match the approved DAR set. * The returned rules are current for the intended party and operation. Treat rules as runtime data. Do not hard-code them into a long-lived integration. ### 3. Create a deposit account Create a deposit account using: * The authenticated Canton party. * The approved Minter credential. * The current deposit-account rules. * A unique command or request identifier where the interface supports one. Verify that the resulting account is owned by the intended party before continuing. ### 4. Select the deposit account ID CHYPE doesn't have a separate deposit address for each account. Instead, every deposit goes to the one HyperEVM bridge contract of the environment. The deposit account ID tells the attestors which account to credit. Select the deposit account ID: * If the deposit account has an `id` value, use that value. * Otherwise, use the contract ID of the deposit account. The ID stays the same when a completed deposit recreates the account contract. Use the same ID for every deposit to the account. Do not replace it with the newest contract ID. :::caution A deposit with the wrong deposit account ID does not mint CHYPE, and the HYPE can become stuck in the bridge. Pay extra attention to the ID before sending a deposit. If a finalized deposit does not mint CHYPE, contact support with the transaction hash and the ID. Do not send a second deposit. ::: Before depositing HYPE: * Confirm the HyperEVM network and chain ID. * Confirm the bridge contract address for the selected environment. * Confirm the ID belongs to the expected deposit account. * Record the account and ID association in the integration’s reconciliation data. ### 5. Deposit HYPE Call `depositETH(bytes depositAccountId)` on the bridge contract. Pass the deposit account ID as UTF-8 bytes, and send the approved test amount as the transaction value. Use the transaction hash to monitor HyperEVM finality. :::caution **Encode the deposit account ID as UTF-8 bytes.** The ledger API returns the ID as a hex string. Do not pass that hex string as raw bytes. Pass the UTF-8 bytes of the text. ``` Deposit account ID from the ledger: 00a1b2c3… Wrong depositAccountId: 0x00a1b2c3… Correct depositAccountId: 0x3030613162326333… ``` ::: The amount must be a whole multiple of `100000000` wei (`0.0000000001` HYPE), because CHYPE has 10 decimal places. The bridge rejects any other amount. The bridge also rejects a plain HYPE transfer, so a deposit must call `depositETH`. The amount must also be within the deposit account's own limits. `chype::mint::deposit_call` checks these limits. :::note Check the bridge's current `depositLimits()` and `paused()` state before sending. Check the current environment and compatibility reference for fees, timing, and timeout behavior. Do not rely on historical values. ::: ### 6. Monitor the mint lifecycle Track the deposit account and CHYPE state until the approved completion condition is met. Monitor: * `Deposit` event emitted by the bridge contract. The bridge emits the five-field layout after its upgrade. `bitsafe-token-lib` 0.5.0 decodes only that layout. * HyperEVM block finalized. * Verification or attestation state. * Mint submitted on Canton. * CHYPE holding created for the intended party. * Terminal failure or escalation state. ### 7. Verify the result A successful mint should be verified in two places: 1. The deposit workflow shows the approved completed state. 2. The intended Canton party’s CHYPE balance or holdings increase by the expected amount. Reconcile the HyperEVM transaction, deposit account, mint result, Canton update, and resulting holdings without exposing secrets. ### Source example The repository includes a guided example: ```bash cargo run --example chype_credentials cargo run --example chype_mint_flow ``` The example reads `DEPOSIT_AMOUNT_WEI`, which defaults to `250000000000000000` wei (0.25 HYPE). The deposit account limits still apply. The `chype_mint_flow` example does not send HYPE. It prints the `depositETH` transaction, which you sign and send with your own HyperEVM wallet. Use these commands only with the reviewed source tag and an approved environment. Link to the source for exhaustive implementation details rather than duplicating the full code. ### Troubleshooting | Symptom | Check | Safe next action | | ----------------------------------- | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | | No eligible credential | Party, environment, registrar, and pending offers | Stop and use the approved credential-request path. | | Account rules unavailable | BitSafe API, authentication, environment, and service status | Do not reuse cached rules unless the support policy permits it. | | Deposit account creation fails | DAR compatibility, credential, party rights, rule identifiers, and Canton response | Capture sanitized identifiers and the version set. | | Deposit transaction fails | Bridge pause state, deposit limits, amount unit, and `depositETH` call data | Correct the input before another attempt. | | HYPE deposit is not detected | Chain ID, bridge contract address, deposit account ID, transaction hash, finality state, and event topic0 | Do not send a second deposit until the first transaction is reconciled. | | Deposit is final but CHYPE is absent | Deposit account ID, verification state, mint status, Canton update, and target party | Escalate with sanitized account, transaction, and update identifiers. | Read topic0 from the deposit transaction's receipt at the proxy address before choosing a filter or decoder. The [SDK event reference](/chype/concepts-and-reference/sdk-api-and-integration-reference/#deposit-event-layout) explains topics and historical log decoding. ### Technical sources * [Mint flow example](https://github.com/DLC-link/bitsafe-token-lib/blob/v0.5.0/examples/chype/mint_flow.rs) * [Credential example](https://github.com/DLC-link/bitsafe-token-lib/blob/v0.5.0/examples/chype/credentials.rs) * [Examples guide](https://github.com/DLC-link/bitsafe-token-lib/blob/v0.5.0/examples/README.md) * [CHYPE DAR guidance](https://github.com/DLC-link/bitsafe-token-lib/tree/v0.5.0/dars) * [HyperEVM bridge contract](https://github.com/DLC-link/evm-asset-bridge) ### Related pages * [Install and validate CHYPE DARs](/chype/get-started/install-and-validate-dars/) * [CHYPE authentication](/chype/get-started/authentication/) * [CHYPE errors, retries, and troubleshooting](/chype/concepts-and-reference/errors-retries-and-troubleshooting/) * [CHYPE compatibility and release notes](/chype/concepts-and-reference/compatibility-and-release-notes/) ### Next step → **Prepare for failures safely:** [CHYPE errors, retries, and troubleshooting](/chype/concepts-and-reference/errors-retries-and-troubleshooting/). --- # Redeem CHYPE URL: https://docs.bitsafe.finance/chype/guides/redeem-chype/ [CHYPE overview](/chype/) · [CHYPE environments and prerequisites](/chype/get-started/environments-and-prerequisites/) ### Outcome Create or select a withdrawal account, redeem CHYPE, and verify delivery of HYPE to the intended HyperEVM address. ### Before you start * Complete the CHYPE environment preflight. * Confirm the party holds enough CHYPE for the intended test. * [Install and validate the DAR packages](/chype/get-started/install-and-validate-dars/) required for redemption. * Confirm the required Minter credential. * Configure the approved BitSafe API. * Obtain a valid HyperEVM destination address for the selected network. The address must accept native HYPE. * Understand the approved minimums, limits, fees, and recovery path. ### 1. Validate the HyperEVM destination Before creating a withdrawal account: * Confirm the destination address format and HyperEVM network. * Confirm that the address can receive native HYPE. A contract address that rejects HYPE makes the redemption fail. * Confirm ownership or authorization under the organization’s controls. * Use a second-person or system control for production destinations where required. The account owner can change the destination address after account creation. A change does not affect a redemption that is already in progress. A wrong-network or wrong-recipient destination may be irreversible. ### 2. Retrieve current withdrawal rules Retrieve the current account rules from the BitSafe API of the selected environment: ```http GET /chype/v1/account-contract-rules ``` Use the `wa_rules` entry for withdrawal accounts. Confirm that the response matches the selected environment, current DAR set, and intended operation. ### 3. Create or select a withdrawal account Create a withdrawal account using the authenticated party, approved credential, current rules, and verified HyperEVM destination. If reusing an existing account, confirm its destination and current status before selecting it. A withdrawal account allows one withdrawal at a time. A second redemption from the same account fails until the first one is processed. Created deposit and withdrawal accounts stay on the ledger until someone closes them. Do not create duplicate accounts as an automatic retry strategy. CHYPE rejects the zero address, HyperEVM system addresses, and CHYPE bridge proxies as withdrawal destinations. The library checks the destination during account creation and again before burning holdings. A burn cannot be undone. ### 4. Select CHYPE holdings Query current CHYPE holdings and select sufficient inputs to cover the requested redemption according to the approved holding-selection policy. Before submission: * Confirm the total selected amount. * Confirm the requested withdrawal amount. * Check applicable limits. * Preserve enough information for reconciliation. * Avoid using holdings involved in another pending operation. ### 5. Submit the withdrawal Submit the redemption through the supported CHYPE interface. Use a unique request or command identifier where available and retain the resulting Canton update or contract identifiers securely. :::note Do not retry blindly after a timeout. First determine whether the original command committed, failed, or remains pending. ::: ### 6. Monitor the lifecycle Monitor the authoritative states for: * Withdrawal submitted. * CHYPE burned or otherwise consumed by the approved contract flow. * Withdrawal account pending balance updated. * HyperEVM redemption transaction submitted. * HyperEVM block finalized. * Completed, failed, cancelled, or escalated. ### 7. Verify and reconcile A successful redemption should show: 1. The intended CHYPE amount no longer appears in the party’s available holdings. 2. The withdrawal account reflects the approved state transition. 3. HYPE is delivered to the verified destination. 4. The Canton and HyperEVM records reconcile to one redemption request. The HYPE arrives as an internal transfer from the bridge contract. The outer HyperEVM transaction shows zero HYPE value. Check the bridge `Withdraw` event or the internal transfers of the transaction. ### Source example The example requires `DESTINATION_HYPE_ADDRESS`. It reads `WITHDRAW_AMOUNT`, which defaults to `0.25` CHYPE. ```bash cargo run --example chype_credentials cargo run --example chype_redeem_flow ``` ### Troubleshooting | Symptom | Check | Safe next action | | ------------------------------------- | -------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | | Destination rejected | Network, format, rule set, and account state | Stop; do not substitute an address without repeating validation. | | Insufficient selectable holdings | Available balance, pending operations, UTXO layout, and limits | Reconcile holdings before consolidating or splitting. | | Second redemption fails | Whether the account has a redemption in progress | Wait until the first redemption is processed. | | Submission times out | Canton update status and withdrawal-account state | Determine commitment before retrying. | | CHYPE decreases but HYPE is pending | Withdrawal state, bridge pause state and limits, HyperEVM finality, and service health | Follow the approved pending-withdrawal escalation path. | | HYPE arrives with an unexpected amount | Requested amount, approved fees, bridge `Withdraw` event, and reconciliation record | Escalate; do not make an offsetting transaction automatically. | | Destination does not accept HYPE | Whether the destination is a contract that rejects HYPE | Escalate with sanitized account, transaction, and update identifiers. | ### Technical sources * [Redeem flow example](https://github.com/DLC-link/bitsafe-token-lib/blob/v0.5.0/examples/chype/redeem_flow.rs) * [Examples guide](https://github.com/DLC-link/bitsafe-token-lib/blob/v0.5.0/examples/README.md) * [HyperEVM bridge contract](https://github.com/DLC-link/evm-asset-bridge) ### Related pages * [Install and validate CHYPE DARs](/chype/get-started/install-and-validate-dars/) * [CHYPE authentication](/chype/get-started/authentication/) * [CHYPE batch transfers and UTXO management](/chype/guides/batch-transfers-and-management/) * [CHYPE errors, retries, and troubleshooting](/chype/concepts-and-reference/errors-retries-and-troubleshooting/) * [CHYPE compatibility and release notes](/chype/concepts-and-reference/compatibility-and-release-notes/) ### Next step → **Prepare for failures safely:** [CHYPE errors, retries, and troubleshooting](/chype/concepts-and-reference/errors-retries-and-troubleshooting/). --- # Transfer and receive CHYPE URL: https://docs.bitsafe.finance/chype/guides/transfer-and-receive-chype/ [CHYPE overview](/chype/) · [CHYPE environments and prerequisites](/chype/get-started/environments-and-prerequisites/) · [Transfer and receive CHYPE](/chype/guides/transfer-and-receive-chype/) ### Outcome Send CHYPE from one Canton party to another, read the result of the transfer, and accept, reject, or cancel a transfer offer. ### Before you start * Use an Engineering-approved `bitsafe-token-lib`, `canton-lib`, DAR, and Canton compatibility row. This guide describes `bitsafe-token-lib` `v0.5.0`. * Confirm authentication, the sender party, the receiver party, and the registry URL for the intended environment. * Confirm the CHYPE instrument identifier. The identifier is the instrument ID `CHYPE` and the administrator party. The library matches both values exactly. * Query the sender's holdings, and confirm that the sender has enough available CHYPE. ### How a transfer settles A transfer has one of two outcomes: * **Offer:** the registry creates a transfer instruction. The receiver accepts or rejects it, or it expires at `execute_before`. The sender can cancel it before the receiver acts. * **Settled on submission:** the registry moves the CHYPE at once, and no offer exists. The registry does this for a self-transfer and for a receiver that pre-approved the sender. The library tells you which outcome occurred. Do not assume that the receiver must accept. ### 1. Send CHYPE Call `bitsafe_token::transfer::submit` as the sender. The call returns a `TransferReceipt`. ```rust let receipt = bitsafe_token::transfer::submit(bitsafe_token::transfer::Params { transfer: bitsafe_token::Transfer { sender: sender_party.clone(), receiver: receiver_party.clone(), amount: bitsafe_token::DamlDecimal::parse("0.01")?, instrument_id: bitsafe_token::InstrumentId { admin: decentralized_party_id.clone(), id: bitsafe_token::tokens::chype::TICKER.to_string(), }, requested_at: chrono::Utc::now().to_rfc3339(), execute_before: (chrono::Utc::now() + chrono::Duration::hours(168)).to_rfc3339(), input_holding_cids: None, // None lets the library select the sender's holdings meta: None, }, ledger_host: ledger_host.clone(), access_token: sender_token.clone(), registry_url: registry_url.clone(), decentralized_party_id: decentralized_party_id.clone(), }).await?; ``` Run the repository example with `ASSET=chype cargo run --example send`. ### 2. Read the transfer receipt The receipt contains three fields: | Field | Meaning | | -------------------- | ------------------------------------------------------------------------------------------------ | | `outcome` | `TransferOutcome::Pending` for an offer, or `TransferOutcome::Completed` for a settled transfer. | | `sender_change_cids` | The sender holdings that remain after the transfer. | | `update_id` | The Canton update identifier of the transaction. | `receipt.outcome.transfer_offer_cid()` returns the offer contract ID for a pending transfer. It returns `None` for a settled transfer. Record the offer ID, because the receiver and the sender need it in the next steps. ### 3. Receive CHYPE Skip this step when the outcome is `Completed`. The receiver already holds the CHYPE. For a pending transfer, the receiver authenticates as the receiver party and does one of these actions: * **Accept one offer:** call `bitsafe_token::accept::submit` with the offer contract ID and the receiver party. * **Accept all offers:** call `bitsafe_token::accept::accept_all`. It returns one result for each offer and the successful and failed counts. Read `failed_count` before you treat the step as done. * **Reject an offer:** call `bitsafe_token::reject::submit` with the offer contract ID and the receiver party. The CHYPE returns to the sender. To list the receiver's pending offers, run `ASSET=chype cargo run --example list_incoming_offers`. ### 4. Cancel an outgoing offer The sender can withdraw an offer that the receiver has not accepted or rejected: * `bitsafe_token::cancel_offers::submit` withdraws one offer. * `bitsafe_token::cancel_offers::withdraw_batch` withdraws a list of offers. * `bitsafe_token::cancel_offers::withdraw_all` withdraws all pending offers of the instrument. To list the sender's pending offers, run `ASSET=chype cargo run --example list_outgoing_offers`. To withdraw them, run `ASSET=chype cargo run --example cancel_offers`. ### Token Standard V2 Each operation in this guide also has a Token Standard V2 form in a `v2` submodule, such as `bitsafe_token::transfer::v2::submit`. The V2 transfer takes the sender and the receiver as `bitsafe_token::Account` values instead of party strings. The accept, reject, and cancel V2 forms take the same parameters as V1. Run the V2 transfer example with `ASSET=chype cargo run --example send_v2`. ### Expected result * The sender has a `TransferReceipt` and a recorded outcome for each transfer. * For a settled transfer, the receiver holds the CHYPE. * For an offer, the receiver accepted or rejected it, the sender cancelled it, or it expired. ### Troubleshooting | Symptom | Check | | ------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | | The receiver sees no offer. | Read the sender's receipt. A `Completed` outcome creates no offer, and the receiver already holds the CHYPE. | | The receiver's balance does not change. | Confirm the instrument ID and the administrator. The library ignores holdings of another administrator. | | Accept or reject fails. | Confirm that the token authenticates the receiver party and that the offer is still active. | | The transfer fails with insufficient funds. | Query the sender's holdings. Holdings locked in another offer are not available. | ### Technical sources * [`bitsafe-token-lib` README at `v0.5.0`](https://github.com/DLC-link/bitsafe-token-lib/blob/v0.5.0/README.md) * [Transfer implementation and receipt model](https://github.com/DLC-link/canton-lib/blob/v0.12.0/crates/token/src/transfer.rs) * [Accept implementation](https://github.com/DLC-link/canton-lib/blob/v0.12.0/crates/token/src/accept.rs) * [Reject implementation](https://github.com/DLC-link/canton-lib/blob/v0.12.0/crates/token/src/reject.rs) * [Cancel implementation](https://github.com/DLC-link/canton-lib/blob/v0.12.0/crates/token/src/cancel_offers.rs) * [Send example](https://github.com/DLC-link/bitsafe-token-lib/blob/v0.5.0/examples/send.rs) * [Reject example](https://github.com/DLC-link/bitsafe-token-lib/blob/v0.5.0/examples/reject_transfer.rs) ### Related pages * [Batch transfers and UTXO management](/chype/guides/batch-transfers-and-management/) * [Token standard and contract model](/chype/concepts-and-reference/token-standard-and-contract-model/) ### Next step → **Send to many receivers:** [Batch transfers and UTXO management](/chype/guides/batch-transfers-and-management/). --- # Batch transfers and management URL: https://docs.bitsafe.finance/chype/guides/batch-transfers-and-management/ [CHYPE overview](/chype/) · [CHYPE environments and prerequisites](/chype/get-started/environments-and-prerequisites/) · [Transfer and receive CHYPE](/chype/guides/transfer-and-receive-chype/) ### Outcome Distribute CHYPE to multiple Canton parties, record one result for each sender-side transfer, and manage CHYPE holdings without creating an unsafe retry or consolidation workflow. ### Terminology This guide uses **UTXO** as shorthand used by the current library for an active CHYPE holding contract. A CHYPE holding is a contract on Canton Network. HyperEVM has no UTXOs. ### Before you start * Complete one sender-to-receiver transfer and receiver acceptance in the intended environment. * Use an Engineering-approved `bitsafe-token-lib`, `canton-lib`, DAR, and Canton compatibility row. * Confirm authentication, the sender party, the CHYPE instrument identifier, the registry service, and the intended environment. * Query the sender’s current holdings and outgoing offers. * Confirm the sender has enough available CHYPE for the full distribution. * Define a durable application-side row identifier and reconciliation record for every recipient. * Stop other processes from spending or restructuring the same sender’s holdings during the run. :::note A batch is not one atomic transfer. In `v0.5.0`, the library submits sender-side transfers sequentially. Each successful submission either creates a transfer offer that the receiver must accept, or settles the transfer on submission. The registry settles a self transfer, and a transfer to a receiver that pre-approved the sender. ::: ### Choose the batch interface | Interface | Use | Result handling | | ----------------------------------------- | --------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `bitsafe_token::batch::submit_from_csv()` | Read `receiver,amount` rows from a CSV file and submit a sequential distribution. | Returns successful and failed counts plus one result per row. `Ok` means that the batch ran, not that every row succeeded. Read `failed_count` before you treat the batch as done. It does not accept a callback. | | `bitsafe_token::distribute::submit()` | Submit an in-memory recipient list. | Returns successful and failed counts plus one result per row. It can call an asynchronous callback after each row completes. | For production-style reconciliation, prefer `bitsafe_token::distribute::submit()`, because only that interface accepts a durable callback. Each interface also has a Token Standard V2 form: `bitsafe_token::batch::v2::submit_from_csv()` and `bitsafe_token::distribute::v2::submit()`. The V2 forms take the sender as a `bitsafe_token::Account` instead of a party string. ### How the current sequential flow works At `v0.5.0`, the distribution flow: 1. Authenticates and refreshes the access token when required. 2. Queries all active sender holdings once at the start. 3. Uses those holding contract identifiers as the first transfer’s inputs. 4. Fetches transfer-factory context once and reuses it for the run. 5. Submits one transfer at a time. 6. Uses the sender change holdings returned by a successful row as the next row’s inputs. When a self transfer settles on submission, the new sender holdings also join those inputs. 7. Records success or failure for each row and then attempts the next row. This is a sequential chained flow. It is not concurrent, and it does not pre-split holdings. ### 1. Prepare and validate recipient input The repository example accepts this CSV shape: ``` receiver,amount receiver1-party::1220...,5.0 receiver2-party::1220...,3.5 ``` Before passing data to the library: * Reject empty receiver identifiers. * Validate every receiver against the intended environment. * Parse every amount as the supported decimal type. * Reject zero, negative, or amounts outside the documented policy limits. * Reject duplicate application-side row identifiers. * Review repeated receiver identifiers intentionally. Do not assume one receiver appears only once. * Sum all amounts and compare the total with the sender’s available balance. The CSV helper rejects malformed amounts and an empty recipient list. The reviewed source does not implement business-reference deduplication or complete recipient-policy validation. Perform those checks in the calling application. ### 2. Create a run record Create a durable run record before submission. Store: * Application run identifier. * Application row identifier. * Row index. * Receiver. * Amount. * Intended environment. * Submission state. * Transfer-offer contract identifier when available. * Canton update identifier when available. * Library reference when available. * Error and raw-response location, with secrets removed. #### Reference limitation in `v0.5.0` The optional `reference_base` generates a reference from the base value, sender, and receiver. It does not include the row index or amount. Repeated rows for the same receiver can therefore produce the same generated reference. Do not treat this generated value as a guaranteed per-row idempotency key. Keep a separate application-side row identifier and reconcile state before replay. ### 3. Check holdings and pending work Immediately before submission: 1. Query active CHYPE holdings for the sender. 2. Record the holding contract identifiers and total available amount. 3. Query pending outgoing offers and unresolved withdrawals. 4. Confirm no other batch, split, consolidation, redemption, or transfer process can consume the same holdings. 5. Apply the holding-count and transaction-size limits documented for the supported release. The batch implementation fetches holdings once. Concurrent mutations can make its chained input set stale. ### 4. Run a batch The simple repository example uses: ```bash ASSET=chype RECIPIENTS_CSV=recipients.csv cargo run --example batch_distribute ``` The callback example uses: ```bash ASSET=chype RECIPIENTS_CSV=recipients.csv cargo run --example batch_with_callback ``` Use placeholders for credentials and environment values. Never commit `.env` files, access tokens, passwords, or production party identifiers. ### 5. Record each callback result The callback receives one result after each sender-side submission attempt. | Field | Use | | -------------------- | ------------------------------------------------------------------------------------------------------------ | | `success` | Whether the library classified the sender-side submission and response parsing as successful. | | `transfer_index` | Zero-based position in the submitted recipient list. | | `receiver`, `amount` | Match the result to the intended row. Also verify the application-side row identifier. | | `transfer_offer_cid` | Track the created transfer instruction or offer. The value is empty when the transfer settled on submission. | | `update_id` | Correlate the result with the Canton update. | | `reference` | Store as supporting metadata. Do not assume uniqueness under the limitation above. | | `raw_response` | Retain securely for diagnostics when policy permits. Remove secrets before support escalation. | | `error` | Classify the row as failed or ambiguous and apply the approved recovery procedure. | Make the callback durable and safe to call once per completed attempt. If writing to a database, protect the application row from duplicate callback processing. ### 6. Reconcile the run Classify each row separately: * **Submitted:** The callback includes a transfer-offer contract identifier and Canton update identifier. This confirms sender-side submission, not receiver acceptance. * **Settled on submission:** The callback includes a Canton update identifier and no transfer-offer contract identifier. The receiver already holds the amount, and no acceptance step follows. * **Accepted:** The receiver accepted the intended offer, and both parties’ holdings reflect the completed transfer. * **Failed before submission:** Evidence proves that no ledger update committed. * **Ambiguous:** The request may have committed, but the client lacks a parseable or authoritative result. * **Rejected, cancelled, or expired:** The offer reached the corresponding terminal state. Use the versioned reference for exact state names and expiry policy. After the sender-side run, verify incoming offers with each receiver or the approved receiving service. Do not mark a distribution complete from `successful_count` alone. ### Partial failure and safe resume The reviewed implementation continues to later rows after a failed submission or response-parsing error. It preserves the last known input-holding list in memory. For production recovery: 1. Stop the run when an outcome is ambiguous. 2. Requery active holdings and outgoing offers from authoritative sources. 3. Match receiver, amount, application row identifier, offer identifier, update identifier, and available reference metadata. 4. Mark already-created offers as submitted. Do not create replacements for them. 5. Resume only rows proven not to have committed. 6. Build a new run from fresh holdings. Do not reuse a stale in-memory holding list. 7. Keep accepted, pending, failed, and ambiguous rows in separate states. Never rerun the complete CSV after partial success. ### Concurrency policy `bitsafe-token-lib` `v0.5.0` processes one distribution sequentially. Do not run parallel distributions, transfers, redemptions, splits, or consolidations from the same sender without an application-level lock and fresh-state strategy. Use the supported release limits for recipient count, total amount, execution duration, timeouts, and rate limits. ### Manage CHYPE holdings #### Inspect holdings Use the active-contract query or the consolidation count helper to record: * Holding count. * Holding contract identifiers. * Total amount. * Pending operations that reference those holdings. * Last successful reconciliation time. A high holding count can increase transaction size and operational complexity. Use the current operational limits when deciding whether to consolidate. #### Consolidate holdings The `v0.5.0` consolidation function performs a self-transfer with merge-split metadata. It can consolidate all active holdings or a selected set. If the party has fewer holdings than the supplied threshold, `check_and_consolidate()` does nothing. If the threshold is met or exceeded, it consolidates all queried holdings and returns the resulting holding contract identifiers. The repository example uses a configurable threshold and defaults that example to `10`. Treat this as example behavior, not a production limit. Use the threshold documented for the target environment. Run the example only after review: ```bash ASSET=chype CONSOLIDATION_THRESHOLD= cargo run --example consolidate_utxos ``` Before consolidation: * Reconcile pending transfers and withdrawals. * Confirm the selected holdings are still active. * Stop concurrent operations for the party. * Estimate the expected resulting holding count and transaction impact. * Record the input holding identifiers. After consolidation, query the party again and verify the total amount and returned holding identifiers. #### Split holdings The `v0.5.0` split function uses sequential self-transfers. It separates each requested amount in order, then feeds the returned change holdings into the next split. It returns output holding identifiers and remaining change identifiers. If a step fails, the function returns a `split::Error`. Its `partial` field lists the holdings that the earlier steps created. Use split only when an approved downstream workflow requires specific holding sizes. Confirm: * The requested amounts and order. * The selected input holdings. * The expected remaining change. * Behavior when requested amounts consume the exact available total. * The release-specific recovery procedure if a later split step fails. Do not split solely to prepare the sequential batch flow. The current batch implementation is designed to chain change holdings without pre-splitting. ### Expected result A completed operation has: * One durable record per recipient. * A reconciled sender-side result for every row. * Receiver acceptance or another approved terminal state for every created offer. * No ambiguous row left queued for automatic retry. * A final sender balance and holding set that match the reconciled run. * A recorded before-and-after holding set for every split or consolidation. ### Troubleshooting
SymptomCheckSafe next action
No recipients foundCSV path, header, and parsed row countCorrect the file. Do not submit an unreviewed replacement.
Invalid amountDecimal syntax and business amount rulesReject the row before any submission.
No holdings availableSender party, environment, active holdings, and pending operationsStop and reconcile the sender. Do not retry with another party implicitly.
Some rows succeed and later rows failPer-item results, current holdings, token refresh, and errorsDo not rerun the complete CSV. Requery authoritative state and resume only proven-uncommitted rows.
Ledger response exists but parsing failsRaw response, update visibility, outgoing offers, and client compatibilityTreat the row as ambiguous. Reconcile before any retry.
Sender-side success but receiver balance is unchangedIncoming offer, receiver acceptance, preapproval policy, rejection, cancellation, and expiryComplete or resolve the receiver-side flow. Do not duplicate the sender submission.
Generated references repeatRepeated receiver identifiers and shared reference_baseUse application-side row identifiers. Escalate before relying on the library reference for replay protection.
Consolidation returns an unexpected holding setInput holdings, concurrent operations, transaction response, and final active holdingsStop new operations and reconcile total amount and contract identifiers.
Split stops after creating earlier outputsCompleted split steps, current change holdings, and remaining requested amountsRequery holdings. Do not restart from the original input identifiers.
### Technical sources * [`bitsafe-token-lib` README at `v0.5.0`](https://github.com/DLC-link/bitsafe-token-lib/blob/v0.5.0/README.md) * [CSV batch helper](https://github.com/DLC-link/canton-lib/blob/v0.12.0/crates/token/src/batch.rs) * [Sequential distribution flow](https://github.com/DLC-link/canton-lib/blob/v0.12.0/crates/token/src/distribute.rs) * [Sequential chained transfer and result model](https://github.com/DLC-link/canton-lib/blob/v0.12.0/crates/token/src/transfer.rs) * [Batch CSV example](https://github.com/DLC-link/bitsafe-token-lib/blob/v0.5.0/examples/batch_distribute.rs) * [Callback example](https://github.com/DLC-link/bitsafe-token-lib/blob/v0.5.0/examples/batch_with_callback.rs) * [Consolidation implementation](https://github.com/DLC-link/canton-lib/blob/v0.12.0/crates/token/src/consolidate.rs) * [Consolidation example](https://github.com/DLC-link/bitsafe-token-lib/blob/v0.5.0/examples/consolidate_utxos.rs) * [Split implementation](https://github.com/DLC-link/canton-lib/blob/v0.12.0/crates/token/src/split.rs) ### Related pages * [Transfer and receive CHYPE](/chype/guides/transfer-and-receive-chype/) * [CHYPE authentication](/chype/get-started/authentication/) * [CHYPE errors, retries, and troubleshooting](/chype/concepts-and-reference/errors-retries-and-troubleshooting/) * [CHYPE compatibility and release notes](/chype/concepts-and-reference/compatibility-and-release-notes/) * [CHYPE SDK, API, and integration reference](/chype/concepts-and-reference/sdk-api-and-integration-reference/) ### Next step → **Plan safe recovery:** [CHYPE errors, retries, and troubleshooting](/chype/concepts-and-reference/errors-retries-and-troubleshooting/). --- # Architecture and trust boundaries URL: https://docs.bitsafe.finance/chype/concepts-and-reference/architecture-and-trust-boundaries/ [How CHYPE works](/chype/how-chype-works/) ### Architecture at a glance CHYPE connects HYPE custody in the HyperEVM bridge contract and event verification with private Canton contract workflows. This page owns the component map and trust boundaries. Lifecycle steps belong in [How CHYPE works](/chype/how-chype-works/); control requirements belong in [CHYPE security](/chype/concepts-and-reference/security/). ### Component map
ComponentResponsibilityPrimary boundary
HyperEVM bridge contractReceive eligible deposits and release approved redemptionsContract logic, signature threshold, limits, upgrade governance, and HyperEVM finality
Attestor NetworkVerify eligible events and participate in threshold authorizationIndependent operation, policy, and signing keys
CHYPE workflow servicesAssociate accounts and events, coordinate workflows, and reconcile stateAuthentication, availability, and correct state handling
Canton participants and partiesHost parties, contracts, and authorized commandsCanton identity, rights, topology, and privacy
CHYPE Daml packagesDefine holdings, transfers, accounts, credentials, and administrative behaviorApproved package versions and contract authorization
Client libraries and applicationsExpose supported workflows and submit authorized requestsPinned releases, credentials, validation, and retries
Proof of Reserve and reconciliationProvide scoped evidence about reserves and system stateCompleteness, freshness, source integrity, and stated limitations
### Trust boundaries #### HYPE custody The HyperEVM bridge contract holds the underlying HYPE. The contract releases HYPE only when it verifies signatures from a threshold of independent Attestor Network operators. Each operator signs with its own HyperEVM key. The threshold is configurable, and the operator set can change. Safe multisig wallets hold the admin roles of the bridge contract. These roles can change the attestor set and the signature threshold, upgrade the contract through a timelock, set deposit and withdrawal limits, and pause the bridge. #### Attestor Network Event verification and signing authorization are separate responsibilities. No single operator should be presented as sufficient to authorize a custody action. The detailed signing model belongs in [CHYPE Attestor Network](/chype/concepts-and-reference/attestor-network-and-hyperevm-signing/). #### Canton Canton records CHYPE contract state and applies authorization through parties, participant rights, package logic, and topology. Configurable sub-transaction privacy limits contract visibility to entitled parties; it does not hide HyperEVM transactions. #### Integration services Clients authenticate separately to Canton and approved CHYPE services. They must validate networks, parties, addresses, package compatibility, and authoritative state before retrying an ambiguous request. #### Evidence Proof of Reserve demonstrates only the evidence and observation scope documented on [CHYPE Proof of Reserve](/chype/concepts-and-reference/proof-of-reserve/). It does not prove every application, custody, operational, or redemption property. ### Architecture limits This architecture does not by itself guarantee instant HyperEVM confirmation, every external service’s availability, correct integrator configuration, protection from an authorized request containing the wrong destination, or complete coverage by one evidence source. ### Technical sources * [BitSafe token library](https://github.com/DLC-link/bitsafe-token-lib) * [Shared Canton library](https://github.com/DLC-link/canton-lib) * [HyperEVM bridge](https://github.com/DLC-link/evm-asset-bridge) ### Related pages * [CHYPE token standard and contract model](/chype/concepts-and-reference/token-standard-and-contract-model/) * [CHYPE Attestor Network](/chype/concepts-and-reference/attestor-network-and-hyperevm-signing/) * [CHYPE Proof of Reserve](/chype/concepts-and-reference/proof-of-reserve/) * [CHYPE security](/chype/concepts-and-reference/security/) ### Next step → **Review the control model:** [CHYPE security](/chype/concepts-and-reference/security/). --- # Token standard and contract model URL: https://docs.bitsafe.finance/chype/concepts-and-reference/token-standard-and-contract-model/ ### Purpose Use this page to understand how CHYPE represents tokens and workflows on Canton Network, which contracts participate in transfers and HyperEVM bridge operations, and where integration responsibilities sit. This page explains the model. For implementation steps, use the dedicated mint, redeem, transfer, authentication, and SDK guides. ### Current token-standard boundary The reviewed `bitsafe-token-lib` `v0.5.0` release interacts with the Canton Token Standard V1 interfaces (CIP-0056) and V2 interfaces (CIP-0112). Eight operations have a V2 form in a `v2` submodule, such as `bitsafe_token::transfer::v2::submit`. The library uses token-standard holdings and transfer instructions for ordinary CHYPE movement, while CHYPE-specific account contracts coordinate mint and redemption workflows. The observed instrument identifier has two parts: * **Administrator:** the CHYPE registrar party for the selected environment. * **Instrument name:** `CHYPE`. Do not hard-code a registrar party, package ID, contract ID, or environment endpoint from an example. These values differ by environment and can change with upgrades. Use the discovery flow and token-standard naming documented for the supported release. :::note **Version boundary:** `bitsafe-token-lib` `v0.5.0` has Token Standard V2 (CIP-0112) entry points for eight operations. Allocation remains V1-only in this release. Confirm that the target registry supports the selected version before submitting a command. Use the compatibility reference for current token-standard support and migration guidance. ::: ### Contract model at a glance | Layer | Primary contracts or interfaces | Responsibility | | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | Token-standard layer | `Holding`, `TransferFactory`, `TransferInstruction`, `InstrumentConfiguration`, `Credential` (Minter role), `BurnMintFactory` | Represents CHYPE holdings, creates and resolves transfer instructions, identifies the instrument, and supplies governed mint or burn primitives. | | CHYPE bridge layer | `CHYPEDepositAccountRules`, `CHYPEDepositAccount`, `CHYPEWithdrawAccountRules`, `CHYPEWithdrawAccount`, `CHYPEWithdrawRequest` | Coordinates deposit account IDs, withdrawal destinations, pending redemption balances, and the asynchronous handoff between Canton and HyperEVM workflows. | | Registry and service layer | Registry choice contexts, disclosed contracts, CHYPE account-rule responses and token-standard contract responses | Returns the contracts and context an authenticated client needs to exercise the intended ledger choice. | ### Holdings A CHYPE balance is represented by one or more active holding contracts rather than one mutable balance field. Integrations therefore need to: 1. Query active holdings for the authenticated party. 2. Confirm that each selected holding belongs to the intended CHYPE instrument. 3. Exclude holdings already locked or consumed by another workflow. 4. Select enough inputs for the operation. 5. Reconcile output and change holdings after submission. This contract-based model is why transfer, split, consolidation, mint, and redemption flows return or create new contract identifiers. Applications should treat those identifiers as operation state, not as permanent account numbers. ### Transfer contracts The reviewed V1 flow is instruction based: 1. The sender selects active CHYPE holdings. 2. The client requests a transfer choice context from the registry. 3. The client exercises `TransferFactory_Transfer` with the sender, receiver, amount, instrument identifier, selected holdings, execution window, and supplied context. 4. The ledger returns sender change holdings and one of two results. The registry creates a transfer-instruction contract, or it settles the transfer and creates the receiver’s holdings. 5. The receiver resolves an instruction through the supported acceptance flow. A settled transfer has no instruction to resolve. 6. Both parties reconcile active holdings and the transaction update identifier. A submitted transfer and a completed receipt are not necessarily the same event. User interfaces should distinguish an outgoing instruction from a holding that the receiver has accepted. Check the supported release for expiry, rejection, cancellation, preapproval, and safe retry behavior. ### Mint contracts Minting uses CHYPE-specific deposit-account contracts around the token-standard mint primitive. 1. The client obtains the current deposit-account rules from the BitSafe API. 2. The authenticated party exercises `CHYPEDepositAccountRules_CreateDepositAccount` with the intended owner and required credentials. 3. The ledger creates a `CHYPEDepositAccount` contract. 4. The client passes the deposit account ID to `depositETH` on the HyperEVM bridge contract. 5. HyperEVM deposit verification occurs outside `bitsafe-token-lib`. 6. After the approved verification and governance flow completes, token-standard holdings become available to the intended Canton party. The reviewed library creates the deposit account, queries its status, and builds the `depositETH` call. It does not send or monitor HyperEVM transactions itself. Use the current operational reference for required credentials, HyperEVM finality, completion states, timing, and recovery behavior. :::caution Use the `id` of the `CHYPEDepositAccount` as the `depositAccountId` parameter of the `depositETH` call. Use the contract ID only if the account has no `id` yet. A deposit with the wrong `depositAccountId` does not mint CHYPE, and the HYPE can become stuck in the bridge. ::: ### Redemption contracts Redemption uses a withdrawal account and an asynchronous withdrawal request. 1. The client obtains the current withdrawal-account rules. 2. The authenticated party exercises `CHYPEWithdrawAccountRules_CreateWithdrawAccount` with the intended owner, HyperEVM destination address, and required credentials. 3. The ledger creates a `CHYPEWithdrawAccount` contract. 4. The client selects eligible CHYPE holdings and exercises `CHYPEWithdrawAccount_Withdraw` with the owner's Minter credential. 5. The withdrawal choice checks the owner's Minter credential and the selected holdings. It then exercises `BurnMintFactory_BurnMint`, which burns the selected holdings and returns any change to the owner. 6. The updated withdrawal account records a pending balance. 7. The Attestor Network later creates a `CHYPEWithdrawRequest` and processes the HyperEVM redemption. The withdrawal request is not created atomically with the initial ledger submission. Integrations must monitor the asynchronous request and verify HyperEVM delivery before treating the workflow as complete. Use the current operational reference for credentials, address rules, minimums, fees, request states, polling, retries, and completion timing. ### Disclosed contracts and choice context Canton choices can require contracts that are not directly visible to the submitting party. The registry and BitSafe API return those contracts with the created-event data needed for disclosure. The client submits them alongside the exercise command. Redemption also uses a namespaced `ExtraArgs` context. The library supplies the instrument configuration contract and a withdrawal reason. The issuer-credentials list is empty, because CHYPE needs no issuer credential. Integrators should obtain this context from the supported source rather than reconstructing identifiers from copied examples. ### Package references and upgrades The reviewed client uses package-name template references for CHYPE account choices rather than pinning the concrete package ID that created an older contract. This allows Canton to resolve a commonly vetted package version during smart-contract upgrades. That behavior does not remove the need for compatibility checks. Before production use, validate the supported combination of: * Canton environment and participant release. * CHYPE DAR packages. * Digital Asset Registry Utility packages. * `bitsafe-token-lib` and shared `canton-lib` releases. * BitSafe API and authentication configuration. Use the maintained compatibility matrix as the source for supported component combinations. ### Responsibility boundaries | Component | Owns | Does not by itself prove | | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | | Canton participant and ledger | Contract state, authorization, transaction submission, and participant-visible events | HyperEVM deposit or redemption completion | | Digital Asset Registry Utility | Token-standard factories, choice context, instrument configuration, and related disclosures used by the observed V1 and V2 flows | CHYPE-specific HyperEVM bridge completion | | CHYPE account contracts | Deposit and withdrawal account state, owner and registrar roles, pending balances, and bridge request records | HyperEVM finality without external verification | | BitSafe API | Current account rules and token-standard contracts used by the reviewed client | Authorization to bypass ledger choices or governance | | Attestor Network | Independent verification and threshold-governed HyperEVM bridge processing under the approved production design | A fixed operator count, named operator list, or fixed threshold in durable public documentation | ### What integrators should record For each production operation, retain the minimum diagnostic evidence permitted by the organization’s security policy: * Environment and reviewed component versions. * Authenticated party and intended instrument, without exposing credentials. * Command or request identifier. * Input holding contract identifiers. * Resulting transfer, account, request, update, and change-holding identifiers where applicable. * HyperEVM transaction hash for completed mint or redemption verification when available. * Timestamp and the last observed lifecycle state. Never place access tokens, passwords, private keys, or unredacted credential payloads in documentation, logs, or support tickets. ### Related implementation guides * [CHYPE environments and prerequisites](/chype/get-started/environments-and-prerequisites/) * [Mint CHYPE](/chype/guides/mint-chype/) * [Redeem CHYPE](/chype/guides/redeem-chype/) * [Transfer and receive CHYPE](/chype/guides/transfer-and-receive-chype/) * [CHYPE developer Quick Start](/chype/get-started/developer-quick-start/) ### Technical sources * [`DLC-link/bitsafe-token-lib` `v0.5.0` README](https://github.com/DLC-link/bitsafe-token-lib/blob/v0.5.0/README.md) * [`canton-lib` `crates/token/src/transfer.rs` at `v0.12.0`](https://github.com/DLC-link/canton-lib/blob/v0.12.0/crates/token/src/transfer.rs) * [`src/flows/canton_bridge_v1/deposit.rs` at `v0.5.0`](https://github.com/DLC-link/bitsafe-token-lib/blob/v0.5.0/src/flows/canton_bridge_v1/deposit.rs) * [`src/flows/canton_bridge_v1/withdraw.rs` at `v0.5.0`](https://github.com/DLC-link/bitsafe-token-lib/blob/v0.5.0/src/flows/canton_bridge_v1/withdraw.rs) * [`src/kits/evm/evm_asset_bridge.rs` at `v0.5.0`](https://github.com/DLC-link/bitsafe-token-lib/blob/v0.5.0/src/kits/evm/evm_asset_bridge.rs) * [`chype::mint::deposit_call` at `v0.5.0`](https://github.com/DLC-link/bitsafe-token-lib/blob/v0.5.0/src/tokens/chype/mod.rs#L234-L279) ### Related pages * [Mint CHYPE](/chype/guides/mint-chype/) * [Redeem CHYPE](/chype/guides/redeem-chype/) * [Transfer and receive CHYPE](/chype/guides/transfer-and-receive-chype/) * [CHYPE authentication](/chype/get-started/authentication/) * [CHYPE SDK, API, and integration reference](/chype/concepts-and-reference/sdk-api-and-integration-reference/) ### Next step → **Implement the model:** [CHYPE SDK, API, and integration reference](/chype/concepts-and-reference/sdk-api-and-integration-reference/). --- # Attestor Network and HyperEVM signing URL: https://docs.bitsafe.finance/chype/concepts-and-reference/attestor-network-and-hyperevm-signing/ [CHYPE architecture and trust boundaries](/chype/concepts-and-reference/architecture-and-trust-boundaries/) ### Attestor Network The Attestor Network is the set of independent institutional operators that verify eligible HyperEVM events and sign redemptions for CHYPE custody workflows. Operator membership and signing policy can change, so check the maintained security reference for current operating details. ### How attestors sign a redemption Each attestor holds its own HyperEVM signing key. For a redemption, each attestor signs a typed EIP-712 message. The message names the redemption, the destination address, the amount, and a deadline. The HyperEVM bridge contract releases HYPE only when it receives valid signatures from at least the threshold number of different attestors. The contract checks each signer against its list of attestors. No shared key or key share exists. The security benefit comes from the signature check in the contract, not from a special transaction type. ### What threshold signing does not do Threshold signing does not by itself: * Verify that a deposit or redemption request is valid. * Decide which redemption should be signed. * Protect a compromised operator application from approving bad input. * Guarantee service availability. * Replace monitoring, policy, access control, or incident response. ### Workflow boundary 1. The system identifies an eligible HyperEVM deposit or redemption event. 2. Operators independently receive the approved signing context. 3. Each participant applies the current verification and authorization policy. 4. The required threshold of attestors signs the redemption. 5. An attestor submits the signatures to the HyperEVM bridge contract, which checks them and releases HYPE. 6. The redemption result proceeds through the workflow. ### Key lifecycle Each attestor generates, stores, backs up, and rotates its own HyperEVM key. The bridge contract holds the list of attestor addresses. Adding, removing, or replacing an attestor is a role change on the contract. It does not need a key ceremony or a new contract. ### Availability and failure The network can continue only while enough eligible participants and required services are available under the active policy. One unavailable operator does not necessarily stop the network. Check the current service reference for applicable availability targets. ### Operator trust boundary Each operator must protect its infrastructure, credentials, signing key, software supply chain, and verification process. Independent operation reduces unilateral control. It does not remove the need to evaluate correlated failures or common software dependencies. ### Related pages * [CHYPE architecture and trust boundaries](/chype/concepts-and-reference/architecture-and-trust-boundaries/) * [CHYPE Proof of Reserve](/chype/concepts-and-reference/proof-of-reserve/) * [CHYPE security](/chype/concepts-and-reference/security/) ### Next step → **Review the complete control model:** [CHYPE security](/chype/concepts-and-reference/security/). --- # Proof of Reserve URL: https://docs.bitsafe.finance/chype/concepts-and-reference/proof-of-reserve/ ### What this page helps you do Use this page to: * Check CHYPE backing from public data. * Understand how the reserve total can be calculated independently from HyperEVM data. * Identify what the evidence proves and what it does not prove. * Stop safely when data is stale, incomplete, or inconsistent. ### The reserve claim CHYPE is designed as an HYPE-backed asset on Canton Network. The reserve claim is that the HYPE held by the HyperEVM bridge contract covers circulating CHYPE on a 1:1 basis. Use the maintained circulating-supply source, coverage formula, and freshness policy when evaluating the 1:1 reserve claim. ### Check CHYPE backing To perform a reserve check: 1. Read the HYPE balance of the Mainnet bridge contract `0x2940FcBb3C32901Df405da0E96fd97D1E2a53f34`. Use your own HyperEVM node or a block explorer. Record the balance and the block number. 2. Read the circulating CHYPE supply from the BitSafe API: ```http GET /chype/v1/total-supply ``` The response is the supply in whole CHYPE, as a plain decimal number with up to 10 decimal places, for example `0.01`. Record the value and the time of the request. 3. Convert the balance from wei to HYPE. One HYPE is 10^18 wei. 4. Compare the reserve with the supply. The reserve covers the supply when the HYPE balance is equal to or larger than the CHYPE supply. 5. Save the balance, block number, supply value, request time, and source links with your review record. **Expected outcome:** the HYPE balance is equal to or larger than the CHYPE supply. The reserve and the supply can differ for a short time while a deposit or a redemption is pending. In that case, the reserve is larger than the supply. The baseline is 1:1 backing. If the reserve is smaller than the supply, stop and follow the support and incident path in [Security and trust index](https://docs.bitsafe.finance/security-and-trust). ### What this evidence proves When the inputs are complete and current, the check can show: * The HYPE held by the bridge contract at the observed block. * The circulating CHYPE supply that the BitSafe API reports at the request time. * Whether the observed reserve amount is consistent with the fully backed claim. ### What this evidence does not prove Proof of Reserve is one control. It does not, by itself, prove: * That the reported CHYPE supply is correct. The BitSafe API reports the supply. For an independent read of the supply, use, for instance, the token metadata endpoint of the Digital Asset Utility registry. * Future reserve coverage. The result is valid only for its observation time and data freshness. * That redemption will complete within a specific time or at a specific cost. * That contracts, signing software, operators, APIs, or operational processes are free of defects. * That one HyperEVM data provider is correct. High-assurance checks should compare independent sources. ### Handle stale, missing, or inconsistent data * Do not interpret missing data as a zero balance. * Do not treat a stale observation as current reserve evidence. * Do not compare a balance and a supply value from far apart in time. * Record the balance, block number, supply value, and request time before escalating. * Re-run the check with a second approved HyperEVM data source. * Escalate through the approved support and incident path if the reserve is smaller than the supply or independent sources disagree. Use the maintained security and support references for the current freshness threshold, severity levels, contact, incident path, and retry interval. ### Technical sources * [HyperEVM bridge](https://github.com/DLC-link/evm-asset-bridge) * [Digital Asset Utility registry: instrument metadata API](https://docs.digitalasset.com/api-reference/public/get-apitoken-standardv0registrars-registrymetadatav1instruments) ### Related pages * [How CHYPE works](/chype/how-chype-works/) * [CHYPE architecture and trust boundaries](/chype/concepts-and-reference/architecture-and-trust-boundaries/) * [CHYPE Attestor Network](/chype/concepts-and-reference/attestor-network-and-hyperevm-signing/) * [CHYPE security](/chype/concepts-and-reference/security/) ### Next step → **Put the evidence in context:** [Security and trust index](https://docs.bitsafe.finance/security-and-trust). --- # Security URL: https://docs.bitsafe.finance/chype/concepts-and-reference/security/ [CHYPE architecture and trust boundaries](/chype/concepts-and-reference/architecture-and-trust-boundaries/) ### Security model CHYPE combines HYPE custody in a threshold-signed HyperEVM bridge contract, independent event verification, Canton authorization and privacy, versioned Daml packages, authenticated service integrations, and reserve evidence. No single control should be presented as the entire security model. ### Security layers | Layer | Primary control | Review focus | | ------------------ | ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | | HYPE custody | Bridge contract that releases HYPE only with threshold attestor signatures | Contract code, upgrade governance, limits, pause, attestor key lifecycle, and correlated risk | | Event verification | Attestor Network policy and evidence | Duplicate prevention, transaction validity, and authorization | | Canton contracts | Daml authorization and party rights | Package versions, choices, privacy, and migration | | Client integration | Authentication, least privilege, validation, and idempotency | Secrets, wrong-party risk, retries, and logs | | Backing evidence | Proof of Reserve and reconciliation | Scope, cadence, stale data, and exclusions | | Operations | Monitoring, change control, incident response, and support | Ownership, escalation, and recovery testing | ### Integrator responsibilities Integrators must verify parties, deposit account IDs, and HyperEVM destination addresses, pin compatible releases, protect credentials, validate contract state, reconcile ambiguous submissions, and use approved support channels. CHYPE infrastructure cannot protect an application that sends an authorized command with incorrect inputs. ### Privacy boundary Canton limits contract visibility through sub-transaction privacy. HyperEVM transactions remain visible on HyperEVM. Application logs, support exports, and external systems can reveal information if operators do not protect them. ### Audits Each audit report identifies the contracts, services, release tags, and dates within its scope. An audit is evidence about reviewed components at a point in time. It is not a guarantee that every deployment or future release is secure. ### Vulnerability reporting Report suspected vulnerabilities through the private security contact listed in [Security and trust index](https://docs.bitsafe.finance/security-and-trust). Do not post unpatched vulnerabilities in public issues. Include the affected release, impact, reproduction steps, and safe contact details. ### Known limitations Check [CHYPE compatibility and release notes](/chype/concepts-and-reference/compatibility-and-release-notes/) for supported versions, operational dependencies, known issues, and applicable audit scope. ### Related pages * [CHYPE architecture and trust boundaries](/chype/concepts-and-reference/architecture-and-trust-boundaries/) * [CHYPE Attestor Network](/chype/concepts-and-reference/attestor-network-and-hyperevm-signing/) * [CHYPE Proof of Reserve](/chype/concepts-and-reference/proof-of-reserve/) * [CHYPE authentication](/chype/get-started/authentication/) * [CHYPE compatibility and release notes](/chype/concepts-and-reference/compatibility-and-release-notes/) * [Security and trust index](https://docs.bitsafe.finance/security-and-trust) ### Next step → **Confirm the evidence and reporting path:** [Security and trust index](https://docs.bitsafe.finance/security-and-trust). --- # SDK, API, and integration reference URL: https://docs.bitsafe.finance/chype/concepts-and-reference/sdk-api-and-integration-reference/ ### Supported source libraries * [`bitsafe-token-lib`](https://github.com/DLC-link/bitsafe-token-lib): Workflows and examples for BitSafe assets. * [`canton-lib`](https://github.com/DLC-link/canton-lib): shared Canton API clients, utilities, and the Token Standard operations that `bitsafe-token-lib` re-exports. Pin approved release tags and keep their compatibility row together. ### Integration layers | Layer | Use | | ------------------------ | -------------------------------------------------------------------------- | | Generated Canton clients | Authenticate, query contracts, submit commands, and read updates | | CHYPE workflow functions | Balance, transfer, mint, redeem, account, and credential operations | | BitSafe API client | Retrieve approved account rules and token-standard contracts | | HyperEVM bridge call | [Build the `depositETH` transaction for a deposit](/chype/guides/mint-chype/) | | Examples | Executable references for supported tasks | ### Recommended integration pattern 1. Load configuration through a typed layer. 2. Create authenticated Canton and BitSafe API clients. 3. Verify the party with a read-only query. 4. Query current contracts and runtime rules. 5. Validate the business request. 6. Submit one command with a unique reference where supported. 7. Read the authoritative result. 8. Reconcile Canton, application, and HyperEVM identifiers. ### API reference policy Generated type and method documentation should remain in the repository or generated reference site. Public task guides should link to exact release documentation instead of copying full schemas. ### Examples to preserve Balance checks, sending, incoming and outgoing offers, accepting or cancelling offers, credentials, minting, redemption, account inspection, batch transfers, and UTXO management. ### Deposit event layout The `mint::Deposit` type in `bitsafe-token-lib` 0.5.0 uses this shared EVM event layout: ```solidity event Deposit( bytes32 indexed depositAccountIdHash, bytes depositAccountId, address indexed sender, uint256 amount, uint256 prevDepositBlock ); ``` `prevDepositBlock` identifies the previous deposit block for the same account. A zero value means no earlier deposit exists since deployment or the upgrade that adds this field. Two deposits for one account can share a block. The second then has `prevDepositBlock` equal to its own block number. The bridge view `lastDepositBlock(bytes32 depositAccountIdHash)` returns the block of the last deposit. The log filter must include the proxy address, topic0, and topic1 for the account. `mint::deposit_id_topic` computes topic1 from the deposit account ID. Read all matching logs in each block and use their lowest `prevDepositBlock` as the next link. The [bridge's deposit-link guide](https://github.com/DLC-link/evm-asset-bridge/blob/e6c3be776586054eeb43c33d33664788c2b88ed5/README.md#the-deposit-links) describes the complete walk. This view belongs to the bridge contract; the library provides no wrapper for it. Callers that construct `Deposit` values must supply the new field. `mint::DEPOSIT_EVENT_TOPIC` now matches only the five-field event: ```text 0xf3ca88974ec5963addc617fe6c0c359d7196759e318be6ab0cade940986e30e2 ``` Callers that scan historical deposits must also filter on the old topic: ```text 0xacaea730ea841fae3326f72a7ff746b6e06c646840526bcaf5dabee5fd887ef8 ``` Declare the old four-field layout in a separate `sol!` block to decode those logs. The new `Deposit` decoder rejects logs with the old topic. Decoding old data without checking the topic can silently produce an incorrect `prevDepositBlock` value. The library provides one event binding; callers select the decoder by the log topic. Check the bridge ABI for the deployment and block range that you query. ### Technical sources * [Shared EVM event binding at `v0.5.0`](https://github.com/DLC-link/bitsafe-token-lib/blob/v0.5.0/src/kits/evm/evm_asset_bridge.rs) * [`bitsafe-token-lib` examples guide at `v0.5.0`](https://github.com/DLC-link/bitsafe-token-lib/blob/v0.5.0/examples/README.md) * [HyperEVM bridge contract](https://github.com/DLC-link/evm-asset-bridge) ### Related pages * [CHYPE developer Quick Start](/chype/get-started/developer-quick-start/) * [CHYPE authentication](/chype/get-started/authentication/) * [Transfer and receive CHYPE](/chype/guides/transfer-and-receive-chype/) * [Mint CHYPE](/chype/guides/mint-chype/) * [Redeem CHYPE](/chype/guides/redeem-chype/) * [CHYPE errors, retries, and troubleshooting](/chype/concepts-and-reference/errors-retries-and-troubleshooting/) * [CHYPE compatibility and release notes](/chype/concepts-and-reference/compatibility-and-release-notes/) ### Next step → **Validate the integration:** [CHYPE developer Quick Start](/chype/get-started/developer-quick-start/). --- # Errors, retries, and troubleshooting URL: https://docs.bitsafe.finance/chype/concepts-and-reference/errors-retries-and-troubleshooting/ ### First rule After a timeout or transport error, do not assume the command failed. Query the authoritative Canton, account, transfer-offer, or HyperEVM state before retrying. ### Error classes | Class | Examples | Response | | ------------------ | --------------------------------------------- | ---------------------------------------------- | | Configuration | Wrong endpoint, party, package, network | Stop and correct configuration | | Authentication | Expired token, wrong audience, missing rights | Refresh or correct access, then re-query state | | Validation | Bad amount, destination, offer, or contract | Do not retry unchanged | | Conflict | Archived contract or concurrent action | Refresh active state and rebuild | | Transport | Timeout, disconnect, unavailable service | Determine commitment before retrying | | External lifecycle | HyperEVM finality or attestation delay | Monitor the existing workflow | ### Idempotency pattern Use one business reference and command identifier for one intent where supported. Persist it before submission. On uncertainty, search by that reference and resulting contract or update identifiers. ### Retry policy Retry only operations documented as safe. Use bounded exponential backoff with jitter for read-only transport failures. Do not automatically retry mint, redemption, transfer acceptance, cancellation, or account creation without checking state. ### Support evidence Collect the environment, UTC time, release set, party, sanitized request reference, Canton update or contract identifiers, HyperEVM transaction hash where relevant, error code, and logs with secrets removed. ### Related pages * [CHYPE authentication](/chype/get-started/authentication/) * [Mint CHYPE](/chype/guides/mint-chype/) * [Redeem CHYPE](/chype/guides/redeem-chype/) * [Transfer and receive CHYPE](/chype/guides/transfer-and-receive-chype/) * [CHYPE batch transfers and UTXO management](/chype/guides/batch-transfers-and-management/) * [Support and developer resources](https://docs.bitsafe.finance/support-and-developer-resources) ### Next step → **Still blocked?** [Support and developer resources](https://docs.bitsafe.finance/support-and-developer-resources). --- # Compatibility and release notes URL: https://docs.bitsafe.finance/chype/concepts-and-reference/compatibility-and-release-notes/ [CHYPE environments and prerequisites](/chype/get-started/environments-and-prerequisites/) ### Purpose Use this reference to: * Choose a known-good CHYPE 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 CHYPE 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. * Review [the chrono advisory follow-up](https://github.com/DLC-link/bitsafe-token-lib/issues/20) before adopting this release. * 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.5.0` | The release package manifest reports version `0.5.0`. | Repository baseline. Verify the target environment and support window. | | `canton-lib` | `v0.12.0` | `bitsafe-token-lib` `v0.5.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.5.0` package manifest. | Wire-client baseline. Verify the approved participant range. | | Canton participant | `3.6.1` for `bitsafe-token-lib` `v0.5.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. | | CHYPE DAR package | Package bundled at `bitsafe-token-lib` `v0.5.0`: `chype-0.1.0.dar` | The `v0.5.0` DAR directory includes `chype-0.1.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 | CHYPE DAR | Utility and Splice release | Last verified | Support status | | ------------------------ | ------------------- | ------------ | ------------------------------- | -------------------------- | ------------------------------- | ----------------------------------- | ------------------------ | | Repository baseline only | `v0.5.0` | `v0.12.0` | Verify in the maintained matrix | Bundled candidate: `0.1.0` | Verify in the maintained matrix | 18 November 2026, source review and local build | 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 chype`, which uploads dependency DARs before CHYPE DARs. Confirm the environment manifest before running it. 6. **Run the DAR inventory check.** `ASSET=chype 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 :::note Release notes summarize public repository releases. They are not deployment announcements and do not prove that every environment supports the released files. ::: Each library publishes its release notes on GitHub: * [`bitsafe-token-lib` `v0.5.0` release notes](https://github.com/DLC-link/bitsafe-token-lib/releases/tag/v0.5.0) * [`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 | | ---------------------------------------------------------------------------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | | Four-field EVM `Deposit` in BETH and CHYPE | Five-field `Deposit` with `prevDepositBlock` | Update struct literals and event filters. Decode historical logs with a separate four-field binding and the old topic. | Breaking change in `bitsafe-token-lib` `v0.5.0`. CBTC APIs remain unchanged. | | Version-pinned UserService template ID in `AcceptCredentialOfferParams` | Package-name template ID that the library sets | Remove the `user_service_template_id` field from each `credentials::accept_credential_offer` call. | Removed in `canton-lib` `v0.12.0`. A participant that does not vet the old package version rejects the old accept. | | `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.5.0`](https://github.com/DLC-link/bitsafe-token-lib/releases/tag/v0.5.0) * [`bitsafe-token-lib` package manifest at `v0.5.0`](https://github.com/DLC-link/bitsafe-token-lib/blob/v0.5.0/Cargo.toml) * [`bitsafe-token-lib` changelog at `v0.5.0`](https://github.com/DLC-link/bitsafe-token-lib/blob/v0.5.0/CHANGELOG.md) * [CHYPE DAR guidance at `v0.5.0`](https://github.com/DLC-link/bitsafe-token-lib/tree/v0.5.0/dars) * [`canton-lib` changelog at `v0.12.0`](https://github.com/DLC-link/canton-lib/blob/v0.12.0/CHANGELOG.md) * [`canton-lib` package manifest at `v0.12.0`](https://github.com/DLC-link/canton-lib/blob/v0.12.0/Cargo.toml) ### Related pages * [CHYPE environments and prerequisites](/chype/get-started/environments-and-prerequisites/) * [Install and validate CHYPE DARs](/chype/get-started/install-and-validate-dars/) * [CHYPE SDK, API, and integration reference](/chype/concepts-and-reference/sdk-api-and-integration-reference/) * [CHYPE errors, retries, and troubleshooting](/chype/concepts-and-reference/errors-retries-and-troubleshooting/) * [Support and developer resources](https://docs.bitsafe.finance/support-and-developer-resources) ### Next step → **Use a supported path:** [CHYPE developer Quick Start](/chype/get-started/developer-quick-start/). --- # Overview URL: https://docs.bitsafe.finance/cbtc/ :::note Looking for the documentation of `cbtc-lib` v0.9.0? See the [legacy docs](/cbtc/legacy/). ::: ### CBTC brings Bitcoin into Canton workflows CBTC is BitSafe’s representation of Bitcoin for applications and institutions operating on Canton Network. It gives teams a documented path to hold, transfer, mint, redeem, and integrate Bitcoin-backed value within Canton applications. This page explains what CBTC is and routes readers to the right task. Detailed lifecycles, setup values, APIs, architecture, and security controls live in their canonical pages. ### What you can do * Hold and transfer CBTC between authorized Canton parties. * Mint CBTC from an eligible Bitcoin deposit. * Redeem CBTC to an approved Bitcoin destination. * Integrate supported CBTC workflows through pinned libraries and APIs. * Review custody, privacy, backing evidence, and operational controls. ### Choose a path | Goal | Canonical page | | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Understand the lifecycle | [How CBTC works](/cbtc/how-cbtc-works/) | | Choose an operation | [Choose a CBTC path](/cbtc/choose-a-cbtc-path/) | | Build an integration | [CBTC developer Quick Start](/cbtc/get-started/developer-quick-start/) | | Review architecture and security | [CBTC architecture and trust boundaries](/cbtc/concepts-and-reference/architecture-and-trust-boundaries/) and [CBTC security](/cbtc/concepts-and-reference/security/) | | Check releases and compatibility | [CBTC compatibility and release notes](/cbtc/concepts-and-reference/compatibility-and-release-notes/) | ### Product boundaries CBTC spans Bitcoin and Canton, but Bitcoin does not move on Canton during every transfer. Bitcoin deposits and redemptions are coordinated with corresponding CBTC state changes. Canton’s configurable sub-transaction privacy applies to entitled Canton contract data; Bitcoin transactions remain visible on Bitcoin. CBTC is intended to remain backed 1:1 by Bitcoin. The evidence, calculation path, and limitations belong in [CBTC Proof of Reserve](/cbtc/concepts-and-reference/proof-of-reserve/). ### Technical sources * [BitSafe token library](https://github.com/DLC-link/bitsafe-token-lib) * [Shared Canton library](https://github.com/DLC-link/canton-lib) ### Next step → **Understand the operating model:** [How CBTC works](/cbtc/how-cbtc-works/). --- # CBTC Ecosystem URL: https://docs.bitsafe.finance/cbtc/cbtc-ecosystem/ [CBTC overview](/cbtc/) Use this page to find third-party wallets, trading venues, and lending platforms that support CBTC. :::note Availability, supported environments, pairs, eligibility, fees, and product terms can change. Confirm current CBTC support directly with the provider before transferring assets or integrating a service. A listing is informational and is not an endorsement by BitSafe. ::: ### Wallets Store, send, receive, or custody CBTC alongside other supported Canton assets.
Wallet or custodianDescriptionWebsite
BronNon-custodial wallet with MPC technology and configurable policy controls.bron.org
ConsoleSelf-custodial browser wallet with passkey authentication, name-based sending, phishing protection, and searchable transaction history.consolewallet.io
FinoaInstitutional digital-asset custodian offering custody and trading services.finoa.io
Meteor WalletSelf-custodial wallet for supported Canton assets, swaps, and access to supported lending markets.app.canton.meteorwallet.app
Nightly WalletMulti-chain, non-custodial wallet for key management, asset holding, and application access.nightly.app
C8 WalletCanton wallet from Cantor8 for asset access and supported application interactions.cantor8.io
Cypherock WalletHardware and software wallet interface for managing supported Canton assets across desktop, mobile, and web.cypherock.com
LoopSelf-custodial Canton wallet accessible through mobile and desktop browsers.cantonloop.com
ModuloMulti-chain self-custody wallet and protocol interface for supported lending, borrowing, swapping, and trading services.modulo.finance
Node Fortress WalletNon-custodial wallet for Canton Coin and supported Canton token-standard assets.wallet.nodefortress.io
WalleyNon-custodial wallet for holding and transacting supported Canton assets.walley.cc
Zoro WalletNon-custodial Canton wallet that runs in mobile and desktop web browsers.zorowallet.com
Canton WalletPrivacy-first self-custody wallet with passkey onboarding and multisig support.cantonwallet.com
SupanovaSelf-custody wallet for supported Canton assets.supanova.app
CauriSelf-custody wallet for supported Canton assets.cauri.cc
### Trading venues Trade, swap, or provide liquidity through services that list or integrate CBTC.
VenueTypeCBTC availabilityWebsite
Temple TradingCentral limit order bookCBTC pairs include CC–CBTC and USDCx–CBTCapp.templedigitalgroup.com
CancoreWallet and trading venueCheck the provider for current pairscancore.io
CantexWallet and trading venueMultiple pairs; check the provider for current availabilitycantex.io
C8 Wallet DEXWallet and trading venueCheck the provider for current pairswallet.cantor8.tech
KoraRequest-for-quote venueCheck the provider for current spot, derivatives, and tokenized-asset marketskora.so
Rho RelayRequest-for-quote venue and bridgeCross-chain CBTC swapsrelay.rho.trading
Silvana BookOff-chain matching with on-chain settlementCheck the provider for current pairssilvana.one
KairoRequest-for-quote venueMultiple pairs; check the provider for current availabilitykairo.ag
HelvetSwapAutomated market makerCBTC and Canton Coin marketshelvetswap.app
OneSwapAutomated market makerCheck the provider for current pairsoneswap.cc
Pool PartyAutomated market makerCBTC swaps and liquidity provisionsend.cantonwallet.com
TradecraftAtomic swap venueCBTC and other CIP-56 token swapscantonswap.com
Rocky ExchangePerpetuals venueCBTC perpetual markets; check the provider for current availabilityrocky.exchange
### Lending platforms Use supported lending platforms to borrow against CBTC, supply assets, or access institution-specific financing terms. | Platform | Description | Website | | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | | ACME Lend | Overcollateralized lending platform supporting CBTC and other Canton assets. Check the provider for current collateral and liquidation parameters. | [acmemarkets.cc](https://acmemarkets.cc) | | Alpend | On-ledger lending and borrowing market for supported digital assets. | [app.alpend.com](https://app.alpend.com/) | | Haven Digital Partners | Institutional peer-to-peer lending marketplace with qualified custody and negotiated terms. | [havendp.com](https://canton-lending.havendp.com/login) | | Verity | Financing platform connecting lenders and borrowers for supported on-chain and off-chain settlement workflows. | [hashrupt.com](https://hashrupt.com) | ### Choose a provider Before using a third-party service: 1. Confirm that the provider supports CBTC in your intended environment. 2. Check institutional or regional eligibility requirements. 3. Review custody, counterparty, smart-contract, liquidity, and operational risks. 4. Confirm current fees, pairs, collateral parameters, and withdrawal conditions with the provider. 5. Test the workflow with the smallest amount permitted by your organization’s policy. ### Integrate CBTC Wallets, trading venues, and lending platforms can use BitSafe’s open-source libraries as integration starting points: * [`bitsafe-token-lib`](https://github.com/DLC-link/bitsafe-token-lib) * [`canton-lib`](https://github.com/DLC-link/canton-lib) ### Related pages * [CBTC overview](/cbtc/) * [Choose a CBTC path](/cbtc/choose-a-cbtc-path/) * [Transfer and receive CBTC](/cbtc/guides/transfer-and-receive-cbtc/) * [CBTC SDK, API, and integration reference](/cbtc/concepts-and-reference/sdk-api-and-integration-reference/) * [Support and developer resources](/support-and-developer-resources/) ### **Integrating CBTC into an institutional product?** Talk to BitSafe --- # How CBTC works URL: https://docs.bitsafe.finance/cbtc/how-cbtc-works/ [CBTC overview](/cbtc/) ### The short version CBTC represents Bitcoin on Canton Network. A mint starts with Bitcoin sent to a deposit address. The system verifies the deposit and creates the corresponding CBTC for the intended Canton party. A redemption consumes CBTC and releases Bitcoin to an approved destination. Transfers between Canton parties use Canton contracts and do not move the underlying Bitcoin for each transfer. ### The system has two connected ledgers * **Bitcoin:** holds the Bitcoin that backs CBTC and records deposits and redemption transactions. * **Canton Network:** records CBTC holdings, transfers, account workflows, and the parties authorized to act. The integration layer links a Bitcoin event to its corresponding Canton workflow. It must prevent duplicate processing and preserve enough identifiers for reconciliation. ### Mint lifecycle 1. The Canton party obtains the required credential and current deposit-account rules. 2. The party creates a deposit account. 3. The approved service returns a Bitcoin deposit address associated with that account. 4. The depositor verifies the network and sends Bitcoin to the address. 5. The system detects the transaction and waits for the approved confirmation state. 6. Independent Attestor Network participants verify the eligible Bitcoin event. 7. The approved threshold authorizes the mint workflow. 8. CBTC is created for the intended Canton party. 9. The Bitcoin transaction, account, attestation, Canton update, and resulting holding are reconciled. ### Transfer lifecycle A Canton transfer does not redeem Bitcoin. The sender creates a transfer offer for a receiver. The receiver inspects and accepts the intended offer unless an approved preapproval flow applies. Canton archives or updates the relevant contracts and creates the receiver’s new holding state. ### Redemption lifecycle 1. The party validates a Bitcoin destination. 2. The party creates or selects a withdrawal account using current rules. 3. The application selects sufficient CBTC holdings. 4. The party submits the redemption. 5. The Canton contract flow consumes the applicable CBTC state. 6. The approved Bitcoin signing workflow creates and broadcasts the redemption transaction. 7. The application tracks completion on Bitcoin and Canton. 8. The records are reconciled to one request. ### Who does what | Role | Responsibility | Boundary | | ------------------ | ---------------------------------------------------------------------------- | --------------------------------------------------------- | | CBTC holder | Owns Canton holdings and initiates supported actions | Can act only with the party’s authorization | | BitSafe services | Coordinate account and integration workflows | Cannot be described as able to move reserves unilaterally | | Attestor Network | Verifies eligible Bitcoin events and participates in threshold authorization | No single operator is sufficient | | Canton participant | Hosts the party and submits or observes authorized Canton actions | Visibility follows Canton entitlements | | Bitcoin network | Records deposits and redemption transactions | Confirmation and fee behavior are external to Canton | ### Backing and verification CBTC is intended to remain backed 1:1 by Bitcoin. Public documentation should distinguish: * Bitcoin reserves visible on Bitcoin. * CBTC supply and contract state visible to entitled Canton parties. * Proof of Reserve evidence and its exact coverage. * Operational reconciliation performed by the system. ### Failure boundaries A workflow can pause because of Bitcoin confirmation delays, service availability, Canton connectivity, authentication, incompatible packages, insufficient approvals, or an ambiguous prior submission. Clients must query authoritative state before retrying. ### Related guides * [Mint CBTC](/cbtc/guides/mint-cbtc/) * [Redeem CBTC](/cbtc/guides/redeem-cbtc/) * [Transfer and receive CBTC](/cbtc/guides/transfer-and-receive-cbtc/) * [CBTC architecture and trust boundaries](/cbtc/concepts-and-reference/architecture-and-trust-boundaries/) ### Technical sources * [`bitsafe-token-lib` repository](https://github.com/DLC-link/bitsafe-token-lib) * [`canton-lib` repository](https://github.com/DLC-link/canton-lib) ### Next step → **Choose an operation:** [Choose a CBTC path](/cbtc/choose-a-cbtc-path/). --- # Choose a CBTC path URL: https://docs.bitsafe.finance/cbtc/choose-a-cbtc-path/ Choose the path that matches your role and immediate task. Start with a read-only check before any state-changing workflow. ### Institutions and trading firms Start with [CBTC overview](/cbtc/), then review transfer operations and the security model. Use the mint or redemption guides only if your organization runs the required Canton infrastructure and has approved access. ### Application developers 1. Review [CBTC environments and prerequisites](/cbtc/get-started/environments-and-prerequisites/). 2. Complete [CBTC developer Quick Start](/cbtc/get-started/developer-quick-start/). 3. [Install and validate CBTC DARs](/cbtc/get-started/install-and-validate-dars/). 4. Choose the [Transfer and receive CBTC](/cbtc/guides/transfer-and-receive-cbtc/), [Mint CBTC](/cbtc/guides/mint-cbtc/), or [Redeem CBTC](/cbtc/guides/redeem-cbtc/) integration. 5. Add [CBTC authentication](/cbtc/get-started/authentication/), reconciliation, and [CBTC errors, retries, and troubleshooting](/cbtc/concepts-and-reference/errors-retries-and-troubleshooting/). ### Canton operators Start with [CBTC compatibility and release notes](/cbtc/concepts-and-reference/compatibility-and-release-notes/), [Install and validate CBTC DARs](/cbtc/get-started/install-and-validate-dars/), [CBTC authentication](/cbtc/get-started/authentication/), monitoring, and recovery. Confirm the participant and package state before enabling an application team. ### Security reviewers Review [CBTC architecture and trust boundaries](/cbtc/concepts-and-reference/architecture-and-trust-boundaries/), [CBTC Attestor Network and FROST](/cbtc/concepts-and-reference/attestor-network-and-frost/), [CBTC Proof of Reserve](/cbtc/concepts-and-reference/proof-of-reserve/), [CBTC authentication](/cbtc/get-started/authentication/), [CBTC security](/cbtc/concepts-and-reference/security/), and [CBTC compatibility and release notes](/cbtc/concepts-and-reference/compatibility-and-release-notes/). Match every claim to a release and approved evidence source. ### Task map | Goal | Start here | | ---------------------- | ------------------------------------------------------------------ | | Evaluate CBTC | [How CBTC works](/cbtc/how-cbtc-works/) | | Connect an application | [CBTC developer Quick Start](/cbtc/get-started/developer-quick-start/) | | Mint | [Mint CBTC](/cbtc/guides/mint-cbtc/) | | Redeem | [Redeem CBTC](/cbtc/guides/redeem-cbtc/) | | Transfer | [Transfer and receive CBTC](/cbtc/guides/transfer-and-receive-cbtc/) | | Review security | [CBTC security](/cbtc/concepts-and-reference/security/) | ### Next step → **New to CBTC development?** [CBTC developer Quick Start: public documentation draft](/cbtc/get-started/developer-quick-start/). --- # Environments and prerequisites URL: https://docs.bitsafe.finance/cbtc/get-started/environments-and-prerequisites/ [CBTC overview](/cbtc/) ### Before you start Choose the CBTC operation you need to perform before configuring an environment. Balance queries, transfers, minting, redemption, batch distribution, and UTXO management do not all share the same prerequisites. ### Choose an environment | Environment | Use it for | Before proceeding | | ----------- | ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | Development | Local development and early workflow testing | Confirm the current participant, registry, BitSafe API, credential, and test-asset setup. | | Testnet | Integration testing against shared infrastructure | Confirm endpoint ownership, faucet availability, reset policy, and differences from production. | | Mainnet | Production workloads | Use only an Engineering-approved compatibility row, production credentials, monitoring, recovery procedures, and security review. | Obtain current endpoints, party identifiers, and package identifiers from the maintained environment reference. Check its owner and last-verified date before use. ### Core prerequisites All CBTC development paths require: * Access to a supported Canton participant. * A Canton party authorized for the intended operation. * A supported authentication configuration and a safe method for storing credentials. * A compatible Rust toolchain when using the current Rust library. * A pinned `bitsafe-token-lib` release and compatible shared `canton-lib` crates. * Network access to the required Canton and external service endpoints. * A test plan that states the expected ledger and application result. ### Operation-specific prerequisites | Operation | Additional prerequisites | | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | Check balances or contracts | Ledger host, authenticated party, and compatible query interface. | | Send, receive, accept, reject, or cancel | Digital Asset Registry Utility components, receiver party details, required transfer context, and sufficient holdings. | | Mint CBTC | BitSafe API access, required Minter credential, compatible CBTC DAR packages, account rules, and a Bitcoin deposit flow. | | Redeem CBTC | BitSafe API access, required Minter credential, compatible CBTC DAR packages, sufficient holdings, and a valid Bitcoin destination. | | Batch distribution | Transfer prerequisites plus recipient input validation, limits, callbacks or result capture, and reconciliation. | | UTXO management | Current holdings, approved split or consolidation policy, and a clear reason for changing the holding layout. | ### Install compatible components The examples on this page use: * `bitsafe-token` package version `0.5.0`. * `canton-lib` dependencies pinned to `v0.12.0`. * A Canton API client generated from Canton `3.6.1` specifications. For deployment, use the approved compatibility matrix for the BitSafe token library, shared Canton library, Canton version, DAR packages, API behavior, and target environment. ### Configure safely Configuration falls into four groups: 1. **Canton connection:** ledger host and party identity. 2. **Authentication:** approved identity-provider host, realm or audience, client identity, and secret-handling method. 3. **CBTC network:** the `ENVIRONMENT` value (`devnet`, `testnet`, or `mainnet`). It selects the Decentralized Party, the registry, and the BitSafe API for the target network. 4. **Mint and redeem:** BitSafe API selection and Bitcoin destination details where needed. Never commit `.env` files, tokens, passwords, client secrets, party-specific credentials, or production addresses. Use placeholders in public examples and document how readers obtain real values through approved channels. ### Preflight checklist * [ ] The target environment is approved for the intended test. * [ ] The Canton participant is reachable. * [ ] Authentication succeeds for the intended party. * [ ] The pinned library set builds successfully. * [ ] Required DAR packages are installed and validated. * [ ] Registry and BitSafe services required by the operation are reachable. * [ ] The party has the required credential and holdings. * [ ] The expected result and rollback or recovery path are documented. * [ ] Logs and identifiers needed for support can be collected without exposing secrets. ### Verify the setup Start with a read-only operation such as a connection or balance check. A successful preflight should confirm: * Authentication completed. * The intended party was used. * The ledger query returned a valid response. * The application can parse the response with the pinned library set. Continue to a state-changing operation only after the read-only check passes. ### Technical sources * [`bitsafe-token-lib` `v0.5.0`](https://github.com/DLC-link/bitsafe-token-lib/tree/v0.5.0) * [`bitsafe-token-lib` environment example](https://github.com/DLC-link/bitsafe-token-lib/blob/v0.5.0/.env.example) * [CBTC DAR guidance](https://github.com/DLC-link/bitsafe-token-lib/tree/v0.5.0/dars) * [`canton-lib` `v0.12.0`](https://github.com/DLC-link/canton-lib/tree/v0.12.0) ### Related pages * [CBTC developer Quick Start](/cbtc/get-started/developer-quick-start/) * [Install and validate CBTC DARs](/cbtc/get-started/install-and-validate-dars/) * [CBTC authentication](/cbtc/get-started/authentication/) * [Mint CBTC](/cbtc/guides/mint-cbtc/) * [Redeem CBTC](/cbtc/guides/redeem-cbtc/) * [Transfer and receive CBTC](/cbtc/guides/transfer-and-receive-cbtc/) * [CBTC compatibility and release notes](/cbtc/concepts-and-reference/compatibility-and-release-notes/) ### Next step → **Verify your setup:** [CBTC developer Quick Start](/cbtc/get-started/developer-quick-start/). --- # Developer quick start URL: https://docs.bitsafe.finance/cbtc/get-started/developer-quick-start/ [CBTC overview](/cbtc/) · [CBTC environments and prerequisites](/cbtc/get-started/environments-and-prerequisites/) ### What you will do 1. Prepare a supported Rust environment. 2. Check out a pinned `bitsafe-token-lib` release. 3. Configure Canton and authentication values without committing secrets. 4. Run the balance-check example. 5. Verify that the response belongs to the intended party. This read-only outcome is intentionally smaller than minting or transferring CBTC. It verifies the core connection before you create accounts or submit ledger changes. ### Prerequisites * Access to an approved development or test environment. * A supported Canton participant and party. * Approved authentication credentials for that party. * Git and a compatible Rust toolchain. * Network access to the Canton participant and identity provider. * A secure local method for storing environment values. ### 1. Check out the reviewed source ```bash git clone https://github.com/DLC-link/bitsafe-token-lib.git cd bitsafe-token-lib git checkout v0.5.0 ``` Use an approved release tag. Do not use `main` in production instructions. ### 2. Create local configuration ```bash cp .env.example .env ``` Fill only the values required for the balance check: * Canton JSON Ledger API host, including the API path. * Target Canton party. * Approved identity-provider and client values required by the selected authentication flow. * The `ENVIRONMENT` value: `devnet`, `testnet`, or `mainnet`. * The `ASSET` value: `cbtc`. Do not paste real credentials into documentation, issue reports, shell history, or source control. ### 3. Build the example ```bash cargo build --example check_balance ``` A successful build confirms that the selected Rust toolchain can resolve the pinned CBTC and shared Canton dependencies. ### 4. Run the balance check ```bash cargo run --example check_balance ``` ### Expected result The command should: * Authenticate successfully. * Query active CBTC holdings for the configured party. The query keeps only holdings whose instrument ID and admin both match the CBTC instrument. * Report the party’s balance and holding count, including a valid zero-balance result where applicable. * Exit without exposing access tokens or passwords. :::note Output fields vary by supported release and environment. Verify the response belongs to the intended party, and never substitute a fabricated balance or contract identifier when testing an integration. ::: ### If the check fails | Symptom | Check | Next action | | ------------------------ | ------------------------------------------------------------------------- | --------------------------------------------------------------------------- | | Authentication fails | Provider URL, realm or audience, client, grant type, secret, token claims | Use the canonical Authentication guide and confirm the party authorization. | | Connection fails | Ledger host, DNS, TLS, proxy, and network access | Verify the participant endpoint with the environment owner. | | No holdings are returned | Target party, environment, and whether zero balance is valid | Confirm the configured party before attempting a state-changing operation. | | Build or type errors | Checked-out tag, Rust toolchain, lockfile, and shared library access | Return to the approved compatibility matrix. | | Response parsing fails | Canton and library compatibility | Capture sanitized output and escalate with the version set. | ### Next steps After the balance check passes, choose one task: * [Transfer and receive CBTC](/cbtc/guides/transfer-and-receive-cbtc/). * Create a deposit account and follow [Mint CBTC](/cbtc/guides/mint-cbtc/). * Create a withdrawal account and follow [Redeem CBTC](/cbtc/guides/redeem-cbtc/). * Use [CBTC SDK, API, and integration reference](/cbtc/concepts-and-reference/sdk-api-and-integration-reference/) to integrate balance and transfer behavior into a wallet or application. ### Technical sources * [`bitsafe-token-lib` `v0.5.0`](https://github.com/DLC-link/bitsafe-token-lib/tree/v0.5.0) * [Balance-check example](https://github.com/DLC-link/bitsafe-token-lib/blob/v0.5.0/examples/check_balance.rs) * [Examples guide](https://github.com/DLC-link/bitsafe-token-lib/blob/v0.5.0/examples/README.md) ### Related pages * [Install and validate CBTC DARs](/cbtc/get-started/install-and-validate-dars/) * [CBTC authentication](/cbtc/get-started/authentication/) * [Mint CBTC](/cbtc/guides/mint-cbtc/) * [Redeem CBTC](/cbtc/guides/redeem-cbtc/) * [Transfer and receive CBTC](/cbtc/guides/transfer-and-receive-cbtc/) * [CBTC SDK, API, and integration reference](/cbtc/concepts-and-reference/sdk-api-and-integration-reference/) * [CBTC errors, retries, and troubleshooting](/cbtc/concepts-and-reference/errors-retries-and-troubleshooting/) ### Next step → **Build your first workflow:** [Transfer and receive CBTC](/cbtc/guides/transfer-and-receive-cbtc/). --- # Install and validate DARs URL: https://docs.bitsafe.finance/cbtc/get-started/install-and-validate-dars/ [CBTC environments and prerequisites](/cbtc/get-started/environments-and-prerequisites/) ### Outcome Upload the CBTC DAR packages required for minting and redemption to a Canton participant, then confirm that the expected CBTC packages are present. :::note CBTC DAR packages are required for minting and redemption, according to the `bitsafe-token-lib` `v0.5.0` DAR guidance. They are not required for sending or receiving CBTC or for UTXO management. ::: ### Before you start You need: * Administrative access to the target Canton participant. * An approved connection to the participant Admin API. The repository examples use `localhost:5002`; use the endpoint and connection method documented for the target environment. * A participant administrator JWT if the Admin API requires authentication. * `grpcurl`, `jq`, and `base64` for the recommended upload path. * A Rust toolchain for the `check_dars` validation example. * The pinned [`bitsafe-token-lib` `v0.5.0` release](https://github.com/DLC-link/bitsafe-token-lib/releases/tag/v0.5.0). * The current compatibility row for the target Canton version, CBTC DAR release, and environment. :::note Treat administrator tokens as secrets. Retrieve them through the approved secret-management process. Do not commit tokens, add them to documentation, or leave them in a modified copy of the upload script. ::: ### 1. Get the pinned DAR release ```bash git clone https://github.com/DLC-link/bitsafe-token-lib.git cd bitsafe-token-lib git checkout v0.5.0 ``` Confirm that the repository contains `dars/upload_dars.sh`, `dars/dependencies/`, and `dars/cbtc/`. ### 2. Confirm the Admin API connection Establish the approved port-forward or network path to the participant Admin API. If the target differs from the repository default `localhost:5002`, set the `canton_admin_api_url` environment variable: ```bash export canton_admin_api_url="" ``` Do not proceed until the endpoint is confirmed to belong to the intended participant and environment. ### 3. Configure authentication If the Admin API requires authentication, expose the administrator token to the script through the `jwt_token` environment variable: ```bash export jwt_token="" ``` If the Admin API does not require authentication, leave `jwt_token` empty. Follow the authentication flow documented for the target environment. ### 4. Upload the DARs The recommended repository path uses the gRPC upload script. Pass the asset name to the script: ```bash dars/upload_dars.sh cbtc ``` The script uploads: 1. Dependency DARs from `dars/dependencies/`. 2. CBTC DARs from `dars/cbtc/`. For every upload, the script requests package vetting and synchronized vetting. The script stops at the first DAR that fails to upload. Canton skips a DAR that is already present, so the repository guidance describes the script as safe to run again. :::note Verify the upload response itself. Do not treat the script's printed success line as sufficient proof that the Admin API accepted every package. ::: ### 5. Check the installed CBTC DARs The repository includes a Rust example that compares the DARs in `dars/dependencies/` and `dars/cbtc/` with the packages on the participant: ```bash ASSET=cbtc cargo run --example check_dars ``` The example reads `LEDGER_HOST` and the Keycloak values from `.env`. It does not need `ENVIRONMENT` or `PARTY_ID`. The example prints `PASS` when every required package is present. Otherwise, it prints `FAIL`, lists each missing package, and exits with a non-zero code. Record this output with the environment and release tag used for the installation. Remove tokens and other sensitive values before sharing diagnostic output. ### 6. Verify the result A successful installation should meet all of these checks: * [ ] Every expected dependency upload returned an accepted or already-present result. * [ ] Every expected CBTC upload returned an accepted or already-present result. * [ ] `check_dars` reports `PASS` for the CBTC DAR set. * [ ] The recorded package set matches the Engineering-approved release manifest for the target environment. * [ ] A read-only CBTC preflight succeeds before any mint or redemption is attempted. :::note The `check_dars` example is a presence check, not a complete compatibility test. It does not verify application behavior or compatibility with the participant version. Complete the release-specific acceptance test after checking the maintained package manifest. ::: ### Expected result The target participant contains the approved CBTC and dependency DAR set for the selected environment. The `check_dars` result shows every expected package as present, and the environment passes the approved read-only preflight. ### Troubleshooting | Symptom | Check | Next action | | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | | Connection refused or unavailable | Port-forward, host, port, participant identity, and Admin API availability. | Restore the approved Admin API connection. Do not switch environments or ports by trial and error. | | Unauthenticated or permission denied | Whether the Admin API requires a token and whether the token has participant administrator permissions. | Obtain a new token through the approved process. Do not paste the token into a support ticket. | | `check_dars` reports missing packages | Target participant, upload responses, the `ASSET` value, and the ledger connection. | Stop before minting or redemption. Collect redacted logs and escalate with the release tag and environment. | | Some packages appear but the release set is incomplete | Dependency and CBTC upload responses, release manifest, and package vetting status. | Do not mix releases. Reconcile against the approved manifest before retrying. | ### Alternative Canton upload path The repository also includes the Canton console scripts `00_UploadDars.sc` and `00_ValidateDars.sc`. Run them from the `dars` directory with `canton run