Skip to main content
This page explains how the LayerZero V2 protocol runs on Canton. It describes each stage of a message at the concept level. Function signatures and Daml code are not included. What you’ll find:
  • The Virtual Endpoint Rollup (VER) and what the Canton ledger records for each message
  • The send workflow, from the sender’s wallet to the DVNs
  • Verification and the receive workflow, including automatic execution into Canton
  • The role of lzowner and the other LayerZero parties on every message
  • Recovery operations and security considerations
Target audience: developers who know the general LayerZero V2 protocol and want to understand how Canton differs.
PrerequisitesRead Technical Overview first for parties, Daml authorization, and disclosed contracts. For the chain-independent protocol, see the LayerZero protocol overview.

​
The Virtual Endpoint Rollup (VER)

On EVM chains, the LayerZero Endpoint is one contract that every OApp calls. It stores nonces, message hashes, and configuration. Canton’s ledger model works differently. A Daml contract is visible only to its stakeholders, and each update archives the contract and creates a new one. One shared endpoint contract would need every OApp and every sender as a stakeholder, and every message on the network would update that same contract. On Canton, LayerZero runs the endpoint logic in the Virtual Endpoint Rollup (VER). Each endpoint operation starts and ends on the Canton ledger:
  1. The OApp creates a request contract on the ledger for the operation, for example a send or a receive. LayerZero’s lzowner and treasury parties sign the request contract.
  2. LayerZero’s VER sequencer polls the ledger for pending requests. When it finds some, it asks the VER validators to process every request created before a timestamp that it sets. Each validator reads those requests from the ledger and processes them in the order of their ledger timestamps. The VER sequencer is an off-ledger LayerZero service. It is not part of the Canton synchronizer and does not order Canton transactions. The Global Synchronizer’s sequencers, run by the Super Validators, order every Canton transaction, including VER’s requests and commits.
  3. Each VER validator runs the same endpoint logic as on other chains, for example nonce checks, packet construction, the OApp’s endpoint configuration, and the DVN verification check for inbound messages. Each validator signs its result.
  4. When a quorum of VER validators has signed the same result, the sequencer submits it to the Canton ledger as one transaction for the batch. The lzowner party commits the result as an accept or a reject of the request, together with a commitment to VER’s new state. lzowner is a LayerZero protocol party. Its signers are LayerZero Labs, Digital Asset, and Blockdaemon. Every request ends in an accept or a reject. LayerZero’s VER sequencer cannot reorder requests or change results. Only a quorum of VER validators can produce a result that lzowner commits.
  5. The commit creates a pending callback for the OApp. The LayerZero executor settles the pending callback, which runs the OApp’s own Daml code. Before it settles, the OApp’s callback checks that the result comes from lzowner and belongs to this OApp.
The sequencer also answers read-only queries against VER state, such as the fee quote for a send, with the signatures of a quorum of VER validators. Access needs a token from LayerZero Labs. The Value Transfer API reads through the sequencer for you. VER does not change an OApp’s contracts directly. Holdings are locked, burned, created, or unlocked only by the OApp’s own Daml choices. Message verification uses the same configurable DVN model as on other chains. The OApp admin chooses its DVNs and endpoint settings, and controls its peers, enforced options, and rate limits on its own contracts. From the OApp’s point of view, each endpoint operation has three phases:
  1. Request: the OApp creates a request contract.
  2. Accept or reject: the lzowner party accepts or rejects the request on the ledger, based on the VER result.
  3. Settlement: the LayerZero executor settles the pending callback, and the OApp’s code applies the result, for example by completing a send or crediting the receiver. The refund for a rejected send is not settled automatically today (see Step 5).

​
Send Workflow

​
Message Lifecycle Overview

​
Step 1: The Sender’s Wallet Submits the Send

The sender’s wallet submits a command that exercises the OApp’s send choice. The command includes:
  • The sender’s token holdings to spend. The wallet supplies them. For most CIP-0056 tokens, only the holdings’ stakeholders can see them. Canton Coin holdings are an exception: Scan publishes them by owner.
  • Amulet holdings that pay the protocol fee upfront. One or more holdings can pay it. Any part of the fee that is not used is returned later, and it can arrive as a transfer instruction. They must be different holdings from the ones being sent. When the sent token is Canton Coin, the sender needs at least two Amulet holdings. The Splice wallet merges the Amulet holdings of the parties it manages into one about every 30 seconds, so send Canton Coin from an external party.
  • Disclosed contracts for the LayerZero contracts that the send uses. The sender is not a stakeholder of these contracts. LayerZero provides these disclosures as part of an integration.

​
Step 2: A Request Is Created

The send choice moves the amount being sent to the adapter’s custody party (lock/unlock adapter) or burns it (burn/mint adapter), and creates a request contract on the ledger. LayerZero’s lzowner and treasury parties are signatories on the request contract. Their participant nodes confirm this transaction together with the participant nodes of the sender, the OApp admin, and the custody or mint escrow party.

​
Step 3: VER Processes the Request

VER processes the request in Canton ledger order and runs the endpoint logic for it, as on other chains: it assigns the nonce, builds the packet, and applies the OApp’s send configuration. When the VER validators reach a quorum, the lzowner party accepts or rejects the request on the ledger.

​
Step 4: The Packet Goes to the DVNs

When VER commits the accept, it emits the packet. The DVNs in the OApp’s security stack pick up the packet and verify it for the destination chain. They do not wait for the settlement in Step 5.

​
Step 5: The LayerZero Executor Settles the Send

The LayerZero executor settles the pending callback for an accepted send, which completes the send. If the request is rejected, settling its pending callback refunds the sender with a transfer instruction that expires after 24 hours. This refund is available through the protocol, but it is not settled automatically today. If a refund does not arrive, contact the LayerZero team with the Canton update ID of the send. The lock/unlock adapter sends the refund from the custody party. The burn/mint adapter mints the amount again to the mint escrow party, which sends the refund.

