> For the complete documentation index, see [llms.txt](https://docs.bitsafe.finance/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bitsafe.finance/cbtc/concepts-and-reference/token-standard-and-contract-model.md).

# 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.

{% hint style="info" %}
**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.
{% endhint %}

### 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](/cbtc/get-started/environments-and-prerequisites.md)
* [Mint CBTC](/cbtc/guides/mint-cbtc.md)
* [Redeem CBTC](/cbtc/guides/redeem-cbtc.md)
* [Transfer and receive CBTC](/cbtc/guides/transfer-and-receive-cbtc.md)
* [CBTC developer Quick Start](/cbtc/get-started/developer-quick-start.md)

### Technical sources

* [`DLC-link/cbtc-lib` `v0.6.4` README](https://github.com/DLC-link/cbtc-lib/blob/v0.6.4/README.md)
* [`src/transfer.rs` at `v0.6.4`](https://github.com/DLC-link/cbtc-lib/blob/v0.6.4/src/transfer.rs)
* [`src/mint_redeem/mint.rs` at `v0.6.4`](https://github.com/DLC-link/cbtc-lib/blob/v0.6.4/src/mint_redeem/mint.rs)
* [`src/mint_redeem/redeem.rs` at `v0.6.4`](https://github.com/DLC-link/cbtc-lib/blob/v0.6.4/src/mint_redeem/redeem.rs)
* [`src/mint_redeem/attestor.rs` at `v0.6.4`](https://github.com/DLC-link/cbtc-lib/blob/v0.6.4/src/mint_redeem/attestor.rs)

### Related pages

* [Mint CBTC](/cbtc/guides/mint-cbtc.md)
* [Redeem CBTC](/cbtc/guides/redeem-cbtc.md)
* [Transfer and receive CBTC](/cbtc/guides/transfer-and-receive-cbtc.md)
* [CBTC authentication](/cbtc/get-started/authentication.md)
* [CBTC SDK, API, and integration reference](/cbtc/concepts-and-reference/sdk-api-and-integration-reference.md)

### Next step

👉 **Implement the model:** [CBTC SDK, API, and integration reference](/cbtc/concepts-and-reference/sdk-api-and-integration-reference.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.bitsafe.finance/cbtc/concepts-and-reference/token-standard-and-contract-model.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.