Token standard and contract model

Purpose

Use this page to understand how CBTC represents tokens and workflows on Canton Network, which contracts participate in transfers and Bitcoin 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 cbtc-lib v0.6.4 release interacts with the Canton Token Standard V1 interfaces associated with CIP-0056. The library uses token-standard holdings and transfer instructions for ordinary CBTC movement, while CBTC-specific account contracts coordinate mint and redemption workflows.

The observed instrument identifier has two parts:

• Administrator: the CBTC registrar party for the selected environment.
• Instrument name: CBTC.

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.

Version boundary: this page does not claim that CBTC supports CIP-112 or Token Standard V2 in production. 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, IssuerCredential, BurnMintFactory	Represents CBTC holdings, creates and resolves transfer instructions, identifies the instrument, and supplies governed mint or burn primitives.
CBTC bridge layer	CBTCDepositAccountRules, CBTCDepositAccount, CBTCWithdrawAccountRules, CBTCWithdrawAccount, CBTCWithdrawRequest	Coordinates Bitcoin deposit addresses, withdrawal destinations, pending redemption balances, and the asynchronous handoff between Canton and Bitcoin workflows.
Registry and service layer	Registry choice contexts, disclosed contracts, CBTC account-rule responses, Bitcoin-address responses, and token-standard contract responses	Returns the contracts and context an authenticated client needs to exercise the intended ledger choice.

Holdings

A CBTC 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 CBTC 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 CBTC 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 a transfer-instruction contract.
5. The receiver resolves the instruction through the supported acceptance flow.
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 CBTC-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 CBTCDepositAccountRules_CreateDepositAccount with the intended owner and required credentials.
3. The ledger creates a CBTCDepositAccount contract.
4. The client uses the account identifier to obtain the associated Bitcoin deposit address.
5. Bitcoin verification occurs outside cbtc-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 and queries its status. It does not monitor Bitcoin transactions itself. Use the current operational reference for required credentials, confirmation depth, completion states, timing, and recovery behavior.

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 CBTCWithdrawAccountRules_CreateWithdrawAccount with the intended owner, Bitcoin destination address, and required credentials.
3. The ledger creates a CBTCWithdrawAccount contract.
4. The client selects eligible CBTC holdings and exercises CBTCWithdrawAccount_Withdraw.
5. The withdrawal choice uses the current BurnMintFactory, InstrumentConfiguration, and IssuerCredential disclosures to consume the selected holdings and create change when required.
6. The updated withdrawal account records a pending balance.
7. The Attestor Network later creates a CBTCWithdrawRequest and processes the Bitcoin payout.

The withdrawal request is not created atomically with the initial ledger submission. Integrations must monitor the asynchronous request and verify Bitcoin 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.

Mint and redemption also use a namespaced ExtraArgs context. In the reviewed release, the context supplies the instrument configuration and issuer credential contracts, plus standardized metadata such as an operation reason. 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 CBTC 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.
• CBTC DAR packages.
• Digital Asset Registry Utility packages.
• cbtc-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	Bitcoin deposit or payout completion
Digital Asset Registry Utility	Token-standard factories, choice context, instrument configuration, and related disclosures used by the observed V1 flow	CBTC-specific Bitcoin bridge completion
CBTC account contracts	Deposit and withdrawal account state, owner and registrar roles, pending balances, and bridge request records	Bitcoin-chain finality without external verification
BitSafe API	Current account rules, Bitcoin addresses, and token-standard contracts used by the reviewed client	Authorization to bypass ledger choices or governance
Attestor Network	Independent verification and threshold-governed Bitcoin 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.
• Bitcoin transaction identifier 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

• CBTC environments and prerequisites
• Mint CBTC
• Redeem CBTC
• Transfer and receive CBTC
• CBTC developer Quick Start

Technical sources

• DLC-link/cbtc-lib v0.6.4 README
• src/transfer.rs at v0.6.4
• src/mint_redeem/mint.rs at v0.6.4
• src/mint_redeem/redeem.rs at v0.6.4
• src/mint_redeem/attestor.rs at v0.6.4

Related pages

• Mint CBTC
• Redeem CBTC
• Transfer and receive CBTC
• CBTC authentication
• CBTC SDK, API, and integration reference

Next step

👉 Implement the model: CBTC SDK, API, and integration reference.