Value Transfer Implementations

Value Transfer is specialized messaging with token-specific invariants and settlement logic. Building on Module 1's value transfer concepts and Module 5's messaging patterns, LayerZero provides multiple approaches for implementing cross-chain asset movement.

Value Transfer as OApp Messaging

Value transfer uses the same LayerZero messaging for moving data, but adds token-specific invariants as part of the OApp's business logic:

// OFT: sends tokens with invariant logic
function send(SendParam memory params) external {
    // 1. Debit tokens locally (burn or lock)
    (uint256 sent, uint256 received) = _debit(msg.sender, params.amountLD, params.dstEid);

    // 2. Send message with token data
    bytes memory message = OFTMsgCodec.encode(params.to, _toSD(received), params.composeMsg);
    _lzSend(params.dstEid, message, options, fee, refundAddress);
}

// On destination: credit tokens
function _lzReceive(..., bytes calldata message, ...) internal override {
    address to = message.sendTo().bytes32ToAddress();
    uint256 amount = _toLD(message.amountSD());

    // 3. Credit tokens on destination (mint or unlock)
    _credit(to, amount, origin.srcEid);
}

Token-Specific Requirements:

• Supply integrity: Total supply preserved across all chains
• Atomic debit/credit: Local debit occurs immediately, remote credit on message delivery
• Decimal handling: Consistent precision across chains with different decimal systems
• Invariant enforcement: Token-specific rules (rate limits, permissions, etc.)

Value Transfer Implementation Approaches

Both approaches represent value transfer requests via LayerZero messages, with different settlement mechanisms:

1. Direct Token Messaging (Omnichain Fungible Token (OFT))

Loading diagram...

Settlement: Direct token operations (burn/mint or lock/unlock) via LayerZero messaging

2. Pool-Based Settlement (Stargate)

Loading diagram...

Settlement: Pool-to-pool coordination via LayerZero messaging with credit guarantees

3. Hybrid Settlement (Stargate Hydra OFT)

Loading diagram...

Settlement: Pool locks native assets on source, OFT mints representations on destination

---

While all these settlement types are similar in nature, they have different guarantees, trust assumptions, and target users depending on who the asset issuer is (token issuer, versus chain, versus DeFi user). The implementation details of moving value - and the control mechanisms involved - determine which approach is appropriate for specific use cases.

OFT: Omnichain Fungible Token Standard

OFT extends the OApp standard with token-specific debit and credit logic. The OFTCore contract implements the standard OApp _lzSend and _lzReceive functions with token invariant enforcement:

Loading diagram...

Key Insight: OFT is not a separate protocol - it's the OApp standard with standardized _debit and _credit abstractions for token handling.

How OFT Messaging Works

OFT messaging follows a precise flow that combines token operations with LayerZero messaging:

Loading diagram...

OFT Message Flow:

1. Token Debit: _debit() burns or locks tokens locally
2. Message Encoding: OFTMsgCodec.encode() creates standardized token message
3. LayerZero Send: _lzSend() dispatches message via LayerZero protocol
4. Verification & Delivery: DVNs verify, Executors deliver (standard LayerZero flow)
5. Message Decoding: OFTMsgCodec.decode() extracts token data from message
6. Token Credit: _credit() mints or unlocks tokens on destination

Why OFT is Popular

OFT is simply an interface for value transfer that runs on LayerZero messaging rails. However, as outlined in Module 3, asset issuers have the liberty to define what those rails look like and how they're governed.

Core Benefits:

1. Unified Supply: One token, many chains, consistent total supply across all deployments
2. No Wrapped Tokens: Native representation on each chain without bridging artifacts
3. Direct Transfer Model: Direct chain-to-chain token transfers without intermediate tokens
4. Composable: Send tokens with any message to any address, enabling complex workflows

Governance Flexibility (from modular architecture):

5. Custom Security Models: Asset issuers choose their own DVN configurations per pathway
6. Configurable Execution: Define gas settings, retry policies, and delivery guarantees per route
7. Configurable Pathways: Change security assumptions without redeploying token contracts
8. Mixed Trust Models: Use different verification approaches for different chains based on risk tolerance

Token Invariants

OFT implementations must maintain specific invariants to ensure safe cross-chain value transfer:

Debit/Credit Operations

