Omnichain Fungible Token (OFT) Technical Reference

​

Deployment

​

Channel Configuration

• Connect the messaging channel at the Endpoint level (establishing the underlying pathway for crosschain messages).
• Pair the OFT deployments at the OApp level using setPeer(...), so each contract knows its trusted counterpart on the destination chain.

​

Core Transfer Flow

1. Debit on the source chain
   The sender calls the OFT’s send(...) function, burning or locking an amount of tokens.
2. Message dispatch via LayerZero
   The source OFT packages the transfer details into a LayerZero message and routes it through the protocol’s messaging layer. LayerZero’s messaging rails handle crosschain routing, verification of the encoded message, and delivery of the message to the destination chain’s receiver OFT contract.
3. Credit on the destination chain
   The paired OFT receives the message and credits the recipient by minting new tokens or unlocking previously-held tokens. The total supply across all chains remains constant, since burned or locked tokens on the source chain are matched 1:1 with minted or unlocked tokens on the destination.
4. (Optional) Trigger a composing call
   A composing contract uses the tokens received in a new transaction, delivered automatically by the LayerZero Executor, to trigger some state change (e.g., swap, stake, vote). For more details on how to implement composable OFT transfers, see Omnichain Composability.

​

Core Concepts

​

1. Transferring Value Across Different VMs

• Local Decimals
  Blockchains use integer mathematics to represent token amounts, avoiding floating-point precision issues. Each chain’s recommended token standard stores tokens as integers but with different decimal place conventions to represent fractional units. For example:
  • EVM chains: ERC-20 tokens typically use 18 decimal places. What users see as “1.0 USDC” is stored onchain as 1000000000000000000 (1 × 10^18) - the smallest unit often called “wei”
  • Solana: SPL tokens commonly use 6 or 9 decimal places. The same “1.0 USDC” would be stored as 1000000 (1 × 10^6) - the smallest unit of SOL called “lamports” (10^-9)
  • Aptos: Fungible Assets may use 6 or 8 decimal places depending on the asset
  Without proper conversion, transferring the integer value 1000000000000000000 from an 18-decimal EVM chain to a 6-decimal Solana chain would result in an astronomically large amount instead of the intended 1 token. The localDecimals field tells the OFT contract how many decimal places that specific blockchain uses to represent the token’s smallest units.
• Shared Decimals
  To ensure consistent value representation, every OFT declares a sharedDecimals parameter. Before sending a token crosschain, the OFT logic converts the “local” amount into a normalized “shared” unit. Upon arrival, the destination OFT reconverts that shared unit back into the local representation of its own decimal precision.
• Dust Removal
  Before converting the local unit amount (amountLD) into the shared unit amount (amountSD), OFT implementations first “floor” the local amount to the nearest multiple of the conversion rate so that no remainder (“dust”) is included in the crosschain transfer. The normalization process works as follows:
  1. Compute the conversion rate: $$\text{decimalConversionRate} = 10^{(\text{localDecimals} - \text{sharedDecimals})}$$
  2. Remove dust by flooring to that multiple (e.g., integer division on the EVM): $$\text{flooredAmountLD} = \Bigl\lfloor \frac{\text{amountLD}}{\text{decimalConversionRate}} \Bigr\rfloor \times \text{decimalConversionRate}$$
  3. Compute and return the dust remainder to the sender: $$\text{dust} = \text{amountLD} - \text{flooredAmountLD}$$ That dust is refunded to the sender’s balance before proceeding with debiting the sender’s account, and the flooredAmountLD is now used as the amountLD.
  4. Convert the amount in local decimals (amountLD) to shared units on the source chain: $$\text{amountSD} = \frac{\text{amountLD}}{\text{decimalConversionRate}}$$
  5. Transmit the amount in shared decimals (amountSD) as part of the LayerZero message.
  6. On the destination chain, reconstruct the local amount (amountLD): $$\text{amountLD} = \text{amountSD} \times \text{decimalConversionRate}$$
• Why This Matters
  • Consistent Economic Value: “1 OFT” means the same thing on any chain, regardless of differing decimal precision.
  • DeFi Compatibility: Prevents rounding errors and ensures seamless integration with onchain tooling (e.g., AMMs, lending protocols) that expect familiar decimal behavior.
  • No Precision Loss: By using a common sharedDecimals, you avoid truncation or expansion mistakes when moving large or small amounts across networks.
  If you override the vanilla sharedDecimals amount or have an existing token supply exceeding 18,446,744,073,709.551615 tokens, extra caution should be applied to ensure amountSD and amountLD do not overflow. Vanilla OFTs can disregard this admonition.

  1. Shared‐Unit Overflow (amountSD)
     OFT encodes amountSD as a 64-bit unsigned integer (uint64). The largest representable shared‐unit value is 2^64 − 1. Therefore, the maximum token supply (in whole‐token terms) is:

  $$\frac{2^{64} - 1}{10^{\text{sharedDecimals}}}$$In vanilla OFT implementations, sharedDecimals = 6, yielding a max supply of$$\frac{2^{64} - 1}{10^6} = 18{,}446{,}744{,}073{,}709.551615 \text{ tokens}$$If you choose a smaller sharedDecimals, the divisor shrinks and you may exceed the uint64 limit when converting a large amountLD into amountSD.

  2. Local‐Unit Overflow (amountLD)
     On some chains (e.g., Solana’s SPL Token or Aptos’s Fungible Asset), the native token amount is also stored as a 64-bit unsigned integer (uint64). In those environments, the maximum local amount is 2^64 − 1. But because amountLD must be a multiple of

  $$\text{decimalConversionRate} = 10^{(\text{localDecimals} - \text{sharedDecimals})}$$If amountSD × decimalConversionRate would exceed 2^64 − 1, the reconstructed amountLD cannot fit in the native uint64 type.To avoid both overflow risks:

  • Pick sharedDecimals so that your target maximum supply divided by 10^{sharedDecimals} is ≤ 2^64 − 1.
  • Verify each chain’s local type (e.g., uint64 on Solana/Aptos or uint256 on most EVM chains) can accommodate the resulting amountLD (i.e., amountSD × decimalConversionRate must not exceed the local limit).

