> 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/beth/concepts-and-reference/token-standard-and-contract-model.md).

# Token standard and contract model

### Purpose

Use this page to understand how BETH represents tokens and workflows on Canton Network, which contracts participate in transfers and Ethereum 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 `bitsafe-token-lib` `v0.2.0` release interacts with the Canton Token Standard V1 interfaces (CIP-0056) and V2 interfaces (CIP-0112). Eight operations have a V2 form in a `v2` submodule, such as `bitsafe_token::transfer::v2::submit`. The library uses token-standard holdings and transfer instructions for ordinary BETH movement, while BETH-specific account contracts coordinate mint and redemption workflows.

The observed instrument identifier has two parts:

* **Administrator:** the BETH registrar party for the selected environment.
* **Instrument name:** `BETH`.

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:** `bitsafe-token-lib` `v0.2.0` has Token Standard V2 (CIP-0112) entry points for eight operations. The eight V2 operations are available on Mainnet. Allocation remains V1-only. 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`, `Credential` (Minter role), `BurnMintFactory` | Represents BETH holdings, creates and resolves transfer instructions, identifies the instrument, and supplies governed mint or burn primitives.            |
| BETH bridge layer          | `BETHDepositAccountRules`, `BETHDepositAccount`, `BETHWithdrawAccountRules`, `BETHWithdrawAccount`, `BETHWithdrawRequest`     | Coordinates deposit account IDs, withdrawal destinations, pending redemption balances, and the asynchronous handoff between Canton and Ethereum workflows. |
| Registry and service layer | Registry choice contexts, disclosed contracts, BETH account-rule responses and token-standard contract responses              | Returns the contracts and context an authenticated client needs to exercise the intended ledger choice.                                                    |

### Holdings

A BETH 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 BETH 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 BETH 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 one of two results. The registry creates a transfer-instruction contract, or it settles the transfer and creates the receiver’s holdings.
5. The receiver resolves an instruction through the supported acceptance flow. A settled transfer has no instruction to resolve.
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 BETH-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 `BETHDepositAccountRules_CreateDepositAccount` with the intended owner and required credentials.
3. The ledger creates a `BETHDepositAccount` contract.
4. The client passes the deposit account ID to `depositETH` on the Ethereum bridge contract.
5. Ethereum deposit verification occurs outside `bitsafe-token-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, queries its status, and builds the `depositETH` call. It does not send or monitor Ethereum transactions itself. Use the current operational reference for required credentials, Ethereum finality, completion states, timing, and recovery behavior.

{% hint style="warning" %}
Use the `id` of the `BETHDepositAccount` as the `depositAccountId` parameter of the `depositETH` call. Use the contract ID only if the account has no `id` yet. A deposit with the wrong `depositAccountId` does not mint BETH, and the ETH can become stuck in the bridge.
{% endhint %}

### 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 `BETHWithdrawAccountRules_CreateWithdrawAccount` with the intended owner, Ethereum destination address, and required credentials.
3. The ledger creates a `BETHWithdrawAccount` contract.
4. The client selects eligible BETH holdings and exercises `BETHWithdrawAccount_Withdraw` with the owner's Minter credential.
5. The withdrawal choice checks the owner's Minter credential and the selected holdings. It then exercises `BurnMintFactory_BurnMint`, which burns the selected holdings and returns any change to the owner.
6. The updated withdrawal account records a pending balance.
7. The Attestor Network later creates a `BETHWithdrawRequest` and processes the Ethereum redemption.

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

Redemption also uses a namespaced `ExtraArgs` context. The library supplies the instrument configuration contract and a withdrawal reason. The issuer-credentials list is empty, because BETH needs no issuer credential. 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 BETH 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.
* BETH DAR packages.
* Digital Asset Registry Utility packages.
* `bitsafe-token-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                                            | Ethereum deposit or redemption completion                                                       |
| Digital Asset Registry Utility | Token-standard factories, choice context, instrument configuration, and related disclosures used by the observed V1 and V2 flows | BETH-specific Ethereum bridge completion                                                        |
| BETH account contracts         | Deposit and withdrawal account state, owner and registrar roles, pending balances, and bridge request records                    | Ethereum finality without external verification                                                 |
| BitSafe API                    | Current account rules and token-standard contracts used by the reviewed client                                                   | Authorization to bypass ledger choices or governance                                            |
| Attestor Network               | Independent verification and threshold-governed Ethereum 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.
* Ethereum transaction hash 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

* [BETH environments and prerequisites](/beth/get-started/environments-and-prerequisites.md)
* [Mint BETH](/beth/guides/mint-beth.md)
* [Redeem BETH](/beth/guides/redeem-beth.md)
* [Transfer and receive BETH](/beth/guides/transfer-and-receive-beth.md)
* [BETH developer Quick Start](/beth/get-started/developer-quick-start.md)

### Technical sources

* [`DLC-link/bitsafe-token-lib` `v0.2.0` README](https://github.com/DLC-link/bitsafe-token-lib/blob/v0.2.0/README.md)
* [`canton-lib` `crates/token/src/transfer.rs` at `v0.11.0`](https://github.com/DLC-link/canton-lib/blob/v0.11.0/crates/token/src/transfer.rs)
* [`src/flows/canton_bridge_v1/deposit.rs` at `v0.2.0`](https://github.com/DLC-link/bitsafe-token-lib/blob/v0.2.0/src/flows/canton_bridge_v1/deposit.rs)
* [`src/flows/canton_bridge_v1/withdraw.rs` at `v0.2.0`](https://github.com/DLC-link/bitsafe-token-lib/blob/v0.2.0/src/flows/canton_bridge_v1/withdraw.rs)
* [`src/kits/evm/evm_asset_bridge.rs` at `v0.2.0`](https://github.com/DLC-link/bitsafe-token-lib/blob/v0.2.0/src/kits/evm/evm_asset_bridge.rs)
* [`beth::mint::deposit_call` at `v0.2.0`](https://github.com/DLC-link/bitsafe-token-lib/blob/v0.2.0/src/tokens/beth/mod.rs#L209-L255)

### Related pages

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

### Next step

👉 **Implement the model:** [BETH SDK, API, and integration reference](/beth/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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.