In OFT implementations, value transfer operates through debit/credit operations:

• Debit: Remove tokens from source chain (burn or lock)
• Credit: Add tokens to destination chain (mint or unlock)

Critical Supply Invariants

In a global LayerZero token mesh, you can ONLY use these debit/credit combinations:

• Debit lock → Credit mint (lockbox to minter)
• Debit burn → Credit mint (burner to minter)
• Debit burn → Credit unlock (burner to lockbox)

NEVER use: Debit lock → Credit unlock, as tokens locked in escrow INSIDE the OFT contract cannot guarantee delivery without credit planning.

Token Decimal Normalization

Different blockchains use different decimal precision for representing tokens. For example, EVM chains typically use 18 decimals while Solana often uses 6 or 9 decimals. OFT handles this through a two-tier decimal system:

• Local Decimals: The native precision of the token on each specific chain
• Shared Decimals: The normalized precision used in LayerZero messages

The conversion follows a mathematical formula where the decimal conversion rate is:

$$\Large {decimalConversionRate} \;=\; 10^{\,(\text{localDecimals} - \text{sharedDecimals})}$$

The Precision Floor Problem: Different blockchains use different semantics and variable types for storing token balances. EVM chains use uint256 (unlimited precision), while Solana uses uint64 (limited precision). Without normalization, a token transfer could succeed on the source chain but fail on the destination due to precision overflow or underflow.

Shared Decimals Solution: By setting a common precision floor (default 6 decimals), OFT ensures that any amount that can be represented in the shared format will work on all connected chains, regardless of their native decimal systems or storage limitations.

Practical Impact: With sharedDecimals = 6, the minimum cross-chain transfer is 0.000001 tokens. This precision floor prevents issues where:

• High-precision chains (18 decimals) send amounts too small for low-precision chains (6 decimals)
• Variable type mismatches cause overflow when converting between chain formats
• Dust accumulation from repeated conversions leads to accounting errors

To transfer smaller amounts than 0.000001 tokens, you would need to increase sharedDecimals to a higher precision, but this must be consistent across all chains in your OFT deployment.

Benefits:

• Cross-Chain Consistency: Same economic value regardless of chain decimal differences
• Automatic Conversion: Developers don't need to handle decimal math manually
• Dust Protection: Prevents precision loss through automatic dust removal

For detailed technical implementation including overflow protection and mathematical formulas, see the OFT Technical Reference.

Architecture Patterns

How token contracts and bridge logic are organized:

Cross-VM Compatibility

While the examples below show EVM Solidity implementations, these same patterns apply to all LayerZero-supported blockchains including Solana, Aptos, and other VMs. The core concepts of debit/credit operations, supply invariants, and decimal normalization remain consistent across all virtual machine environments.

OFT Self (Integrated Token + Bridge)

Architecture: Single contract combines ERC20 token functionality with LayerZero bridge logic - the token contract IS the bridge contract.

Loading diagram...

Characteristics:

• Contract Structure: Single contract per chain containing both token and bridge logic
• Deployment: Must be deployed on every chain where tokens will exist
• Control Requirements: Must control minting authority on all deployment chains
• Retrofitting: Cannot be added to existing tokens without code modifications

Use Cases: New protocol tokens, governance tokens, tokens designed for omnichain deployment from inception

Implementation: Uses burn/mint operations internally (detailed in Implementation Patterns section below)

OFT Adapter (Separate Token + Bridge)

Architecture: Separate bridge contract handles LayerZero messaging while existing token contracts remain unchanged - the token contract is NOT the bridge contract.

Loading diagram...

Characteristics:

• Contract Structure: Separate bridge contract per chain, existing token contracts unchanged
• Deployment: Bridge contracts deployed alongside existing token deployments
• Control Requirements: Bridge must have appropriate permissions on token contract
• Retrofitting: Can be added to existing tokens without modifying token code

Use Cases: Existing tokens that cannot be modified, established tokens with existing ecosystems

Implementation: Can use various patterns - lock/unlock, mint/burn, or hybrid approaches (detailed in Implementation Patterns section below)

Implementation Patterns

The technical mechanisms used to transfer value across chains, regardless of architecture:

Burn/Mint Pattern

Debit/Credit Invariant: Debit burn → Credit mint

Architecture Compatibility:

