Environments and prerequisites

CBTC overview

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 cbtc-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:

• cbtc package version 0.6.4.
• canton-lib dependencies pinned to v0.6.1.
• A Canton API client generated from Canton 3.6.0 specifications.

For deployment, use the approved compatibility matrix for the CBTC 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: Decentralized Party and registry selection for the target environment.
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

• cbtc-lib v0.6.4
• cbtc-lib environment example
• CBTC DAR guidance
• canton-lib v0.6.1

Related pages

• CBTC developer Quick Start
• Install and validate CBTC DARs
• CBTC authentication
• Mint CBTC
• Redeem CBTC
• Transfer and receive CBTC
• CBTC compatibility and release notes

Next step

👉 Verify your setup: CBTC developer Quick Start.