Mint CBTC

CBTC overview · CBTC environments and prerequisites

Outcome

Create a CBTC deposit account, obtain its Bitcoin address, deposit Bitcoin, and verify that the corresponding CBTC becomes available to the intended Canton party.

Before you start

• Complete the CBTC environment preflight.
• Use a supported Canton participant and authenticated party.
• Install and validate the CBTC DAR packages required for minting.
• Confirm that the party has the required Minter credential.
• Configure the approved BitSafe API for the selected environment.
• Use a pinned cbtc-lib release and compatible shared Canton libraries.
• Confirm the approved Bitcoin network and test-asset source.

Minting has additional prerequisites beyond ordinary CBTC transfers. Do not begin from the Send CBTC 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 approved BitSafe service. 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. Obtain the Bitcoin deposit address

Request the Bitcoin address associated with the deposit account through the approved BitSafe API.

Before sending Bitcoin:

• Confirm the Bitcoin network.
• Confirm the address belongs to the expected deposit account.
• Confirm the address format is valid for that network.
• Confirm whether addresses are reusable or single-purpose.
• Record the account and address association in the integration’s reconciliation data.

5. Deposit Bitcoin

Send the approved test amount to the verified address. Use the transaction identifier to monitor Bitcoin confirmation state.

Check the current environment and compatibility reference for confirmation depth, minimum amount, address-reuse policy, fees, timing, and timeout behavior. Do not rely on historical values.

6. Monitor the mint lifecycle

Track the deposit account and CBTC state until the approved completion condition is met. Monitor:

• Bitcoin deposit detected.
• Required confirmation state reached.
• Verification or attestation state.
• Mint submitted on Canton.
• CBTC 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 CBTC balance or holdings increase by the expected amount.

Reconcile the Bitcoin transaction, deposit account, mint result, Canton update, and resulting holdings without exposing secrets.

Source example

The repository includes a guided example:

cargo run --example credentials
cargo run --example mint_cbtc_flow

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.
Bitcoin deposit is not detected	Network, address, transaction identifier, and confirmation state	Do not send a second deposit until the first transaction is reconciled.
Bitcoin confirms but CBTC is absent	Verification state, mint status, Canton update, and target party	Escalate with sanitized account, transaction, and update identifiers.

Technical sources

• Mint flow example
• Credential example
• Examples guide
• CBTC DAR guidance

Related pages

• Install and validate CBTC DARs
• CBTC authentication
• CBTC errors, retries, and troubleshooting
• CBTC compatibility and release notes

Next step

👉 Prepare for failures safely: CBTC errors, retries, and troubleshooting.