• OFT Self: Built-in burn/mint operations
• OFT Adapter: Via MintBurnOFTAdapter with IMintableBurnable interface

OFT Self Implementation: Single contracts with integrated burn/mint operations:

Loading diagram...

MintBurn OFT Adapter Implementation: Separate bridge contracts with mint/burn permissions on existing tokens:

Loading diagram...

Characteristics:

• Supply Invariant: Global supply remains constant (burn on source = mint on destination)
• Capital Efficiency: No locked capital requirements
• Approval Required: Varies by architecture (OFT Self: false, OFT Adapter: true)
• Requirements: Mint/burn authority or IMintableBurnable interface implementation

Use Cases: New tokens, tokens with existing mint/burn infrastructure

Lock/Unlock Pattern

Debit/Credit Invariant: Debit lock → Credit mint (forward) / Debit burn → Credit unlock (reverse)

Architecture Compatibility:

• OFT Self: Not applicable (uses burn/mint)
• OFT Adapter: Via standard OFTAdapter with safeTransfer operations

Forward Direction (Lock/Mint): Tokens locked on source chain, minted on destination chains:

Loading diagram...

Reverse Direction (Burn/Unlock): Tokens burned on destination chains, unlocked from escrow on source chain:

Loading diagram...

Characteristics:

• Supply Invariant: Global supply increases in forward direction (locked + minted), decreases in reverse (burned, unlocked)
• Capital Efficiency: Requires reserves on source chain only
• Approval Required: True on source chain (for locking)
• Requirements: Mint authority on destination chains

Recommended Architecture: Deploy Adapter on one chain, OFT Self contracts everywhere else. This avoids permission requirements while enabling omnichain functionality.

Use Cases: Existing major tokens that need to connect to omnichain ecosystems

Native Asset Pattern

Debit/Credit Invariant: Debit lock → Credit mint (forward) / Debit burn → Credit unlock (reverse)

Architecture Compatibility:

• OFT Self: Not applicable
• OFT Adapter: Via NativeOFTAdapter with msg.value operations

Forward Direction (Lock/Mint): Native tokens locked on source chain, wrapped tokens minted on destination chains:

Loading diagram...

Reverse Direction (Burn/Unlock): Wrapped tokens burned on destination chains, native tokens unlocked on source chain:

Loading diagram...

Characteristics:

• Supply Invariant: Native tokens locked in contract balances
• Capital Efficiency: Requires native token reserves on destination chains
• Approval Required: False (native tokens sent via msg.value)
• Requirements: Contract must handle native asset transfers properly

Important Note: This pattern is intended for canonical asset issuers (e.g., Ethereum Foundation for ETH, Polygon Labs for MATIC) who want to enable their native token on other chains. This is NOT for development teams who want to bridge an existing native asset they don't control to their destination chain.

Use Cases: Native token bridging by canonical issuers (ETH by Ethereum Foundation, MATIC by Polygon Labs, AVAX by Avalanche Foundation)

Implementation Guidelines

Approach Selection

OFT Approach: Direct token messaging provides unified supply management and composability with other OApps. Token delivery depends on LayerZero message finality, requiring consideration of cross-chain latency and destination gas costs. Mint authority requirements limit this approach to new tokens or tokens with controllable minting.

Stargate Approach: Pool-based settlement provides deep liquidity for established native assets through coordinated pool networks. Settlement depends on LayerZero messaging between pools, with transport optimization through batching. Requires liquidity provision and may involve pool-based fees and slippage.

Technical Implementation

Decimal Handling: OFT implements automatic decimal conversion between local and shared decimals across chains. Use the built-in sharedDecimals() system rather than custom implementations.

Supply Monitoring: Track total supply across all chains to ensure supply invariants are maintained. Implement monitoring for supply discrepancies and reconciliation mechanisms.

Gas Planning: Account for destination chain execution costs in your execution options. Different chains have varying gas costs and mechanisms that affect total transfer costs.

Pattern Selection: Choose burn/mint patterns for new tokens requiring unified supply. Choose lock/mint patterns for existing tokens requiring omnichain expansion. Use pool-based approaches for high-liquidity native assets.

See Also

• OFT Quickstart - Deploy your first OFT
• Stargate Documentation - LP-based transfers
• OFT Standard - Technical specification
• Glossary - Complete terminology reference