> ## Documentation Index
> Fetch the complete documentation index at: https://docs.layerzero.network/llms.txt
> Use this file to discover all available pages before exploring further.

# Canton Coin Bridging for Wallet Operators

> What a Canton wallet must support so users can bridge Canton Coin: package vetting on every co-host, CIP-0103 signing, upgrades, registration, preapprovals.

> [!NOTE]
>
> Available when Canton Coin launches on Stargate and the Value Transfer API.
>
> Canton Coin on BSC, HyperEVM, and Solana is bridged CC: an OFT that LayerZero Labs deployed and administers. It is minted when native CC is locked on Canton through the LayerZero CC adapter. On HyperCore, `LZCC` is a spot token linked to the HyperEVM OFT through the Hyperliquid asset bridge. The Global Synchronizer Foundation, Digital Asset, and the Canton Network did not deploy bridged CC and do not administer its contracts. See [Canton Coin Across Chains](https://docs.layerzero.network/v2/developers/canton/canton-coin/overview.md).

A Canton wallet's users can bridge Canton Coin (CC) only if the wallet's nodes run the LayerZero packages and the wallet can sign the transactions that the [Value Transfer API](https://docs.layerzero.network/v2/developers/canton/canton-coin/value-transfer-api.md) builds. This page lists what the wallet operator must set up.

> [!WARNING]
>
> **Your users must send CC into Canton through Stargate or the Value Transfer API.** Both check that the receiving Canton party is registered before they build a send. An OFT `send()` built by hand on BSC, HyperEVM, or Solana does not. If a user's party is not registered, including because a node that hosts it has not vetted the LayerZero DAR packages, CC sent to that party from another chain will be stuck. Do not construct hand-built OFT sends into Canton in your wallet, and do not direct users to send that way. Recovery needs action by the node operator or by LayerZero, is not practical for the user, and LayerZero does not guarantee it. See [Send from Another Chain to Canton](https://docs.layerzero.network/v2/developers/canton/oft/overview.md#send-from-another-chain-to-canton) and the [pre-send checklist](https://docs.layerzero.network/v2/developers/canton/oft/overview.md#pre-send-checklist).

## Package Vetting

The LayerZero Canton packages are private DAR files. To get access, [contact the LayerZero team](https://layerzeronetwork.typeform.com/to/U9hMgxf1) with the GitHub handles of your operators.

Upload and vet the full set in [LayerZero Packages](https://docs.layerzero.network/v2/developers/canton/technical-overview.md#layerzero-packages) on each participant node that hosts your users' parties. If a party is hosted on more than one node, vet the packages on every co-host. If a hosting node has not vetted `layerzero-ioapp` (send) or `layerzero-iregistry` (registration), the Value Transfer API returns the `CantonPackagesNotVetted` error (see [Errors](https://docs.layerzero.network/v2/developers/canton/canton-coin/value-transfer-api.md#errors)). The API does not check the other packages. If one of them is missing, the transaction fails when it is submitted.

## Package Upgrades

The Value Transfer API picks the package version when it builds a transaction: the version that both LayerZero's node and the user's node have vetted. It puts that package ID in the command. When LayerZero releases a new version, upload and vet it on every node that hosts your users. Do not unvet an older version while transactions built against it may still be signed.

## Signing (CIP-0103)

For each transfer or registration, the Value Transfer API returns a CIP-0103 `prepareExecute` request. Your wallet must:

1. Accept a request with one command that exercises a LayerZero choice (`OApp_LzSend` or `SetPartyId`).
2. Pass through the command, `disclosedContracts`, `actAs`, and `readAs` fields unchanged.
3. Use the `commandId` in the request if it has one. Stargate sets one and matches completion events on it. If the request has none, set your own unique `commandId`. Keep the same `commandId` if you resubmit the same send. `synchronizerId` is optional: set it to the Global Synchronizer ID, or leave it unset and the node picks a synchronizer that it is connected to.
4. Show the transaction to the user. For `OApp_LzSend`, show the amount, the destination chain, the receiver, and the CC fee. For `SetPartyId`, show "Register for LayerZero transfers into Canton" and the fee.
5. Sign the transaction and execute it on the user's validator.

Execute the request within a few minutes of the build. The LayerZero contracts reject it once ledger time is more than 10 minutes past the build timestamp. Your wallet does not need its own idempotency checks. For retries and tracking, see [Submit on Canton](https://docs.layerzero.network/v2/developers/canton/canton-coin/value-transfer-api.md#submit-on-canton).

### Connect to Stargate

Stargate connects Canton wallet extensions through CIP-0103 extension discovery (`@canton-network/dapp-sdk`), and Loop through Loop's own SDK. WalletConnect is not supported at launch. Your wallet must:

1. Announce itself as a CIP-0103 extension.
2. Report the network as `mainnet` (`main` and `canton:mainnet` are also accepted). Other networks fail with "wallet does not support chain".
3. Answer `ledgerApi` calls for `GET /v2/state/ledger-end` and `POST /v2/state/active-contracts` for the connected party. Stargate reads holdings and balances this way.
4. Emit `txChanged` for the request's `commandId`, with `status: executed` and `payload.updateId`, or with `status: failed`. Stargate waits 120 seconds, including the time the user takes to approve.

## Registration

A party must register once in the CC adapter's registry before anyone can bridge CC into Canton for it. Registration is a Canton transaction: the party signs `SetPartyId` in its own Canton wallet and pays the fee in CC from its own holdings on Canton. The Value Transfer API prepares this transaction through `POST /v1/register-canton-party`. Through Stargate, Stargate prepares the registration, and your wallet only signs it. To offer registration inside your wallet, call `POST /v1/register-canton-party` with your own Value Transfer API key. Neither Stargate nor the Value Transfer API can register a party from BSC, HyperEVM, or Solana, and no flow registers a party automatically from another chain.

* Prompt the user to register on Canton before the first transfer into Canton.
* Make sure the user holds enough CC on Canton for the registration fee. A user whose CC is only on BSC, HyperEVM, or Solana must first get CC into their Canton wallet.
* Partners that send CC to your users from other chains with their own tooling must check every item in the [pre-send checklist](https://docs.layerzero.network/v2/developers/canton/oft/overview.md#pre-send-checklist) first.

> [!WARNING]
>
> **Shared namespace.** By default, Canton hosts local parties under the validator's namespace, so they share one fingerprint. The registry stores only the fingerprint. If two parties in one namespace register, the last one receives every inbound transfer for both. The Value Transfer API refuses this second registration (the `CantonNamespaceTaken` error). If your users are local parties on a shared validator, only one of them can receive CC from other chains. External parties created with their own key have their own namespace. Do not create several receiving parties under one key.

## One-step Transfers (Preapproval)

Inbound CC arrives in one of two ways:

| Receiver has | What happens |
| - | - |
| A CC transfer preapproval | The CC arrives in the user's wallet directly. |
| No preapproval | The CC arrives as a CIP-0056 transfer instruction (Splice `AmuletTransferInstruction`). Wallets such as Loop show it as an incoming offer. The user must accept it within 24 hours. Accepting is a Canton transaction, so the user's validator pays traffic for it. Refunds of rejected sends and unused fee change from a send also arrive this way. |

If the user rejects the instruction or lets it expire, the CC goes back to the LayerZero CC adapter. LayerZero does not resend an expired instruction automatically. To have the tokens delivered again, [contact the LayerZero team](https://layerzeronetwork.typeform.com/to/U9hMgxf1). The same applies to a rejected instruction. Show the sender as LayerZero, and warn the user before a reject.

Create a Splice [`TransferPreapproval`](https://docs.dev.sync.global/background/preapprovals.html) for each user. A preapproval costs CC and expires, so renew it before expiry, as Loop does with its One-step Transfers setting.

## Holdings

A send from Canton pays the amount and the fee from different holdings, so a user needs at least two. One or more holdings pay the fee, and the holdings that are left must cover the amount. The Value Transfer API picks the fee holdings first: one holding, then a pair, then larger groups. It does not try every combination, so in rare cases it returns the `CantonHoldingsNotSplit` error although a split exists. If a user's CC is all in one holding that covers the amount and the fee, the API returns the `CantonHoldingsNotSplit` error (see [Errors](https://docs.layerzero.network/v2/developers/canton/canton-coin/value-transfer-api.md#errors)). If that holding does not cover both, it returns HTTP 400 insufficient balance.

If your users are wallet users on a Splice validator, the Splice wallet automatically merges their Amulet holdings into one about every 30 seconds. A split made by a self-transfer does not last, and a merge between build and submit archives the holdings in the built transaction. Host bridging users as external parties, or as parties that the Splice wallet automation does not manage. For those parties, a transfer to yourself leaves the amount plus a separate change holding. Build and submit immediately after you read the holdings.

The Value Transfer API does not look up your users' holdings. Your wallet passes them, at most 200 per request. A send can use at most 100 holdings, so merge many small holdings.

## Bridged CC Balances

If your wallet also shows BSC, Solana, HyperEVM, or HyperCore balances, label CC there as bridged CC administered by LayerZero Labs. Check the address against the [token table](https://docs.layerzero.network/v2/developers/canton/canton-coin/overview.md#token-identifiers), and keep it separate from the native CC balance.

## Support Your Users

For transfers that do not arrive, see [Canton Coin Troubleshooting](https://docs.layerzero.network/v2/developers/canton/canton-coin/troubleshooting.md). Before you contact LayerZero, collect the user's Canton party ID, the Canton update ID or the source transaction hash, the `quoteId` if you used the API, and the time of the transfer.