​

2. Adapter vs. Direct Patterns: Contract Structure & Bridge Logic

​

What Is “Direct” vs. “Adapter”?

• Direct Pattern
  • The token contract itself contains all bridge logic (send/receive) along with standard token functions (mint, burn, transfer).
  • When a user initiates a crosschain transfer, the token contract on the source chain invokes internal “debit” logic to burn tokens, packages the message, and sends it through LayerZero. On the destination chain, the same contract (deployed there) receives the message and invokes internal “credit” logic to mint new tokens.
• Adapter Pattern
  • The token contract is separate from the bridge logic. Instead of embedding send/receive in the token, an adapter contract handles all crosschain operations.
  • The adapter holds (locks) user tokens (or has burn and mint roles, e.g., “Mint and Burn Adapter”) and communicates with a paired OFT contract on the destination chain, which mints/unlocks or transfers the equivalent amount to the recipient.
  • From the developer’s perspective, the only requirement is that the adapter exists as a standalone contract; the original token contract remains unaware of LayerZero or crosschain flows.

​

Key Distinctions

• Separate vs. Combined
  • Direct: Token + bridge = single deployable.
  • Adapter: Token = unmodified existing contract; Bridge logic = standalone adapter contract.
• Mint And Burn Adapter Example
  • Even though it uses mint/burn semantics, it is still an “Adapter” because the adapter contract, not the token contract itself, contains all LayerZero business logic.
  • The adapter delegates calls to mint or burn on a “wrapper” token or calls an interface on the underlying token, separating concerns without requiring the original token code to change.
• User/Integrator Perspective
  • No Difference in UX: Users call a standard send function (or “transfer” wrapper) without caring whether the token is Direct or Adapter.
  • Meshability: Any two OFT-enabled contracts (Direct or Adapter) on different chains can interoperate. This means liquidity can span adapters and direct tokens seamlessly, making the system truly omnichain.

​

Implications for Asset Issuers

• Direct Pattern Suits New Tokens
  • When launching a brand-new token, embedding OFT logic directly can save on contract count and gas.
  • Simplifies deployment paths since your token and crosschain logic are co-located.
• Adapter Pattern Suits Existing Tokens
  • If you already have an active ERC-20 (or SPL, or Move) token with liquidity and integrations, deploying an adapter contract lets you plug into OFT without migrating your token.
  • The adapter can implement mint and burn, lock and unlock, or any hybrid, as long as it abides by the OFT interface.
• Access Control & Governance
  • Direct Token: You manage roles (Admin, Delegate) within a single contract.
  • Adapter + Token: You may need to coordinate roles and permissions across two deployables.

​

3. Extensibility & Composability

​

Hooks Around Debit/Credit

• Beyond Value Transfer
  • Many applications require extra functionality during or after crosschain value transfer for example:
    • Protocol Fees: Automatically deduct a small fee on each crosschain transfer and route it to a treasury.
    • Rate Limiting: Applying a limit on the number of tokens that can be sent in a given time-interval.
    • Access Control: Enforce time-based or role-based restrictions, such as requiring KYC verification for large transfers.
• Overrideable Functions
  • OFT’s core _debit and _credit methods are declared virtual (or their equivalent in non-EVM languages), allowing developers to override them in custom subclasses/modules.
  • Inject additional checks or side effects (e.g., take fees off transfers, check for rate limits, or validate off-chain context) without rewriting the entire message flow.

​

Composability with LayerZero Messaging

• Crosschain Value Transfer + Call
  • You can bundle arbitrary data with your OFT transfer. For example, trigger a staking action on the destination chain if a recipient stakes a minimum amount, or execute a crosschain governance vote.
  • The OFT contract simply forwards any extra bytes as a composeMsg through LayerZero’s endpoint. On the destination, your custom lzCompose(...) hook can decode and act on that arbitrary data and token transfer.

​

Security & Roles

• Owner
  • Sets required gas limit requests for execution.
  • Can peer new OApp contracts or remove peers in emergencies.
• Delegate
  • Configures connected chain’s and messaging channel properties (e.g., Message Libraries, DVNs, and executors).
  • Can pause or unpause crosschain functionality in emergencies.

Best Practice: Use a multisig to manage both Owner and Delegate privileges.

​

Further Reading

• EVM OFT Quickstart A step-by-step guide to deploying Direct or Adapter OFT contracts on Ethereum-compatible networks.
• Solana OFT Quickstart Detailed instructions and example code for setting up an OFT program with SPL Token / Token 2022 integration.
• Aptos Move OFT Quickstart In-depth documentation on Move module structure, sharedDecimals math, and composability best practices.