​
Verification Workflow

Verification follows the standard LayerZero model. Each DVN in the OApp’s security stack checks the packet independently. The destination chain accepts the message when the required DVNs and the optional DVN threshold have verified it. See Message Security. For the DVNs that verify Canton Coin messages on Canton mainnet, see DVN Providers.

​
Receive Workflow

​
Automatic Execution into Canton

For messages that arrive on Canton, the LayerZero executor delivers the message automatically after verification. The receiver gets a CIP-0056 transfer instruction from the adapter, and must accept it within 24 hours unless it has a transfer preapproval. See Step 4.

​
Step 1: The DVNs Verify the Packet

Each DVN in the OApp’s receive configuration verifies the packet on Canton. Each verification is a request on the Canton ledger that VER processes.

​
Step 2: The Executor Submits the Delivery

When the required DVNs have verified the packet, the LayerZero executor commits the verification in VER. VER accepts the commit only if the path has delivered a message before, or the receiving OApp has marked the path as initializable (see Set the Endpoint Configuration). The executor then submits an lzReceive request on Canton for the delivery.

​
Step 3: VER Accepts or Rejects the Request

The lzReceive request goes through the same VER pipeline as a send. VER checks the message against the verified state, as the endpoint does on other chains, and the request is accepted or rejected. A rejected request moves no tokens on Canton, and the delivery can be submitted again. The request’s minFee is still charged.

​
Step 4: The LayerZero Executor Settles the Receive

The LayerZero executor settles the pending callback, which credits the receiver. The OApp’s callback resolves the receiver party from the 32-byte receiver value in the message. It then credits the receiver: the custody party (lock/unlock adapter) or the mint escrow party (burn/mint adapter) sends the receiver a CIP-0056 transfer instruction. The OApp admin’s participant node confirms this transaction, because the OApp admin is a signatory on the adapter contracts. Canton Coin supports transfer preapprovals. If the receiver has one, the transfer completes in the same transaction. If not, the receiver must accept it within 24 hours. LayerZero does not resend an expired instruction automatically. To have the tokens delivered again, contact the LayerZero team. If the receiver party is not registered, the lzReceive request is still accepted, but the settlement cannot complete. The pending callback stays on the ledger. The LayerZero executor can retry the settlement after the party registers.

​
LayerZero Parties on Every Message

On EVM chains, an OApp calls the endpoint contract directly, and no LayerZero account signs the transaction. On Canton, LayerZero’s protocol parties take part in every send and every receive:
  • They are signatories on the request contracts, so their participant nodes must confirm each message.
  • They act on each request: lzowner accepts or rejects it, the LayerZero executor submits inbound deliveries, and the executor settles the pending callbacks for accepted sends and for receives.
These parties have the role that the endpoint contract and the executor have on other chains. The result for an integration: messages move only while enough of the participant nodes that host LayerZero’s parties and your parties are online to confirm them.

​
Who Does What

Who submits the OApp admin’s operations depends on the integration arrangement. The OApp admin can submit them itself, or LayerZero can submit them for it.

​
Recovery Operations

The standard LayerZero recovery operations exist on Canton: skip, clear, nilify, and burn. On Canton, each one is an endpoint operation. The OApp creates a request, and VER processes it in the same way as a send or a receive. For what each operation does, see Debugging Messages. These operations do not cover every failure:
  • Rejected receive. If VER rejects a delivery request, no tokens move on Canton, although the request’s minFee is still charged. The message stays verified and undelivered, and it can be delivered by a new request. The OApp’s reject callback does nothing for a receive. If a delivery does not complete, contact the LayerZero team with the source transaction hash.
  • Expired transfer instruction. If a receiver does not accept an adapter’s transfer instruction within 24 hours, it expires and the tokens return to the custody or mint escrow party. LayerZero does not resend an expired instruction automatically. To have the tokens delivered again, contact the LayerZero team.
  • Delivery accepted, settlement pending. When the receiver is not registered or an inbound rate limit is reached, the lzReceive request is still accepted. LayerZero Scan can show the message as delivered while the settlement is pending. Skip, clear, nilify, and burn do not apply to this state. The LayerZero executor can retry the settlement after the receiver registers or the rate limit’s capacity recovers (see Send from Another Chain to Canton).
  • Malformed message. If the message payload is malformed, for example to is not a party fingerprint, the settlement never completes. Registering a party does not fix it. Contact the LayerZero team with the source transaction hash.
For Canton Coin, see Canton Coin Troubleshooting.

​
Security Considerations

​
Validator Quorum

LayerZero’s VER sequencer submits a result to the ledger only after a quorum of VER validators has signed it. On the ledger, lzowner commits the result (see The Virtual Endpoint Rollup).

​
Results Recorded on the Ledger

Every request, accept, reject, and settlement is a transaction on the Canton ledger. The OApp’s callback checks each result before it settles, and only the OApp’s own Daml choices change its holdings and configuration.

​
Confirmation on Every Message

Canton requires the participant nodes of the involved signatories to confirm each transaction. Every message needs confirmation from LayerZero’s participant nodes and from the participant nodes of the OApp admin and the custody or mint escrow party. This protects each party’s contracts.

​
Package Vetting

A participant node runs only the Daml packages that it has vetted. Your participant node, and the participant nodes of your users’ wallets, must vet the LayerZero packages and each upgraded version of them.

​
Rate Limits

An OApp can set rate limits on its token flows. The OApp admin controls these limits directly.

​
Get Help

LayerZero on Canton is not yet open for self-service integrations. To discuss integrating, contact the LayerZero team.

​
Next Steps