> >
> > **EVM equivalence:**\ > These chains replicate Ethereum's execution environment so closely that standard clients, deployment scripts, and tooling work without modification. Most LayerZero integrations (like OApp/OFT/ONFT and lzRead queries) work as on Ethereum—with only subtle differences. These differences directly impact: * **Fee payment:** Standard `msg.value` fee delivery is expected by LayerZero endpoints. Some chains, however, require alternative tokens or extra configuration. * **Onchain data:** lzRead can depend on `block.number` and `block.timestamp`. Variability or drift in these values (for instance, Arbitrum may return L1 `block.number`) may result in inaccurate or outdated state queries. * **Gas management:** Accurate gas limits must be set to ensure `lzReceive` and `lzCompose` execution succeeds across chains. ## Detailed Chain-Specific Overviews Below is a summary for each chain type with key impacts for LayerZero integrations and links to more documentation.
## Usage Once deployed and wired, you can begin sending crosschain messages. ### Calling `send`
## Usage Once deployed and wired, you can begin sending tokens across chains. ### Send tokens The OFT standard provides methods for quoting and sending tokens crosschain via the [IOFT interface](https://github.com/LayerZero-Labs/devtools/blob/main/packages/oft-evm/contracts/interfaces/IOFT.sol). #### quoteSend() - Get Transfer Fees
**Scenario**: Deposit `asset` from a `_spokeEid`, receive vault `shares` on **a different** `_spokeEid` ```bash wrap theme={null} # Using the CLI task (recommended) npx hardhat lz:ovault:send \ --src-eid 30110 --dst-eid 30111 \ --amount 100.0 --to 0xRecipient \ --token-type asset ``` **Flow**: ```mermaid wrap theme={null} sequenceDiagram participant U as User(Arbitrum) participant A_SRC as AssetOFT(Arbitrum) participant A_HUB as AssetOFT(Hub) participant C as Composer(Hub) participant V as Vault(Hub) participant S_HUB as ShareOFTAdapter(Hub) participant S_DST as ShareOFT(Optimism) participant R as Recipient rect rgb(40, 169, 225) Note over U,A_SRC: Arbitrum Chain end rect rgb(243, 244, 246) Note over A_HUB,S_HUB: Hub Chain end rect rgb(255, 4, 32) Note over S_DST,R: Optimism Chain end U->>A_SRC: send(asset, dstEid, composer, composeMsg) A_SRC->>A_HUB: LayerZero transfer A_HUB->>C: lzReceive() → lzCompose() Note over C: Detects asset deposit operation C->>V: deposit(assets) V-->>C: shares minted C->>S_HUB: send(shares, optimism, recipient) S_HUB->>S_DST: LayerZero transfer S_DST->>R: shares delivered Note over U,R: Single transaction: Assets(Arbitrum) → Shares(Optimism) ```
**Scenario**: Deposit `asset` from `_spokeEid`, receive vault `shares` on the `_hubEid` chain ```bash wrap theme={null} npx hardhat lz:ovault:send \ --src-eid 30110 --dst-eid 30184 \ --amount 100.0 --to 0xRecipient \ --token-type asset ``` **Flow**: ```mermaid wrap theme={null} sequenceDiagram participant U as User(Arbitrum) participant A_SRC as AssetOFT(Arbitrum) participant A_HUB as AssetOFT(Hub) participant C as Composer(Hub) participant V as Vault(Hub) participant R as Recipient(Hub) rect rgb(40, 169, 225) Note over U,A_SRC: Arbitrum Chain end rect rgb(243, 244, 246) Note over A_HUB,R: Hub Chain end U->>A_SRC: send(asset, dstEid, composer, composeMsg) A_SRC->>A_HUB: LayerZero transfer A_HUB->>C: lzReceive() → lzCompose() Note over C: Detects asset deposit operation C->>V: deposit(assets) V-->>C: shares minted Note over C: dstEid == hubEid (local delivery) C->>R: Direct ERC20 transfer (shares) Note over U,R: Single transaction: Assets(Arbitrum) → Shares(Hub) ``` ### Redeem Shares → Receive Assets **Scenario**: Redeem vault `shares` from `_spokeEid`, receive `asset` on different `_spokeEid` ```bash wrap theme={null} npx hardhat lz:ovault:send \ --src-eid 30111 --dst-eid 30110 \ --amount 50.0 --to 0xRecipient \ --token-type share ``` **Flow**: ```mermaid wrap theme={null} sequenceDiagram participant U as User(Optimism) participant S_SRC as ShareOFT(Optimism) participant S_HUB as ShareOFTAdapter(Hub) participant C as Composer(Hub) participant V as Vault(Hub) participant A_HUB as AssetOFT(Hub) participant A_DST as AssetOFT(Arbitrum) participant R as Recipient(Arbitrum) rect rgb(255, 4, 32) Note over U,S_SRC: Optimism Chain end rect rgb(243, 244, 246) Note over S_HUB,A_HUB: Hub Chain end rect rgb(40, 169, 225) Note over A_DST,R: Arbitrum Chain end U->>S_SRC: send(shares, dstEid, composer, composeMsg) S_SRC->>S_HUB: LayerZero transfer S_HUB->>C: lzReceive() → lzCompose() Note over C: Detects share redeem operation C->>V: redeem(shares) V-->>C: assets returned C->>A_HUB: send(assets, arbitrum, recipient) A_HUB->>A_DST: LayerZero transfer A_DST->>R: assets delivered Note over U,R: Single transaction: Shares(Optimism) → Assets(Arbitrum) ```
**Scenario**: Redeem `vault` shares from `_spokeEid`, receive `asset` on the `_hubEid` chain ```bash wrap theme={null} npx hardhat lz:ovault:send \ --src-eid 30111 --dst-eid 30184 \ --amount 50.0 --to 0xRecipient \ --token-type share ``` **Flow**: ```mermaid wrap theme={null} sequenceDiagram participant U as User(Optimism) participant S_SRC as ShareOFT(Optimism) participant S_HUB as ShareOFTAdapter(Hub) participant C as Composer(Hub) participant V as Vault(Hub) participant R as Recipient(Hub) rect rgb(255, 4, 32) Note over U,S_SRC: Optimism Chain end rect rgb(243, 244, 246) Note over S_HUB,R: Hub Chain end U->>S_SRC: send(shares, dstEid, composer, composeMsg) S_SRC->>S_HUB: LayerZero transfer S_HUB->>C: lzReceive() → lzCompose() Note over C: Detects share redeem operation C->>V: redeem(shares) V-->>C: assets returned Note over C: dstEid == hubEid (local delivery) C->>R: Direct ERC20 transfer (assets) Note over U,R: Single transaction: Shares(Optimism) → Assets(Hub) ``` ### SDK Integration For programmatic integration, use the official SDK [`@layerzerolabs/ovault-evm/src`](https://github.com/LayerZero-Labs/devtools/tree/main/packages/ovault-evm/src) which simplifies OVault operations by using [viem](https://viem.sh/) to generate the necessary calldata for calling `OFT.send()` with the proper `composeMsg` for the hub composer. The SDK's `OVaultMessageBuilder.generateOVaultInputs()` method handles all the complex message encoding and returns ready-to-use transaction parameters for `viem` wallet clients. ```typescript wrap theme={null} const input = { srcEid: 40245, // eid for base-sepolia hubEid: 40231, // eid for arbitrum-sepolia dstEid: 40245, // eid for base-sepolia // Optional. If dstAddress is not specified it will default to the walletAddress on the dst chain dstAddress: '0x0000000000000000000000000000000000000000', walletAddress: '0x0000000000000000000000000000000000000000', vaultAddress: '0x0000000000000000000000000000000000000000', // Address of the OVault Composer on the Hub Chain. Should implement IVaultComposerSync composerAddress: '0x0000000000000000000000000000000000000000', // Supply the Viem Chain Definitions for the hub and source chain. This is so the sdk can // quote fees and perform read operations hubChain: arbitrumSepolia, sourceChain: baseSepolia, operation: OVaultOperations.DEPOSIT, amount: 100000000000000000n, slippage: 0.01, // 1% slippage // Address of the token/oft. The token is an ERC20. They can be the same address. // If tokenAddress isn't specified it defaults to the oftAddress tokenAddress: '0x0000000000000000000000000000000000000000', oftAddress: '0x0000000000000000000000000000000000000000', } as const; const inputs = await OVaultMessageBuilder.generateOVaultInputs(input); ``` For complete usage examples, API reference, and advanced configuration, see the [SDK repository](https://github.com/LayerZero-Labs/devtools/blob/main/packages/ovault-evm/README). For manual integration and advanced usage, see the [Technical Reference](#technical-reference) section below. ## Technical Reference ### Contracts Overview OVault uses a **hub-and-spoke model**: * **Hub Chain**: Hosts the `OFT` asset, `ERC4626` vault, the `VaultComposerSync`, and the share's `OFTAdapter` (lockbox) * **Spoke Chains**: Host `OFT` assets and `OFT` shares that connect to the hub implementations These connections enable a user to transfer an amount of the asset or share `OFT` from a **source** blockchain, **deposit** or **redeem** the token amount in the `ERC4626` vault, and receive the corresponding output token amount back on the **source** network. ```mermaid wrap theme={null} sequenceDiagram participant U as User(Arbitrum) participant A_SRC as AssetOFT(Arbitrum) participant A_HUB as AssetOFT(Hub) participant C as Composer(Hub) participant V as ERC4626(Hub) participant S_HUB as ShareOFTAdapter(Hub) rect rgb(40, 169, 225) Note over U,A_SRC: Arbitrum Chain end rect rgb(243, 244, 246) Note over A_HUB,S_HUB: Hub Chain end U->>A_SRC: send(asset, dstEid, composer, composeMsg) A_SRC->>A_HUB: LayerZero transfer A_HUB->>C: lzReceive() → lzCompose() Note over C: Detects asset deposit operation C->>V: deposit(assets) V-->>C: shares minted C->>S_HUB: send(shares, arbitrum, recipient) S_HUB->>A_SRC: LayerZero transfer (shares) A_SRC->>U: shares delivered Note over U,S_HUB: Single transaction: Assets → Shares (source chain) ```
If you have an existing `assetOFT`, `vault`, or `ShareOFT` implementation, you may only need to deploy some of the contracts provided in the `ovault-evm` example repo: ##### Share OFT (Spoke Chains) ```solidity wrap theme={null} // SPDX-License-Identifier: UNLICENSED pragma solidity ^0.8.20; import { Ownable } from "@openzeppelin/contracts/access/Ownable.sol"; import { OFT } from "@layerzerolabs/oft-evm/contracts/OFT.sol"; /** * @title MyShareOFT * @notice ERC20 representation of the vault's share token on a spoke chain for crosschain functionality * @dev This contract represents the vault's share tokens on spoke chains. It inherits from * LayerZero's OFT (Omnichain Fungible Token) to enable seamless crosschain transfers of * vault shares between the hub chain and spoke chains. This contract is designed to work * with ERC4626-compliant vaults, enabling standardized crosschain vault interactions. * * Share tokens represent ownership in the vault and can be redeemed for the underlying * asset on the hub chain. The OFT mechanism ensures that shares maintain their value and can be freely * moved across supported chains while preserving the vault's accounting integrity. */ contract MyShareOFT is OFT { /** * @notice Constructs the Share OFT contract * @dev Initializes the OFT with LayerZero endpoint and sets up ownership * @param _name The name of the share token * @param _symbol The symbol of the share token * @param _lzEndpoint The address of the LayerZero endpoint on this chain * @param _delegate The address that will have owner privileges */ constructor( string memory _name, string memory _symbol, address _lzEndpoint, address _delegate ) OFT(_name, _symbol, _lzEndpoint, _delegate) Ownable(_delegate) { // WARNING: Do NOT mint share tokens directly as this breaks the vault's share-to-asset ratio // Share tokens should only be minted by the vault contract during deposits to maintain // the correct relationship between shares and underlying assets // _mint(msg.sender, 1 ether); // ONLY uncomment for testing UI/integration, never in production } } ``` Similar to `MyAssetOFT`, `MyShareOFT` is a standard `OFT` representation of the `share` token from the `ERC4626` vault to be used on other spoke chains. This contract requires `MyShareOFTAdapter` to be deployed on the hub chain using the `share` address as the `_token` argument.
with composeMsg]) --> OFTTransfer[LayerZero OFT transfer
Source → Hub chain] OFTTransfer --> LayerZeroCheck{LayerZero transfer
successful?} LayerZeroCheck -->|Yes| LzReceive[LZ Executor calls lzReceive
OFT credits tokens to composer] LayerZeroCheck -->|No| TxRevert[Transaction reverts
No tokens moved] LzReceive --> SendCompose[OFT calls endpoint.sendCompose
Stores composeMsg for execution] SendCompose --> LzCompose[LZ Executor calls lzCompose
on VaultComposerSync] LzCompose --> TryCatch[try-catch around handleCompose
Protects against composer failures] TryCatch --> MsgValueCheck{msg.value sufficient
for destination delivery?} MsgValueCheck -->|Yes| VaultExecution[Vault operation executes
vault.deposit or vault.redeem] MsgValueCheck -->|No| AutoRefund[InsufficientMsgValue revert
try-catch triggers _refund] VaultExecution --> ActualAmount[actualAmount from vault output
shares or assets received] ActualAmount --> SlippageCheck{actualAmount >= minAmountLD
from composeMsg?} SlippageCheck -->|Yes| UpdateParam[Update SendParam.amountLD
Reset minAmountLD to zero] SlippageCheck -->|No| SlippageRevert[revert SlippageExceeded
try-catch triggers _refund] UpdateParam --> OutputDelivery[_send executes
Hub → Destination or local transfer] OutputDelivery --> Success[✓ Operation complete
Tokens delivered to recipient] TxRevert --> RetryState[User retries with
correct gas/fees] AutoRefund --> RetryState SlippageRevert --> RetryState[User retries with
adjusted slippage tolerance] ``` ### Refund Scenarios and Recovery The `VaultComposerSync` uses a try-catch pattern around `handleCompose()` to ensure robust error handling: ```solidity wrap theme={null} try this.handleCompose{ value: msg.value }(/*...*/) { emit Sent(_guid); } catch (bytes memory _err) { // Automatic refund for any handleCompose failures _refund(_composeCaller, _message, amount, tx.origin); emit Refunded(_guid); } ``` **Common scenarios caught by try-catch**: * `InsufficientMsgValue` - insufficient gas for destination delivery → Auto refund * `SlippageExceeded` - vault output below minimum → Manual refund available * Vault operational errors (paused, insufficient liquidity) → Manual refund available ##### Transaction Revert: Gas or Fee Issues **What happens**: OFT transfer fails on source chain before any tokens move **Common causes**: * Insufficient native tokens for LayerZero fees * Invalid destination endpoint configuration * Gas estimation errors **User experience**: Transaction reverts immediately, no tokens transferred **Recovery**: User can retry immediately after fixing the issue * Use `quoteSend()` to get accurate fee estimation * Verify destination chain configuration * Ensure sufficient native tokens for crosschain fees ##### Automatic Refund: Insufficient msg.value for Second Hop **What happens**: LayerZero completes lzReceive and lzCompose successfully, but insufficient gas for destination delivery **Technical flow**: 1. LZ Executor calls `lzReceive()` - tokens credited to composer ✓ 2. OFT calls `endpoint.sendCompose()` - composeMsg stored ✓ 3. LZ Executor calls `lzCompose()` on VaultComposerSync ✓ 4. Try-catch around `handleCompose()` catches `InsufficientMsgValue` revert 5. Automatic `_refund()` triggered back to source chain **Common causes**: * Underestimated gas for second hop during `quoteSend()` * Gas price fluctuations between quote and execution * Complex destination chain operations requiring more gas **User experience**: * Crosschain transfer appears successful initially * Composer automatically triggers refund to source chain * Original tokens returned within minutes **Recovery**: Automatic - no user action required * Monitor source chain for refunded tokens * Retry with higher gas estimate from `quoteSend()` ##### Manual Refund: Vault Operation Issues **What happens**: LayerZero flow completes successfully, but vault operation fails slippage check **Technical flow**: 1. LZ Executor calls `lzReceive()` - tokens credited to composer ✓ 2. OFT calls `endpoint.sendCompose()` - composeMsg stored ✓ 3. LZ Executor calls `lzCompose()` on VaultComposerSync ✓ 4. Try-catch around `handleCompose()` executes vault operation ✓ 5. Vault returns `actualAmount` (shares or assets) 6. Slippage check: `actualAmount >= minAmountLD` **FAILS** 7. `SlippageExceeded` revert caught by try-catch 8. Manual `_refund()` available (user must trigger) **Common causes**: * Vault share/asset price changed during crosschain transfer * Vault hit deposit/withdrawal limits between quote and execution * `minAmountLD` set too high based on stale `previewDeposit/previewRedeem` data **User experience**: * Crosschain transfer succeeds * Vault operation fails on hub with slippage error * Tokens held by composer awaiting user action **Recovery**: User must manually trigger refund from hub chain 1. Switch wallet to hub chain network 2. Call composer refund function 3. Original tokens returned to source chain 4. Retry operation with adjusted slippage tolerance **Prevention**: * Use wider slippage tolerance (2-5% for volatile vaults) * Check vault limits: `vault.maxDeposit()`, `vault.maxRedeem()` * Monitor vault state with `vault.previewDeposit()` before large operations * Account for time delays in crosschain operations when setting `minAmountLD` # LayerZero V2 Solidity Contract Standards Source: https://docs.layerzero.network/v2/developers/evm/overview Overview of Solidity Contract Standards on LayerZero V2. Learn the architecture, features, and how to get started building. LayerZero enables secure... LayerZero enables seamless crosschain messaging, configurations for security, and other quality of life improvements to simplify crosschain development. ## LayerZero Solidity Contract Standards
(LayerZero)"] OFTCoreBase["OFTCoreBaseUpgradeable
Core OFT send/receive logic"] OFTCoreRBAC["OFTCoreRBACUpgradeable
+ RBAC for OApp config"] OFTCoreExtended["OFTCoreExtendedRBACUpgradeable
+ Fee + RateLimiter + PauseByID + CreditRedirect"] BurnMintExtended["OFTBurnMintExtendedRBACUpgradeable
+ burn/mint with custom selectors"] LockUnlockExtended["OFTLockUnlockExtendedRBACUpgradeable
+ lock/unlock token transfers"] NativeExtended["OFTNativeExtendedRBACUpgradeable
+ native token wrapping"] OFTBurnMint["OFTBurnMint"] OFTBurnSelfMint["OFTBurnSelfMint"] OFTLockUnlock["OFTLockUnlock"] OFTNative["OFTNative"] OAppUpgradeable --> OFTCoreBase OFTCoreBase --> OFTCoreRBAC OFTCoreRBAC --> OFTCoreExtended OFTCoreExtended --> BurnMintExtended OFTCoreExtended --> LockUnlockExtended OFTCoreExtended --> NativeExtended BurnMintExtended --> OFTBurnMint BurnMintExtended --> OFTBurnSelfMint LockUnlockExtended --> OFTLockUnlock NativeExtended --> OFTNative ACEnumerable["AccessControlEnumerableUpgradeable
(OpenZeppelin)"] AC2Step["AccessControl2StepUpgradeable"] FeeRBAC["FeeRBACUpgradeable"] RateLimiterRBAC["RateLimiterRBACUpgradeable"] PauseByIDRBAC["PauseByIDRBACUpgradeable"] CreditRedirectRBAC["CreditRedirectRBACUpgradeable"] ACEnumerable --> AC2Step AC2Step -.->|inherited via| FeeRBAC AC2Step -.->|inherited via| RateLimiterRBAC AC2Step -.->|inherited via| PauseByIDRBAC AC2Step -.->|inherited via| CreditRedirectRBAC FeeRBAC -.->|mixin| OFTCoreExtended RateLimiterRBAC -.->|mixin| OFTCoreExtended PauseByIDRBAC -.->|mixin| OFTCoreExtended CreditRedirectRBAC -.->|mixin| OFTCoreExtended style OFTBurnMint fill:#34a853,color:#fff style OFTBurnSelfMint fill:#34a853,color:#fff style OFTLockUnlock fill:#34a853,color:#fff style OFTNative fill:#34a853,color:#fff ``` Each green box is a **deployable contract**. Everything above is abstract. The `Alt` variants (`OFTBurnMintAlt`, `OFTLockUnlockAlt`, `OFTBurnSelfMintAlt`) follow the same hierarchy but target `EndpointV2Alt` for chains where ERC20 tokens are used for gas fees. ## ERC20Plus Inheritance ```mermaid theme={null} graph TB ERC20Upgradeable["ERC20Upgradeable
(OpenZeppelin)"] ERC20PermitUpgradeable["ERC20PermitUpgradeable
(OpenZeppelin)"] AllowlistRBAC["AllowlistRBACUpgradeable
3-mode allowlist + RBAC"] PauseRBAC["PauseRBACUpgradeable
Global pause + RBAC"] ACEnumerable["AccessControlEnumerableUpgradeable
(OpenZeppelin)"] AC2Step["AccessControl2StepUpgradeable"] ERC20Plus["ERC20Plus
+ mint/burn + fund recovery"] ERC20Upgradeable --> ERC20PermitUpgradeable ERC20PermitUpgradeable --> ERC20Plus AllowlistRBAC --> ERC20Plus PauseRBAC --> ERC20Plus ACEnumerable --> AC2Step AC2Step -.->|inherited via| AllowlistRBAC AC2Step -.->|inherited via| PauseRBAC style ERC20Plus fill:#34a853,color:#fff ``` ## Cross-Chain Message Flow ### Send Path (Source Chain) ``` send() | v OFTCoreBaseUpgradeable.send() | v _debit() [overridden per variant] |-- whenNotPaused(_dstEid) <-- PauseByID |-- _debitView() <-- Fee calculation | |-- getFee(_dstEid, _amountLD) | |-- _removeDust() | +-- SlippageExceeded check |-- _outflow(_dstEid, _from, amount) <-- Rate limit | |-- Address exemption check | +-- Token bucket decay +-- Transfer/burn + collect fee <-- Allowlist & global pause | v _buildMsgAndOptions() | v _lzSend() --> LayerZero Endpoint | v emit OFTSent(guid, dstEid, from, amountSentLD, amountReceivedLD) ``` ### Receive Path (Destination Chain) ``` LayerZero Endpoint delivers message | v _lzReceive() | v _credit() [overridden per variant] |-- _inflow(_srcEid, _to, _amountLD) <-- Rate limit (inbound) |-- _redirectCredit(_to, amount) <-- Escrow if configured and not allowlisted +-- Mint/unlock/transfer to recipient <-- Or escrow, if redirected | v If compose message exists: +-- endpoint.sendCompose() --> downstream contract | v emit OFTReceived(guid, srcEid, to, amountReceivedLD) ``` ## Transfer Model Mechanics ### Burn/Mint ``` Source Chain Destination Chain +--------------------+ +--------------------+ | ERC20Plus | | ERC20Plus | | | | | | burn() | LayerZero V2 | mint() | | | -----------> | | | | | | | OFTBurnMint | | OFTBurnMint | +--------------------+ +--------------------+ ``` The OFT must hold `MINTER_ROLE` and `BURNER_ROLE` on the `ERC20Plus` token. Total supply across all chains remains constant. ### Burn-Self/Mint ``` Source Chain Destination Chain +--------------------+ +--------------------+ | ERC20Plus | | ERC20Plus | | | | | | transferFrom() | LayerZero V2 | mint() | | burn() | -----------> | | | | | | | OFTBurnSelfMint | | OFTBurnSelfMint | +--------------------+ +--------------------+ ``` First transfers tokens from user to OFT via ERC20 allowance, then burns using `burn(uint256)` selector. The OFT must hold `MINTER_ROLE` on the destination token. ### Lock/Unlock ``` Source Chain Destination Chain +--------------------+ +--------------------+ | ERC20Plus | | ERC20Plus | | | | | | transferFrom() | LayerZero V2 | transfer() | | (lock in OFT) | -----------> | | | | | | | OFTLockUnlock | | OFTLockUnlock | +--------------------+ +--------------------+ ``` Tokens are locked in the OFT contract on the source chain and unlocked from the OFT contract on the destination. Only one lock/unlock OFT should exist per mesh to prevent supply fragmentation. ### Native ``` Source Chain Destination Chain +--------------------+ +--------------------+ | | | | | msg.value | LayerZero V2 | .call{value} | | (ETH sent | -----------> | (ETH sent to | | with tx) | | recipient) | | | | | | OFTNative | | OFTNative | +--------------------+ +--------------------+ ``` The OFT wraps/unwraps native tokens. `msg.value` must include both the transfer amount and the LayerZero messaging fee. ## Upgradeability Model All contracts support Transparent Upgradeable Proxy (TUP) and Beacon proxy patterns: * **Proxy contract** holds state (storage) and delegates calls to the implementation * **Implementation contract** holds logic and is stateless * **EIP-7201 namespaced storage** ensures each module's storage is isolated at a deterministic slot, preventing collisions ## Next Steps * [ERC20Plus](/v2/developers/evm/stablecoin-oft/erc20plus) for the token core (layer 1) * [OFTs](/v2/developers/evm/stablecoin-oft/ofts) for the cross-chain transport (layer 3) * [Extensions](/v2/developers/evm/stablecoin-oft/extensions) for token controls and cross-chain extensions (layers 2 and 4) # ERC20Plus Source: https://docs.layerzero.network/v2/developers/evm/stablecoin-oft/erc20plus Enhanced upgradeable ERC20 token with enterprise controls: RBAC mint/burn, three-mode allowlist, global pause, ERC20Permit, and fund recovery. `ERC20Plus` is an enhanced, upgradeable ERC20 token that works consistently across EVM chains supported by LayerZero, without relying on native token standard quirks that vary by chain. It provides administrative controls directly at the token level. ## Feature Comparison | Feature | Standard ERC20 | `ERC20Plus` | | ------------------------------ | -------------- | ---------------------------------------------- | | Transfer / Approve / Allowance | Yes | Yes | | Role-based mint | No | Yes (`MINTER_ROLE`) | | Role-based burn | No | Yes (`BURNER_ROLE`) | | Allowlist (3-mode) | No | Yes (Open / Blacklist / Whitelist) | | Global pause | No | Yes (separate `PAUSER_ROLE` / `UNPAUSER_ROLE`) | | Fund recovery | No | Yes (`DEFAULT_ADMIN_ROLE`) | | ERC20Permit (EIP-2612) | Optional | Built-in | | Enumerable address lists | No | Yes (paginated blacklist/whitelist queries) | | Upgradeable | Depends | Yes (EIP-7201 namespaced storage) | | RBAC (AccessControl2Step) | No | Yes (OpenZeppelin) | ## Features ### Role-Based Minting and Burning `ERC20Plus` defines two roles for token supply management: ```solidity theme={null} bytes32 public constant MINTER_ROLE = keccak256("MINTER_ROLE"); bytes32 public constant BURNER_ROLE = keccak256("BURNER_ROLE"); ``` * **MINTER\_ROLE**: Can call `mint(address _to, uint256 _amount)` to create new tokens * **BURNER\_ROLE**: Can call `burn(address _from, uint256 _amount)` to destroy tokens When used with OFTs, the OFT contract must be granted both `MINTER_ROLE` and `BURNER_ROLE` so it can mint tokens on the receive path and burn tokens on the send path. ### Allowlist, Pause, and Fund Recovery `ERC20Plus` includes a three-mode allowlist (Open / Blacklist / Whitelist), a global pause with separate pauser/unpauser roles, and a fund recovery function for compliance seizures from non-allowlisted addresses. Allowlist and pause apply to `transfer`, `transferFrom`, `mint`, and `burn`. These are documented in detail on the [Extensions](/v2/developers/evm/stablecoin-oft/extensions#token-level-controls-on-erc20plus) page alongside the OFT-level extensions. ### ERC20Permit (EIP-2612) Built-in support for gasless approvals via signed messages. Users can authorize token spending by signing an off-chain message instead of submitting an on-chain `approve` transaction: ```solidity theme={null} function permit( address owner, address spender, uint256 value, uint256 deadline, uint8 v, bytes32 r, bytes32 s ) external; ``` Nonces are available via `nonces(address owner)`. ## Working with OFTs When `ERC20Plus` is used with the OFT Burn/Mint variant: 1. Deploy `ERC20Plus` on each chain 2. Deploy `OFTBurnMint` on each chain, pointing to the `ERC20Plus` token address 3. Grant `MINTER_ROLE` and `BURNER_ROLE` to the `OFTBurnMint` address on each chain's `ERC20Plus` 4. Set peers and LZ messaging configurations between `OFTBurnMint` contracts across chains The OFT uses configurable function selectors to call the token's mint/burn functions. For `ERC20Plus`, the default selectors are: * Mint: `0x40c10f19` (`mint(address,uint256)`) * Burn: `0x9dc29fac` (`burn(address,uint256)`) ## Next Steps * [OFTs](/v2/developers/evm/stablecoin-oft/ofts) for choosing the right variant * [RBAC Reference](/v2/developers/evm/stablecoin-oft/rbac-reference) for roles and access-controlled functions on `ERC20Plus` # Extensions Source: https://docs.layerzero.network/v2/developers/evm/stablecoin-oft/extensions Cross-chain extensions (Credit Redirect, Fee, Rate Limiter, PauseByID) and token-level controls (Allowlist, Pause). Stablecoin OFT enforces security policies at two levels (see [Architecture](/v2/developers/evm/stablecoin-oft/architecture)): * **Cross-chain extensions** (Credit Redirect, Fee, Rate Limiter, PauseByID) — mixed into the OFT via `OFTCoreExtendedRBACUpgradeable`. Fee, rate limit, and pause are configured per destination (EID); credit redirect is global. Together they intercept `_debit` and/or `_credit` on cross-chain sends and receives. * **Token controls** (Allowlist, Pause) — built into `ERC20Plus`, applied to **all** token operations including local transfers and mint/burn. Documented in detail on the [ERC20Plus](/v2/developers/evm/stablecoin-oft/erc20plus) page; summarized here for completeness. ## Overview | Module | Layer | Purpose | Granularity | Where Applied | | ------------------- | ----- | ----------------------------------------------------------------- | ------------------------- | ----------------------------------------------------- | | **Fee** | OFT | Collect basis-point fees on outbound transfers | Per-destination + default | `_debitView()` | | **Rate Limiter** | OFT | Token bucket rate limits with linear decay | Per-destination + default | `_debit()` and `_credit()` | | **PauseByID** | OFT | Halt transfers to/from specific destinations | Per-destination + default | `_debit()` modifier | | **Credit Redirect** | OFT | Redirect inbound credits for non-allowlisted recipients to escrow | Global (on OFT) | `_credit()` | | **Allowlist** | Token | Restrict token holders by address | Global (on `ERC20Plus`) | `transfer()` / `transferFrom()` / `mint()` / `burn()` | | **Pause** | Token | Halt all token operations globally | Global (on `ERC20Plus`) | `transfer()` / `transferFrom()` / `mint()` / `burn()` | ## Fee Module Collects fees in basis points (BPS) on outbound cross-chain transfers. Fees are deducted from the transfer amount before it reaches the destination chain. ### How It Works 1. User calls `send()` with `amountLD` 2. `_debitView()` calculates the fee: `fee = (amountLD * feeBps) / 10_000` 3. `amountReceivedLD = removeDust(amountLD - fee)` 4. `amountSentLD = amountLD` (the user pays the full amount) 5. The difference (`amountSentLD - amountReceivedLD`) is retained as fee ### Configuration **Default fee** applies to all destinations unless overridden: ```solidity theme={null} function setDefaultFeeBps(uint16 _feeBps) external; // FEE_CONFIG_MANAGER_ROLE ``` **Per-destination override:** ```solidity theme={null} function setFeeBps( uint256 _id, // Destination EID uint16 _feeBps, // Fee in BPS (0-10000) bool _enabled // true = use this override; false = fall back to default ) external; // FEE_CONFIG_MANAGER_ROLE ``` When `enabled` is `false`, the destination falls back to the default fee. **Fee settlement is push-based across all OFT variants.** When fees are collected during `_debit`, they are transferred immediately to the fee deposit address supplied at initialization. Treasury accounting should follow normal ERC20 `Transfer` (or native) inflows to that address rather than a separate withdrawal action. ### Constants ```solidity theme={null} uint16 public constant BPS_DENOMINATOR = 10_000; ``` A fee of 50 BPS = 0.50%. Setting `_feeBps > BPS_DENOMINATOR` reverts with `InvalidBps(feeBps)`. ### Roles | Role | Functions | | ------------------------- | ----------------------------------- | | `FEE_CONFIG_MANAGER_ROLE` | `setDefaultFeeBps()`, `setFeeBps()` | ## Rate Limiter Module Enforces transfer volume limits using a token bucket algorithm with linear decay. Supports per-destination limits for both outbound (send) and inbound (receive) directions. ### How It Works The rate limiter uses a token bucket model: 1. Outbound transfers consume capacity; inbound transfers replenish it (when net accounting is enabled) 2. Capacity regenerates linearly over the configured time window 3. If a transfer would exceed available capacity, it reverts with `RateLimitExceeded` **Example:** With a limit of 1,000,000 tokens and a window of 3,600 seconds (1 hour), the regeneration rate is \~277.78 tokens/second: * At t=0: Available = 1,000,000 * User sends 800,000 tokens. Available = 200,000 * At t=1800 (30 min): 500,000 regenerated. Available = 700,000 * At t=3600 (1 hr): Fully regenerated. Available = 1,000,000 * If 300,000 tokens arrive inbound at any point, available increases by 300,000 (capped at limit) ### Configuration **Global configuration:** ```solidity theme={null} function setRateLimitGlobalConfig(RateLimitGlobalConfig memory _globalConfig) external; // RATE_LIMITER_MANAGER_ROLE struct RateLimitGlobalConfig { bool useGlobalState; // Use single bucket for all destinations bool isGloballyDisabled; // Disable all rate limiting } ``` **Per-destination configuration:** ```solidity theme={null} function setRateLimitConfigs(SetRateLimitConfigParam[] calldata _params) external; // RATE_LIMITER_MANAGER_ROLE struct RateLimitConfig { bool overrideDefaultConfig; // true = use this config; false = use default bool outboundEnabled; // Enable outbound rate limit bool inboundEnabled; // Enable inbound rate limit bool netAccountingEnabled; // Offset outflow with inflows bool addressExemptionEnabled; // Allow per-address exemptions uint96 outboundLimit; // Max outbound tokens in window uint96 inboundLimit; // Max inbound tokens in window uint32 outboundWindow; // Outbound decay window (seconds) uint32 inboundWindow; // Inbound decay window (seconds) } ``` **Manual state override** (for emergency adjustments): ```solidity theme={null} function setRateLimitStates(SetRateLimitStateParam[] calldata _params) external; // RATE_LIMITER_MANAGER_ROLE struct RateLimitState { uint96 outboundUsage; // Current outbound usage uint96 inboundUsage; // Current inbound usage uint40 lastUpdated; // Timestamp (cannot be in the future) } ``` **Address exemptions:** ```solidity theme={null} function setRateLimitAddressExemptions( SetRateLimitAddressExceptionParam[] calldata _exemptions ) external; // RATE_LIMITER_MANAGER_ROLE struct SetRateLimitAddressExceptionParam { address user; bool isExempt; } ``` Exemptions only apply when `addressExemptionEnabled` is `true` in the destination's config. **Checkpoint** (call before changing limits or windows): ```solidity theme={null} function checkpointRateLimits(uint256[] calldata _ids) external; // RATE_LIMITER_MANAGER_ROLE ``` Writes decayed usages to storage so new config applies to the current state rather than stale values. ### Net vs Gross Accounting When `netAccountingEnabled` is `true`: * Outbound transfers reduce inbound usage (and vice versa) * This allows "round-trip" capacity: if 500k tokens leave and 500k arrive, net usage is zero When `netAccountingEnabled` is `false`: * Outbound and inbound are tracked independently * Each direction has its own separate bucket ### Scaling Rate limit amounts are stored as `uint96`. For tokens with amounts exceeding `type(uint96).max` (\~79 billion with 18 decimals), use the `SCALE_DECIMALS` constructor parameter to downscale amounts. For example, `SCALE_DECIMALS = 6` divides all amounts by `10^6` before storing. ### Roles | Role | Functions | | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | `RATE_LIMITER_MANAGER_ROLE` | `setRateLimitGlobalConfig()`, `setRateLimitConfigs()`, `setRateLimitStates()`, `setRateLimitAddressExemptions()`, `checkpointRateLimits()` | ## PauseByID Module Per-destination pause controls that halt outbound transfers to specific chains without affecting the rest of the network. ### How It Works The `_debit()` function includes a `whenNotPaused(_dstEid)` modifier. If the destination EID is paused, the transaction reverts with `Paused(uint256 id)`. Pause logic evaluates: 1. Is there a specific `PauseConfig` for this destination with `enabled = true`? 2. If yes, use that config's `paused` value 3. If no, use the `defaultPaused` value ### Configuration **Default pause** (applies to all destinations without specific config): ```solidity theme={null} function setDefaultPaused(bool _paused) external; // PAUSER_ROLE or UNPAUSER_ROLE ``` **Per-destination pause:** ```solidity theme={null} function setPaused(SetPausedParam[] calldata _params) external; // PAUSER_ROLE or UNPAUSER_ROLE struct SetPausedParam { uint256 id; // Destination EID bool paused; // Whether to pause bool enabled; // true = use this config; false = fall back to default } ``` ### Use Cases * **Chain compromise:** Pause a single destination without halting all cross-chain operations * **Maintenance:** Temporarily halt transfers to a chain during upgrades * **Regulatory action:** Block transfers to/from a specific chain ### Interaction with quoteOFT When a destination is paused, `quoteOFT()` returns `maxAmountLD = 0` in the `OFTLimit`, signaling to UIs that no transfer is possible. ## Credit Redirect When configured, inbound `_credit` checks an allowlist and, if the recipient is not allowlisted, credits an escrow address instead. The message still completes; the OFT emits `CreditRedirected(from, to, amountLD)` (`from` = intended recipient, `to` = escrow). `_credit` returns `0` for `amountReceivedLD` when redirected, so `OFTReceived` / compose are not treated as payment to the intended recipient. ```solidity theme={null} function setCreditRedirectConfig(CreditRedirectConfig calldata _config) external; // DEFAULT_ADMIN_ROLE // allowlist and escrow must both be set, or both address(0) to disable struct CreditRedirectConfig { address allowlist; // Must implement isAllowlisted(address) address escrow; // Receives redirected credits } ``` Point `allowlist` at the token (`ERC20Plus`) or another `isAllowlisted` contract. Keep `escrow` allowlisted so the mint or transfer succeeds. With redirect disabled, inbound credits follow normal token allowlist and pause rules on `mint` / transfer. Failed receives can be cleared with messaging channel ops (`nilify` / `skip`) — see [RBAC Reference](/v2/developers/evm/stablecoin-oft/rbac-reference). ## Token-Level Controls (on `ERC20Plus`) The following controls live on the token itself, not on the OFT. They apply to **all** token operations — local transfers and cross-chain sends alike. ### Allowlist The allowlist system operates in one of three modes at any time: | Mode | Behavior | Who Can Transfer | | ------------- | ----------------------------- | ------------------------------------- | | **Open** | No restrictions | Everyone | | **Blacklist** | Block specific addresses | Everyone except blacklisted addresses | | **Whitelist** | Allow only specific addresses | Only whitelisted addresses | **Mode transitions** are controlled by `DEFAULT_ADMIN_ROLE`. Switching modes does not clear existing lists — the blacklist and whitelist are maintained independently and apply only when their respective mode is active. Both lists are implemented as OpenZeppelin `EnumerableSet.AddressSet`, supporting: * `blacklistedCount()` / `whitelistedCount()` for total counts * `getBlacklist(offset, limit)` / `getWhitelist(offset, limit)` for paginated enumeration * `isBlacklisted(address)` / `isWhitelisted(address)` for individual queries The allowlist check (`isAllowlisted`) is enforced on `transfer` and `transferFrom` (sender and recipient), `mint` (recipient), and `burn` (source). | Role | Functions | | -------------------- | -------------------- | | `DEFAULT_ADMIN_ROLE` | `setAllowlistMode()` | | `BLACKLISTER_ROLE` | `setBlacklisted()` | | `WHITELISTER_ROLE` | `setWhitelisted()` | ### Fund Recovery For compliance scenarios (e.g., court orders, sanctions enforcement), addresses holding `DEFAULT_ADMIN_ROLE` can transfer tokens away from non-allowlisted addresses: ```solidity theme={null} function recoverFunds(address _from, address _to, uint256 _amount) external; ``` `_from` must NOT be allowlisted under the current mode. Attempting to recover from an allowlisted address reverts with `CannotRecoverFromAllowlisted(address user)`. ### Pause (Global) Halts all `transfer`, `transferFrom`, `mint`, and `burn` calls. Unlike `PauseByID` (which targets individual destinations), global pause blocks everything — local and cross-chain. | Role | Functions | | --------------- | ----------- | | `PAUSER_ROLE` | `pause()` | | `UNPAUSER_ROLE` | `unpause()` | The pause/unpause split ensures a compromised pauser key cannot also undo a legitimate security pause. ## Execution Order On an outbound `send()`, modules execute in this order: ``` 1. PauseByID → whenNotPaused(dstEid) modifier on _debit() 2. Fee → _debitView() calculates fee, reduces amountReceivedLD 3. Rate Limiter → _outflow() checks and updates outbound bucket 4. Token Transfer → burn/lock/wrap the tokens ``` On an inbound receive (`_lzReceive`): ``` 1. Rate Limiter → _inflow() checks and updates inbound bucket 2. Credit Redirect → _redirectCredit() (escrow if configured and recipient not allowlisted) 3. Token Transfer → mint/unlock/unwrap to recipient (or escrow) ``` ## Next Steps * [RBAC Reference](/v2/developers/evm/stablecoin-oft/rbac-reference) for the complete role-to-function mapping * [OFTs](/v2/developers/evm/stablecoin-oft/ofts) for deployable variants and initialization (including fee deposit) # OFT Variants Source: https://docs.layerzero.network/v2/developers/evm/stablecoin-oft/ofts Cross-chain transfer OFTs: BurnMint, BurnSelfMint, LockUnlock, and Native variants. Stablecoin OFT provides multiple OFT variants to support different token economics and deployment scenarios. Each variant implements a different cross-chain transfer model. All share the same extension stack (fee, rate limiting, pause). ## Decision Matrix | Scenario | OFT | Why | | --------------------------------------------------------- | ----------------- | --------------------------------------------------------------------- | | Token with permissioned burn and mint | `OFTBurnMint` | Burn on source, mint on destination. No locked collateral. | | Token with permissionless self-burn and permissioned mint | `OFTBurnSelfMint` | Transfers to OFT via allowance, then self-burns. Mint on destination. | | Existing token with supply on one chain | `OFTLockUnlock` | Lock on source, unlock on destination. No supply change. | | Native gas token (ETH, MATIC, etc.) | `OFTNative` | Wraps `msg.value` for cross-chain transfer. | | Target chain uses ERC20 for gas fees | **Alt variants** | Same logic but built for `EndpointV2Alt`. | ## OFTBurnMint Burns tokens on the source chain and mints them on the destination chain. Supports any token that exposes mint and burn functions with `(address, uint256)` parameters. The OFT must be granted the required roles (e.g., `MINTER_ROLE`, `BURNER_ROLE`) to call these functions. **Key feature:** Configurable function selectors allow the OFT to call non-standard mint/burn function names. ### Constructor Parameters | Parameter | Type | Description | | --------------------------- | --------- | -------------------------------------------------------------------------- | | `_token` | `address` | Underlying ERC20 token address (must implement `IERC20Metadata`) | | `_burnerMinter` | `address` | Contract with burn/mint capabilities (can differ from `_token`) | | `_endpoint` | `address` | LayerZero EndpointV2 address | | `_approvalRequired` | `bool` | Whether the OFT needs ERC20 approval to burn | | `_burnSelector` | `bytes4` | Function selector for burn, e.g., `0x9dc29fac` for `burn(address,uint256)` | | `_mintSelector` | `bytes4` | Function selector for mint, e.g., `0x40c10f19` for `mint(address,uint256)` | | `_rateLimiterScaleDecimals` | `uint8` | Decimals to scale rate limit amounts (usually `0`) | ### Common Selector Values | Function Signature | Selector | | ------------------------- | ------------ | | `mint(address,uint256)` | `0x40c10f19` | | `burn(address,uint256)` | `0x9dc29fac` | | `issue(address,uint256)` | `0x867904b4` | | `redeem(address,uint256)` | `0x1e9a6950` | ### Initialization Parameters | Parameter | Type | Description | | --------------- | --------- | ---------------------------------------------------------------- | | `_initialAdmin` | `address` | Address to be granted `DEFAULT_ADMIN_ROLE` and endpoint delegate | | `_feeDeposit` | `address` | Address that will receive any accrued fees | ```solidity theme={null} function initialize(address _initialAdmin, address _feeDeposit) public initializer; ``` ## OFTBurnSelfMint For tokens with a permissionless self-burn function (e.g., OpenZeppelin's `ERC20Burnable.burn(uint256)`) and a permissioned mint function. On the send path, the OFT transfers tokens from the user to itself via ERC20 allowance, then calls the self-burn selector to destroy them. On the receive path, it mints via the mint selector like `OFTBurnMint`. ### Constructor Parameters | Parameter | Type | Description | | --------------------------- | --------- | -------------------------------------------- | | `_token` | `address` | Token address that is also the burner/minter | | `_endpoint` | `address` | LayerZero EndpointV2 address | | `_burnSelector` | `bytes4` | Function selector for burn | | `_mintSelector` | `bytes4` | Function selector for mint | | `_rateLimiterScaleDecimals` | `uint8` | Decimals to scale rate limit amounts | ### Common Selector Values for OFTBurnSelfMint | Function Signature | Selector | | ------------------------ | ------------ | | `mint(address,uint256)` | `0x40c10f19` | | `burn(uint256)` | `0x42966c68` | | `issue(address,uint256)` | `0x867904b4` | | `redeem(uint256)` | `0xdb006a75` | ## OFTLockUnlock Locks tokens in the OFT contract on the source chain and unlocks (transfers) them from the OFT on the destination chain. No minting or burning occurs. ### Constructor Parameters | Parameter | Type | Description | | --------------------------- | --------- | ---------------------------------------------------------------- | | `_token` | `address` | Underlying ERC20 token address (must implement `IERC20Metadata`) | | `_endpoint` | `address` | LayerZero EndpointV2 address | | `_rateLimiterScaleDecimals` | `uint8` | Decimals to scale rate limit amounts | `approvalRequired` is always `true` for lock/unlock since users must approve the OFT to transfer their tokens.
An OApp's delegate can call the `skip` method via the Endpoint to stop message delivery: #### skip()
LayerZero provides [**IOTA L1 Move Packages**](https://github.com/LayerZero-Labs/LayerZero-v2/tree/main/packages/layerzero-v2/iota/contracts) that can communicate with the equivalent [Solidity Contract Libraries](/v2/developers/evm/overview) and [Solana Programs](/v2/developers/solana/overview) deployed on other chains. These packages, like their Solidity and Rust counterparts, simplify calling the [LayerZero Endpoint](../../concepts/protocol/layerzero-endpoint), provide message handling, interfaces for protocol configurations, and other utilities for interoperability: * **Omnichain Fungible Token (OFT)**: extends OApp with functionality for handling omnichain token transfers using IOTA L1's coin framework. * **Omnichain Application (OApp)**: the base package utilities for omnichain messaging and configuration. Each of these package standards implements common functions for **sending** and **receiving** omnichain messages. ## Differences from the Ethereum Virtual Machine The full differences between Solidity/EVM and IOTA L1/Move are significant. For comprehensive guides, see: * [IOTA Documentation](https://docs.iota.org/) * [Move Book](https://move-book.com/) * [IOTA Developer Basics](https://docs.iota.org/developer/iota-101)