Redeem CBTC

CBTC overview · CBTC environments and prerequisites

Outcome

Create or select a withdrawal account, redeem CBTC, and verify delivery of Bitcoin to the intended address.

Before you start

• Complete the CBTC environment preflight.
• Confirm the party holds enough CBTC for the intended test.
• Install and validate the DAR packages required for redemption.
• Confirm the required Minter credential.
• Configure the approved BitSafe API.
• Obtain a valid Bitcoin destination for the selected network.
• Understand the approved minimums, limits, fees, and recovery path.

1. Validate the Bitcoin destination

Before creating a withdrawal account:

• Confirm the destination address format and Bitcoin network.
• Confirm ownership or authorization under the organization’s controls.
• Check whether the address can be changed after account creation.
• Use a second-person or system control for production destinations where required.

A wrong-network or wrong-recipient destination may be irreversible.

2. Retrieve current withdrawal rules

Retrieve the current account rules from the approved BitSafe service. 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 Bitcoin destination. If reusing an existing account, confirm its destination and current status before selecting it.

The source integration test notes that created deposit and withdrawal accounts persist. Do not create duplicate accounts as an automatic retry strategy.

4. Select CBTC holdings

Query current CBTC 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 CBTC interface. Use a unique request or command identifier where available and retain the resulting Canton update or contract identifiers securely.

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.
• CBTC burned or otherwise consumed by the approved contract flow.
• Withdrawal account pending balance updated.
• Bitcoin transaction created or broadcast.
• Required Bitcoin confirmation state reached.
• Completed, failed, cancelled, or escalated.

7. Verify and reconcile

A successful redemption should show:

1. The intended CBTC amount no longer appears in the party’s available holdings.
2. The withdrawal account reflects the approved state transition.
3. Bitcoin is delivered to the verified destination.
4. The Canton and Bitcoin records reconcile to one redemption request.

Source example

cargo run --example credentials
cargo run --example redeem_cbtc_flow

A separate burn test exists for controlled development use. Do not use it as a production redemption path.

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.
Submission times out	Canton update status and withdrawal-account state	Determine commitment before retrying.
CBTC decreases but Bitcoin is pending	Withdrawal state, Bitcoin transaction status, and service health	Follow the approved pending-withdrawal escalation path.
Bitcoin arrives with an unexpected amount	Requested amount, approved fees, transaction output, and reconciliation record	Escalate; do not make an offsetting transaction automatically.

Technical sources

• Redeem flow example
• Withdrawal-request query
• Examples guide

Related pages

• Install and validate CBTC DARs
• CBTC authentication
• CBTC batch transfers and UTXO management
• CBTC errors, retries, and troubleshooting
• CBTC compatibility and release notes

Next step

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