DEVREL-782 Feat: support native composer in ovault example (#1840)

Author: St0rmBr3w

.changeset/thin-lizards-lick.md

@@ -0,0 +1,5 @@
+---
+"@layerzerolabs/ovault-evm-example": patch
+---
+
+Adds native OFT support (NativeOFTAdapter, StargatePoolNative) to OVault composer and send tasks.

examples/ovault-evm/README.md

@@ -16,6 +16,7 @@ Deploy **omnichain ERC-4626 vaults** that enable users to deposit assets from an
 
 - [Prerequisite Knowledge](#prerequisite-knowledge)
 - [Introduction](#introduction)
+- [Composer Types](#composer-types)
 - [Requirements](#requirements)
 - [Scaffold this Example](#scaffold-this-example)
 - [Helper Tasks](#helper-tasks)
@@ -45,6 +46,49 @@ OVault extends the ERC-4626 tokenized vault standard with LayerZero's omnichain
 
 OVault makes it extremely easy to move assets and shares between any supported chains, while also enabling cross-chain vault operations. Users can deposit assets from any chain to receive shares on any destination chain, redeem shares from any chain to receive assets on any destination chain, or simply transfer these tokens between chains - all through a unified interface.
 
+**Stargate Integration**: OVault is fully compatible with Stargate OFTs (USDC, USDT, etc.) as vault assets, with automatic decimal handling and no configuration required.
+
+## Composer Types
+
+OVault supports two types of composers to handle different asset types:
+
+### MyOVaultComposerERC20
+
+Use this composer when your vault's underlying asset is a standard **ERC20 token**:
+
+- Works with any ERC20-based OFT (e.g., Stargate USDC, USDT0, WBTC)
+- Direct integration with ERC-4626 vaults
+- Standard approval and transfer flow
+
+### MyOVaultComposerNative
+
+Use this composer when your vault's underlying asset is based on the **chain's native token** (e.g., ETH, HYPE):
+
+- Required for native token OFTs like `NativeOFTAdapter` or `StargatePoolNative`
+- Automatically wraps native tokens (ETH) into WETH before depositing to the vault
+- Necessary because ERC-4626 vaults only support ERC20 tokens
+- Transparent to end users - they send native tokens and receive shares
+
+> **Note**: This composer uses the WETH9 interface (`deposit()`/`withdraw()`) to convert between native and wrapped tokens. This works with standard implementations like ETH→WETH and HYPE→WHYPE. If your chain's wrapped native token uses a different interface, you must override the composer's `lzCompose()` function with the correct wrapping mechanism.
+
+> **Issuing Your Own Native Asset**: If you plan on issuing a bridged version of the chain's native asset yourself (i.e., not `StargatePoolNative` or an already deployed `NativeOFTAdapter`), use a `NativeOFTAdapter` instead of a standard OFT. See the [native-oft-adapter example](https://github.com/LayerZero-Labs/devtools/tree/main/examples/native-oft-adapter) for details.
+
+**Which Composer Should You Use?**
+
+The composer type depends on your asset OFT's underlying token:
+
+- If `assetOFT.token()` returns an ERC20 address → use `MyOVaultComposerERC20`
+- If `assetOFT.token()` returns `address(0)` (native token) → use `MyOVaultComposerNative`
+
+**Customizing Token Initialization**
+
+The parent `VaultComposerSync` contract provides overridable functions for custom token patterns:
+
+- `_initializeAssetToken()`: Override for non-standard asset token configurations
+- `_initializeShareToken()`: Override for non-standard share token configurations
+
+This is useful when your vault or OFT contracts don't follow the default patterns (e.g., custom ERC4626 vaults that accept ETH directly).
+
 ## Requirements
 
 - **git**
@@ -117,6 +161,13 @@ Configure your vault deployment in `devtools/deployConfig.ts`. This file control
 
 > **Note**: If your asset is already an OFT, you do not need to deploy a separate mesh. The only requirement is that the asset OFT supports the hub chain you are deploying to.
 
+> **Important - Composer Selection**: Choose the correct composer type based on your asset:
+>
+> - Use `MyOVaultComposerERC20` for standard ERC20 asset OFTs
+> - Use `MyOVaultComposerNative` for native token OFTs (e.g., `NativeOFTAdapter`, `StargatePoolNative`)
+>
+> See the [Composer Types](#composer-types) section for details.
+
 ```typescript
 import { EndpointId } from "@layerzerolabs/lz-definitions";
 
@@ -134,7 +185,7 @@ export const DEPLOYMENT_CONFIG = {
     contracts: {
       vault: "MyERC4626",
       shareAdapter: "MyShareOFTAdapter",
-      composer: "MyOVaultComposer",
+      composer: "MyOVaultComposerERC20", // Use MyOVaultComposerNative for native token assets
     },
     // IF YOU HAVE EXISTING CONTRACTS, SET THE ADDRESSES HERE
     vaultAddress: undefined, // Set to '0x...' to use existing vault
@@ -143,10 +194,11 @@ export const DEPLOYMENT_CONFIG = {
   },
 
   // Asset OFT configuration (deployed on specified chains OR use existing address)
+  // NOTE: For native assets (ETH, HYPE), use 'MyAssetOFTNative' with 'MyOVaultComposerNative'
   asset: {
-    contract: "MyAssetOFT",
+    contract: "MyAssetOFTERC20",
     metadata: {
-      name: "MyAssetOFT",
+      name: "MyAssetOFTERC20",
       symbol: "ASSET",
     },
     deploymentEids: [_hubEid, ..._spokeEids],
@@ -229,7 +281,7 @@ Compile your contracts:
 pnpm compile`
 ```
 
-> **Testing Note**: If you're deploying the asset OFT from scratch for testing purposes, you'll need to mint an initial supply. Uncomment the `_mint` line in the `MyAssetOFT` constructor to provide initial liquidity. This ensures you have tokens to test deposit and cross-chain transfer functionality.
+> **Testing Note**: If you're deploying the asset OFT from scratch for testing purposes, you'll need to mint an initial supply. Uncomment the `_mint` line in the `MyAssetOFTERC20` constructor to provide initial liquidity. This ensures you have tokens to test deposit and cross-chain transfer functionality.
 >
 > **⚠️ Warning**: Do NOT mint share tokens directly in `MyShareOFT`. Share tokens must only be minted by the vault contract during deposits to maintain the correct share-to-asset ratio. Manually minting share tokens breaks the vault's accounting and can lead to incorrect redemption values. The mint line in `MyShareOFT` should only be uncommented for UI/integration testing, never in production.
 
@@ -274,17 +326,17 @@ import { OAppEnforcedOption } from "@layerzerolabs/toolbox-hardhat";
 
 const optimismContract: OmniPointHardhat = {
   eid: EndpointId.OPTSEP_V2_TESTNET.valueOf(),
-  contractName: "MyAssetOFT",
+  contractName: "MyAssetOFTERC20",
 };
 
 const arbitrumContract: OmniPointHardhat = {
   eid: EndpointId.ARBSEP_V2_TESTNET.valueOf(),
-  contractName: "MyAssetOFT",
+  contractName: "MyAssetOFTERC20",
 };
 
 const baseContract: OmniPointHardhat = {
   eid: EndpointId.BASESEP_V2_TESTNET.valueOf(),
-  contractName: "MyAssetOFT",
+  contractName: "MyAssetOFTERC20",
 };
 
 // Configure gas limits for message execution
@@ -650,6 +702,30 @@ npx hardhat lz:ovault:send \
 - `--lz-compose-value`: Value for lzCompose operation (in wei)
 - `--oft-address`: Override source OFT address
 
+**Using Stargate Assets:**
+
+The OVault system is fully compatible with Stargate OFTs (e.g., USDC.e) as the underlying vault asset. To use Stargate assets, specify the Stargate pool/OFT address using the `--oft-address` parameter:
+
+```bash
+# Example: Deposit Stargate USDC from Ethereum to receive shares on Base
+npx hardhat lz:ovault:send \
+  --src-eid 30101 \
+  --dst-eid 30184 \
+  --amount 100 \
+  --to 0xYourRecipientAddress \
+  --token-type asset \
+  --oft-address 0xc026395860Db2d07ee33e05fE50ed7bD583189C7  # Stargate USDC pool on Ethereum
+```
+
+**Key points for Stargate integration:**
+
+- The `--oft-address` must point to the Stargate pool/OFT address on the source chain
+- Decimals are automatically detected (e.g., 6 decimals for USDC vs 18 for ETH)
+- No LayerZero config files needed - addresses are read from the deployed composer
+- Works with any Stargate asset that implements the IOFT interface
+- Find Stargate contract addresses in the [LayerZero OFT Ecosystem Docs](https://docs.layerzero.network/v2/deployments/oft-ecosystem-stargate-assets?stages=mainnet&issuers=Stargate)
+- Automatic slippage protection (0.5% default) for stablecoin transfers
+
 **Gas Optimization:**
 
 The task automatically optimizes gas limits based on operation type:

…ples/ovault-evm/contracts/MyAssetOFT.sol …ovault-evm/contracts/MyAssetOFTERC20.solexamples/ovault-evm/contracts/MyAssetOFT.sol renamed to examples/ovault-evm/contracts/MyAssetOFTERC20.sol examples/ovault-evm/contracts/MyAssetOFT.sol renamed to examples/ovault-evm/contracts/MyAssetOFTERC20.sol

@@ -5,7 +5,7 @@ import { Ownable } from "@openzeppelin/contracts/access/Ownable.sol";
 import { OFT } from "@layerzerolabs/oft-evm/contracts/OFT.sol";
 
 /**
- * @title MyAssetOFT
+ * @title MyAssetOFTERC20
  * @notice ERC20 representation of the vault's asset token on a spoke chain for cross-chain functionality
  * @dev This contract represents the vault's underlying asset on spoke chains. It inherits from
  * LayerZero's OFT (Omnichain Fungible Token) to enable seamless cross-chain transfers of the
@@ -14,7 +14,7 @@ import { OFT } from "@layerzerolabs/oft-evm/contracts/OFT.sol";
  * The asset OFT acts as a bridgeable ERC20 representation of the vault's collateral asset, allowing
  * users to move their assets across supported chains while maintaining fungibility.
  */
-contract MyAssetOFT is OFT {
+contract MyAssetOFTERC20 is OFT {
     /**
      * @notice Constructs the Asset OFT contract
      * @dev Initializes the OFT with LayerZero endpoint and sets up ownership

examples/ovault-evm/contracts/MyAssetOFTNative.sol

@@ -0,0 +1,35 @@
+// SPDX-License-Identifier: UNLICENSED
+pragma solidity ^0.8.20;
+
+import { Ownable } from "@openzeppelin/contracts/access/Ownable.sol";
+import { NativeOFTAdapter } from "@layerzerolabs/oft-evm/contracts/NativeOFTAdapter.sol";
+
+/**
+ * @title MyAssetOFTNative
+ * @notice NativeOFTAdapter for issuing a bridged version of the chain's native asset (e.g., ETH, HYPE)
+ *
+ * @dev WARNING: Only use this if you plan on issuing a bridged version of the chain's native asset yourself.
+ *      Most integrations should use existing native asset OFTs like `StargatePoolNative`.
+ *
+ * @dev WARNING: ONLY 1 NativeOFTAdapter should exist for a given global mesh, unless you make a
+ *      non-default implementation, which needs to be done very carefully.
+ *
+ * @dev This contract adapts the chain's native currency to OFT functionality for cross-chain transfers.
+ *      When used with MyOVaultComposerNative, the composer handles wrapping/unwrapping via WETH9 interface.
+ *      - `token()` returns `address(0)` indicating native asset
+ *      - `approvalRequired()` returns `false` since native transfers don't need ERC20 approval
+ */
+contract MyAssetOFTNative is NativeOFTAdapter {
+    /**
+     * @notice Constructs the Native Asset OFT Adapter
+     * @dev Initializes the NativeOFTAdapter with LayerZero endpoint and sets up ownership
+     * @param _localDecimals The decimals of the native token on this chain (18 for ETH, 18 for HYPE)
+     * @param _lzEndpoint The address of the LayerZero endpoint on this chain
+     * @param _delegate The address that will have owner privileges
+     */
+    constructor(
+        uint8 _localDecimals,
+        address _lzEndpoint,
+        address _delegate
+    ) NativeOFTAdapter(_localDecimals, _lzEndpoint, _delegate) Ownable(_delegate) {}
+}

…vault-evm/contracts/MyOVaultComposer.sol …-evm/contracts/MyOVaultComposerERC20.solexamples/ovault-evm/contracts/MyOVaultComposer.sol renamed to examples/ovault-evm/contracts/MyOVaultComposerERC20.sol examples/ovault-evm/contracts/MyOVaultComposer.sol renamed to examples/ovault-evm/contracts/MyOVaultComposerERC20.sol

@@ -7,12 +7,12 @@ import { VaultComposerSync } from "@layerzerolabs/ovault-evm/contracts/VaultComp
  * @title MyOVaultComposer
  * @notice Cross-chain vault composer enabling omnichain vault operations via LayerZero
  */
-contract MyOVaultComposer is VaultComposerSync {
+contract MyOVaultComposerERC20 is VaultComposerSync {
     /**
-     * @notice Creates a new cross-chain vault composer
+     * @notice Creates a new cross-chain vault composer where the vault asset is an ERC20 token
      * @dev Initializes the composer with vault and OFT contracts for omnichain operations
      * @param _vault The vault contract implementing ERC4626 for deposit/redeem operations
-     * @param _assetOFT The OFT contract for cross-chain asset transfers
+     * @param _assetOFT The OFT contract for cross-chain asset transfers of the vault asset
      * @param _shareOFT The OFT contract for cross-chain share transfers
      */
     constructor(address _vault, address _assetOFT, address _shareOFT) VaultComposerSync(_vault, _assetOFT, _shareOFT) {}

examples/ovault-evm/contracts/MyOVaultComposerNative.sol

@@ -0,0 +1,40 @@
+// SPDX-License-Identifier: UNLICENSED
+pragma solidity ^0.8.22;
+
+import { VaultComposerSyncNative } from "@layerzerolabs/ovault-evm/contracts/VaultComposerSyncNative.sol";
+
+/**
+ * @title MyOVaultComposerNative
+ * @notice Cross-chain vault composer enabling omnichain vault operations via LayerZero for native token assets
+ *
+ * @dev This composer uses the WETH9 interface (deposit/withdraw) to convert between native tokens and
+ *      wrapped native tokens. This works with standard implementations like ETH->WETH and HYPE->WHYPE.
+ *
+ * @dev IMPORTANT: OFT.token() != Vault.asset() in this scenario:
+ *      - The asset OFT returns address(0) for native tokens
+ *      - The vault asset is the wrapped native token (e.g., WETH)
+ *      - The composer handles the wrapping/unwrapping automatically
+ *
+ * @dev If your chain's wrapped native token does NOT follow the WETH9 interface, you must override
+ *      the lzCompose function to use the correct wrapping mechanism.
+ *
+ * @dev The parent contract provides overridable functions for custom token initialization:
+ *      - _initializeAssetToken(): Override for non-standard asset token patterns
+ *      - _initializeShareToken(): Override for non-standard share token patterns
+ */
+contract MyOVaultComposerNative is VaultComposerSyncNative {
+    /**
+     * @notice Creates a new cross-chain vault composer where the vault asset is the chain's native asset
+     * @dev Initializes the composer with vault and OFT contracts for omnichain operations
+     * @dev Requires the asset OFT to be a NativeOFTAdapter or StargatePoolNative contract (OFT.token() returns address(0))
+     * @dev Requires the vault's underlying asset to be a WETH9-compatible wrapped native token
+     * @param _vault The vault contract implementing ERC4626 for deposit/redeem operations (asset must be WETH)
+     * @param _assetOFT The NativeOFTAdapter or StargatePoolNative contract for cross-chain native asset transfers
+     * @param _shareOFT The OFT contract for cross-chain share transfers
+     */
+    constructor(
+        address _vault,
+        address _assetOFT,
+        address _shareOFT
+    ) VaultComposerSyncNative(_vault, _assetOFT, _shareOFT) {}
+}

examples/ovault-evm/deploy/MyOvault.ts

@@ -81,17 +81,33 @@ const deploy: DeployFunction = async (hre) => {
 
         if (DEPLOYMENT_CONFIG.vault.assetOFTAddress) {
             assetOFTAddress = DEPLOYMENT_CONFIG.vault.assetOFTAddress
-            console.log(`Using existing asset address: ${assetOFTAddress}`)
+            console.log(`Using existing asset OFT address: ${assetOFTAddress}`)
         } else {
             // Use deployed address or get from deployments
             assetOFTAddress =
                 deployedContracts.assetOFT || (await hre.deployments.get(DEPLOYMENT_CONFIG.assetOFT.contract)).address
-            console.log(`Using deployed asset address: ${assetOFTAddress}`)
-            // Fetch underlying ERC20 token address from the OFT using the IOFT artifact
-            const IOFTArtifact = await hre.artifacts.readArtifact('IOFT')
-            const oftContract = await hre.ethers.getContractAt(IOFTArtifact.abi, assetOFTAddress)
-            const assetTokenAddress = await oftContract.token()
-            console.log(`Underlying ERC20 token address found from OFT deployment: ${assetTokenAddress}`)
+            console.log(`Using deployed asset OFT address: ${assetOFTAddress}`)
+        }
+
+        // Fetch underlying ERC20 token address from the OFT using the IOFT artifact
+        const IOFTArtifact = await hre.artifacts.readArtifact('IOFT')
+        const oftContract = await hre.ethers.getContractAt(IOFTArtifact.abi, assetOFTAddress)
+        const oftTokenAddress = await oftContract.token()
+
+        // Handle native token OFTs (NativeOFTAdapter, StargatePoolNative) where token() returns address(0)
+        let assetTokenAddress: string
+        if (oftTokenAddress === hre.ethers.constants.AddressZero) {
+            if (!DEPLOYMENT_CONFIG.vault.assetTokenAddress) {
+                throw new Error(
+                    `Native asset OFT detected (token() returns address(0)), but vault.assetTokenAddress is not configured. ` +
+                        `For native assets, you must set vault.assetTokenAddress to the WETH address on this chain.`
+                )
+            }
+            assetTokenAddress = DEPLOYMENT_CONFIG.vault.assetTokenAddress
+            console.log(`Native asset OFT detected - using configured WETH address: ${assetTokenAddress}`)
+        } else {
+            assetTokenAddress = oftTokenAddress
+            console.log(`Underlying ERC20 token address found from OFT: ${assetTokenAddress}`)
         }
 
         // Get vault address (existing or deploy new)
@@ -107,7 +123,7 @@ const deploy: DeployFunction = async (hre) => {
                 args: [
                     DEPLOYMENT_CONFIG.shareOFT.metadata.name,
                     DEPLOYMENT_CONFIG.shareOFT.metadata.symbol,
-                    assetOFTAddress,
+                    assetTokenAddress,
                 ],
                 log: true,
                 skipIfAlreadyDeployed: true,

examples/ovault-evm/devtools/deployConfig.ts

@@ -37,7 +37,7 @@ export const DEPLOYMENT_CONFIG: DeploymentConfig = {
         contracts: {
             vault: 'MyERC4626',
             shareAdapter: 'MyShareOFTAdapter',
-            composer: 'MyOVaultComposer',
+            composer: 'MyOVaultComposerERC20',
         },
         // IF YOU HAVE EXISTING CONTRACTS, SET THE ADDRESSES HERE
         // This will skip deployment and use your existing hubEid contract deployments instead
@@ -47,6 +47,9 @@ export const DEPLOYMENT_CONFIG: DeploymentConfig = {
         assetOFTAddress: undefined, // Set to '0xdef...' to use existing asset OFT
         // This must be the address of the ShareOFTAdapter
         shareOFTAdapterAddress: undefined, // Set to '0xghi...' to use existing ShareOFTAdapter
+        // Required for native token OFTs (NativeOFTAdapter, StargatePoolNative) where token() returns address(0)
+        // Set this to the WETH address on the hub chain (e.g., '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2' for Ethereum mainnet)
+        assetTokenAddress: undefined,
     },
 
     // Share OFT configuration (only on spoke chains)
@@ -60,10 +63,11 @@ export const DEPLOYMENT_CONFIG: DeploymentConfig = {
     },
 
     // Asset OFT configuration (deployed on specified chains OR use existing address)
+    // NOTE: For native assets (ETH, HYPE), use 'MyAssetOFTNative' with 'MyOVaultComposerNative'
     assetOFT: {
-        contract: 'MyAssetOFT',
+        contract: 'MyAssetOFTERC20',
         metadata: {
-            name: 'MyAssetOFT',
+            name: 'MyAssetOFTERC20',
             symbol: 'ASSET',
         },
         deploymentEids: [_hubEid, ..._spokeEids],

examples/ovault-evm/devtools/types.ts

@@ -17,6 +17,7 @@ export interface VaultConfig {
     vaultAddress?: string // Optional pre-deployed vault address
     assetOFTAddress?: string // Optional pre-deployed asset OFT address
     shareOFTAdapterAddress?: string // Optional pre-deployed ShareOFTAdapter address
+    assetTokenAddress?: string // Optional: Required when asset OFT is native (token() returns address(0)), set to WETH address
 }
 
 export interface DeploymentConfig {