Layerzero
Layerzero OFT carries fungible value from source debit to destination credit
Layerzero OFT turns a source-chain token debit into a destination-chain credit through a standardized crosschain message. A direct OFT normally burns on the source and mints at the destination, while an adapter can lock, burn, unlock or mint according to its design. Before a first transfer, confirm that the deployments are trusted peers and that the quoted receivable amount meets the sender's minimum. Completion is the destination credit, not a successful source transaction alone.
Confirm the pathway before committing tokens
A transfer is ready only when the source deployment and receiving deployment recognize each other for that direction. The destination endpoint ID, recipient encoding, send and receive libraries, verification settings and execution options must describe the intended path. The sender also needs the token balance, any allowance required by an adapter and enough funds to cover the quoted native fee and any quoted LZ-token fee. If one of those inputs is wrong, stop before signing; no token debit has occurred.
Start with a read-only quote.
quoteOFT
applies the amount logic without moving tokens and reports the amounts that would be sent and received.
quoteSend
estimates the messaging fee for the same send parameters. Compare those outputs with the intended recipient, route and minimum amount. A mismatched amount or pathway calls for a corrected request. A matching quote makes the request ready to sign only after the pathway, balance and allowance checks above also pass.
Seven stages connect debit to credit
The transfer progresses through distinct token and message states. The stages expose different evidence and conditions, while the final column tracks the value state or control of the next action.
| Stage | Evidence or condition | Value or control position |
|---|---|---|
| 1. Pre-send quote |
quoteOFT
reports amount fields and
quoteSend
reports the message fee.
|
The sender retains the tokens because these view calls write no state. |
| 2. Amount normalization |
The transferable local amount is floored to shared precision and checked against
minAmountLD.
|
Contract arithmetic fixes the encodable amount before any debit persists. |
| 3. Source debit |
The source balance falls within the successful
send
transaction.
|
A direct OFT burns value; an adapter locks or burns it according to its implementation. |
| 4. Message encoding | The recipient and shared-decimal amount are encoded in the OFT message. | No spendable token exists inside the message; the source debit already represents the value change. |
| 5. Message dispatch |
The messaging receipt records a GUID, nonce and fee, while
OFTSent
records the amount.
|
The source debit is committed and the configured messaging pathway controls progress. |
| 6. Verification and delivery | The payload satisfies the configured DVN rule and reaches the trusted receiving deployment. | DVNs attest to the message and an Executor submits the destination call. |
| 7. Destination credit |
OFTReceived
and the recipient's destination balance show the credited amount.
|
The destination OFT mints or unlocks value, after which the recipient controls the credited tokens. |
In the default direct EVM implementation, source debit burns the transferable amount and destination credit mints that amount to the recipient. An adapter changes where tokens are held and which contract has mint or burn authority, while the debit-credit relationship still protects the global supply accounting.
Source and destination effects occur in separate transactions. A successful source receipt proves that the debit and message dispatch occurred, but it doesn't prove that the recipient can spend the destination balance. The GUID ties the dispatch to later evidence. Waiting on that record is different from submitting another transfer, which would create a second debit and a second message.
Shared decimals set the crosschain precision
The amount carried in an OFT message uses a common precision that every connected deployment can represent. Local token decimals can differ between chains, so raw local units can't safely travel unchanged.
Normalization happens before message encoding
The source converts the requested local amount into shared units. The destination reverses that conversion into its own local units, keeping the human-readable value aligned across different token representations.
Local units become shared units
The conversion rate is
10^(localDecimals - sharedDecimals), and the local precision must be at least the shared precision in the vanilla EVM contract.
The vanilla EVM OFT implementation uses six shared decimals and encodes the shared-unit amount as an unsigned 64-bit integer.
A custom shared precision must also fit the supply and each destination's local numeric type.
The dust floor protects the conversion
Before debit, the base logic floors
amountLD
to a multiple of the conversion rate. The remainder stays outside the crosschain transfer instead of being encoded and lost through integer division. The quoted
amountSentLD
and
amountReceivedLD
expose the transferable amount. If that amount falls below
minAmountLD, the call reverts before a successful debit and message dispatch can persist.
Direct OFT and adapter designs place control differently
The same debit-credit interface can sit inside the token or in a separate adapter. That choice determines where custody, mint authority and upgrade or administrative power reside.
Integrated burn and mint
A direct EVM OFT combines ERC-20 behavior with crosschain send and receive logic. Its normal debit burns the sender's tokens, then the paired destination contract mints the credited amount. Because the OFT is the token contract, its standard implementation doesn't require a separate token allowance for
send. The design needs compatible deployments on each connected chain and controlled minting through authenticated peer messages.
Adapters for an existing token
A base OFTAdapter leaves the original token contract unchanged. On its home chain, the adapter uses
transferFrom
to lock tokens during debit and releases held tokens during the corresponding credit. Remote OFT deployments can mint against that locked supply, while a return transfer burns the remote representation before the home adapter unlocks the original asset.
A mint-and-burn adapter is another pattern when the existing token exposes suitable mint and burn permissions. The trade-off shifts from escrow custody to privileged supply operations. An adapter also adds a contract boundary and, in the lockbox pattern, an allowance step. The direct pattern has fewer moving contracts but places token and crosschain logic together. Use one OFTAdapter for the token mesh when relying on the default lockbox pattern. Multiple adapters create separate pools, so the source can't know whether the destination adapter holds enough tokens to unlock. A non-default design must address that accounting risk. Neither structure removes the need for peer authentication and pathway configuration.
Amount quotes and messaging fees answer different questions
quoteOFT
describes token accounting: the amount debited, the amount expected to be credited and any fee detail supplied by a customized implementation.
quoteSend
prices message verification and destination execution for the selected parameters. The
send
call uses both kinds of information, returning a messaging receipt and an OFT receipt. The messaging fee is separate from the transferred token amount unless customized debit logic also deducts a token fee.
A messaging-fee quote should be refreshed near the send because verification and execution costs can change. A stale native-fee value can make the transaction revert even when the token amount remains valid. Refresh the fee quote without changing the destination, recipient or token amount.
Customized debit logic may deduct a token fee, enforce a route limit or apply permissions. When the custom logic changes the token amount,
amountSentLD
and
amountReceivedLD
can differ. The sender's
minAmountLD
sets the lowest acceptable destination amount. If the current amount quote no longer meets that floor, fix the amount before signing to avoid creating an onchain transfer.
Recovery starts from the last confirmed token state
Before commitment, compare the expected destination, recipient and receivable amount with the transaction request and quote. If one of those values differs, correct that request input and quote again. This is the only stage where abandoning the attempt leaves no source debit or message to reconcile.
If the source transaction reverts, its token debit and message dispatch don't persist. Correct the stated cause, obtain a fresh quote and retry only when the request now matches the intended state. Once a successful receipt contains the OFT message record, don't submit a replacement merely because the destination is still pending. Follow the original GUID and locate whether verification, delivery or destination execution remains incomplete.
At the destination, compare the expected credit with
OFTReceived
and the recipient's actual balance. Correct the failed receive condition, then retry the same message through an available delivery path. If the token credit succeeded but a separate composed action failed, recovery belongs to the compose execution rather than the token debit. The transfer is complete when the intended destination balance is available to the recipient.
Layerzero OFT FAQ
Can a composed action fail after the destination credits tokens?
Yes. In a composed transfer, lzReceive credits the OFT and queues the compose payload, while lzCompose runs the follow-on contract logic separately. If the second execution lacks gas or reverts, the token credit may already be complete even though the requested action isn't. Recovery should target the failed compose execution and the same GUID, not send another token transfer.
Why are fee-on-transfer tokens incompatible with default adapter accounting?
A transfer fee makes the adapter's balance increase smaller than the amount requested from the sender. Default OFTAdapter logic assumes a lossless transfer, so that difference breaks its debit-credit accounting. Supporting such a token requires customized debit and credit logic that reconciles actual balance changes and preserves the amount invariant. Rebasing tokens need equivalent care because balances can change outside a transfer.
Are opposite OFT directions allowed to use different verification settings?
Yes. An OFT pathway is directional, and each direction can have its own peer mapping, message libraries, DVN selection, confirmation requirement and execution options. A working source-to-destination transfer therefore doesn't prove that the return direction is wired or secured the same way. Each direction must authenticate the expected remote deployment and satisfy its own receive configuration.
Do OFT transfers need liquidity pools on every connected chain?
No. Direct OFT transfers use token debits and credits rather than pool-to-pool settlement. A burn-and-mint path doesn't need a liquidity pool, while a lockbox adapter depends on the tokens held by that adapter for unlocks on its home chain. The relevant constraint is the configured supply and custody model, not a universal pool balance on each chain.
- last updated