OVault EVM Implementation

LZ_ENABLE_OVAULT_EXAMPLE=1 npx create-lz-oapp@latest --example ovault-evm

✔ Where do you want to start your project? … ./<YOUR_DIRECTORY>
? Which example would you like to use as a starting point? › - Use arrow-keys. Return to submit.
❯   OVault EVM
    OApp
    OFT
    OFTAdapter
    ONFT721

cp .env.example .env

const config: HardhatUserConfig = {
  networks: {
    base: {
      eid: EndpointId.BASESEP_V2_TESTNET,
      url: process.env.RPC_URL_BASESEP_TESTNET || 'https://base-sepolia.gateway.tenderly.co',
      accounts,
    },
    arbitrum: {
      eid: EndpointId.ARBSEP_V2_TESTNET,
      url: process.env.RPC_URL_ARBSEP_TESTNET || 'https://arbitrum-sepolia.gateway.tenderly.co',
      accounts,
    },
    optimism: {
      eid: EndpointId.OPTSEP_V2_TESTNET,
      url: process.env.RPC_URL_OPTSEP_TESTNET || 'https://optimism-sepolia.gateway.tenderly.co',
      accounts,
    },
  },
  // ... rest of config
};

// highlight-start
// Hub network where ERC4626 lives
const _hubEid = EndpointId.ARBSEP_V2_TESTNET;
// Spoke networks where ShareOFT lives (excluding hub)
const _spokeEids = [EndpointId.OPTSEP_V2_TESTNET, EndpointId.BASESEP_V2_TESTNET];
// highlight-end

// ============================================
// Deployment Export
// ============================================
// devtools/deployConfig.ts
export const DEPLOYMENT_CONFIG: DeploymentConfig = {
  // highlight-start
  vault: {
    contracts: {
      vault: 'MyERC4626',
      shareAdapter: 'MyShareOFTAdapter',
      composer: 'MyOVaultComposer',
    },
    deploymentEid: _hubEid,
    vaultAddress: undefined, // Existing ERC4626 vault
    assetOFTAddress: '<YOUR_ASSET_OFT_ADDRESS>', // Existing AssetOFT
    shareOFTAdapterAddress: undefined, // Deploy ShareOFTAdapter
  },
  // highlight-end

  // highlight-start
  // Share OFT configuration (only on spoke chains)
  shareOFT: {
    contract: 'MyShareOFT',
    metadata: {
      name: 'MyShareOFT',
      symbol: 'SHARE',
    },
    deploymentEids: _spokeEids,
  },
  // highlight-end

  // Asset OFT configuration (deployed on specified chains)
  assetOFT: {
    contract: 'MyAssetOFT',
    metadata: {
      name: 'MyAssetOFT',
      symbol: 'ASSET',
    },
    deploymentEids: [_hubEid, ..._spokeEids],
  },
} as const;

// devtools/deployConfig.ts
// highlight-start
// Hub network where ERC4626 lives
const _hubEid = EndpointId.ARBSEP_V2_TESTNET;
// Spoke networks where ShareOFT lives (excluding hub)
const _spokeEids = [EndpointId.OPTSEP_V2_TESTNET, EndpointId.BASESEP_V2_TESTNET];
// highlight-end

// ============================================
// Deployment Export
// ============================================
export const DEPLOYMENT_CONFIG: DeploymentConfig = {
  vault: {
    contracts: {
      vault: 'MyERC4626',
      shareAdapter: 'MyShareOFTAdapter',
      composer: 'MyOVaultComposer',
    },
    deploymentEid: _hubEid,
    // highlight-start
    vaultAddress: '<YOUR_VAULT_ADDRESS>', // Existing ERC4626 vault
    assetOFTAddress: '<YOUR_ASSET_OFT_ADDRESS>', // Existing AssetOFT token
    shareOFTAdapterAddress: undefined, // Deploy ShareOFTAdapter
    // highlight-end
  },

  // highlight-start
  // Share OFT configuration (only on spoke chains)
  shareOFT: {
    contract: 'MyShareOFT',
    metadata: {
      name: 'MyShareOFT',
      symbol: 'SHARE',
    },
    deploymentEids: _spokeEids,
  },
  // highlight-end

  // Asset OFT configuration (deployed on specified chains)
  assetOFT: {
    contract: 'MyAssetOFT',
    metadata: {
      name: 'MyAssetOFT',
      symbol: 'ASSET',
    },
    deploymentEids: [_hubEid, ..._spokeEids],
  },
} as const;

// devtools/deployConfig.ts
// highlight-start
// Hub network where ERC4626 lives
const _hubEid = EndpointId.ARBSEP_V2_TESTNET;
// Spoke networks where ShareOFT lives (excluding hub)
const _spokeEids = [EndpointId.OPTSEP_V2_TESTNET, EndpointId.BASESEP_V2_TESTNET];
// highlight-end

// ============================================
// Deployment Export
// ============================================
export const DEPLOYMENT_CONFIG: DeploymentConfig = {
    vault: {
    contracts: {
      vault: 'MyERC4626',
      shareAdapter: 'MyShareOFTAdapter',
      // highlight-start
      composer: 'MyOVaultComposer',
      // highlight-end
    },
    deploymentEid: _hubEid,
    // highlight-start
    vaultAddress: '<YOUR_VAULT_ADDRESS>',                       // Existing ERC4626 vault
    assetOFTAddress: '<YOUR_ASSET_OFT_ADDRESS>',                // Existing AssetOFT
    shareOFTAdapterAddress: <'YOUR_SHARE_OFT_ADAPTER_ADDRESS'>, // Existing ShareOFTAdapter
    // highlight-end
  },

  // Share OFT configuration (only on spoke chains)
  shareOFT: {
    contract: 'MyShareOFT',
    metadata: {
      name: 'MyShareOFT',
      symbol: 'SHARE',
    },
    deploymentEids: _spokeEids,
  },

  // Asset OFT configuration (deployed on specified chains OR use existing address)
  assetOFT: {
    contract: 'MyAssetOFT',
    metadata: {
      name: 'MyAssetOFT',
      symbol: 'ASSET',
    },
    deploymentEids: [_hubEid, ..._spokeEids],
  },
} as const;

const _hubEid = EndpointId.ARBSEP_V2_TESTNET;
const _spokeEids = [EndpointId.OPTSEP_V2_TESTNET, EndpointId.BASESEP_V2_TESTNET];

// ============================================
// Deployment Export
// ============================================
export const DEPLOYMENT_CONFIG: DeploymentConfig = {
  vault: {
    contracts: {
      vault: 'MyERC4626',
      shareAdapter: 'MyShareOFTAdapter',
      composer: 'MyOVaultComposer',
    },
    deploymentEid: _hubEid,
    // highlight-start
    vaultAddress: undefined,
    assetOFTAddress: undefined,
    shareOFTAdapterAddress: undefined,
    // highlight-end
  },

  // Share OFT configuration (only on spoke chains)
  ShareOFT: {
    contract: 'MyShareOFT',
    metadata: {
      name: 'MyShareOFT',
      symbol: 'SHARE',
    },
    deploymentEids: _spokeEids,
  },

  // Asset OFT configuration (deployed on specified chains)
  AssetOFT: {
    contract: 'MyAssetOFT',
    metadata: {
      name: 'MyAssetOFT',
      symbol: 'ASSET',
    },
    deploymentEids: [_hubEid, ..._spokeEids],
  },
} as const;

pnpm compile

pnpm hardhat lz:deploy --tags ovault

pnpm hardhat lz:oapp:wire --oapp-config layerzero.share.config.ts

# Configure LayerZero connections
pnpm hardhat lz:oapp:wire --oapp-config layerzero.asset.config.ts
pnpm hardhat lz:oapp:wire --oapp-config layerzero.share.config.ts

# Using the CLI task (recommended)
npx hardhat lz:ovault:send \
  --src-eid 30110 --dst-eid 30110 \
  --amount 100.0 --to 0xRecipient \
  --token-type asset

# Using the CLI task (recommended)
npx hardhat lz:ovault:send \
  --src-eid 30110 --dst-eid 30111 \
  --amount 100.0 --to 0xRecipient \
  --token-type asset

npx hardhat lz:ovault:send \
  --src-eid 30110 --dst-eid 30184 \
  --amount 100.0 --to 0xRecipient \
  --token-type asset

npx hardhat lz:ovault:send \
  --src-eid 30111 --dst-eid 30110 \
  --amount 50.0 --to 0xRecipient \
  --token-type share

npx hardhat lz:ovault:send \
  --src-eid 30111 --dst-eid 30184 \
  --amount 50.0 --to 0xRecipient \
  --token-type share

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);

// 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
    }
}

// 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 MyAssetOFT
 * @notice ERC20 representation of the vault's asset token on a spoke chain for crosschain 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 crosschain transfers of the
 * vault's asset tokens between the hub chain and spoke chains.
 *
 * 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 {
    /**
     * @notice Constructs the Asset OFT contract
     * @dev Initializes the OFT with LayerZero endpoint and sets up ownership
     * @param _name The name of the asset token
     * @param _symbol The symbol of the asset 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) {
        // NOTE: Uncomment the line below if you need to mint initial supply
        // This can be useful for testing or if the asset needs initial liquidity
        // _mint(msg.sender, 1 ether);
    }
}

// SPDX-License-Identifier: UNLICENSED
pragma solidity ^0.8.22;

import { Ownable } from "@openzeppelin/contracts/access/Ownable.sol";
import { ERC20 } from "@openzeppelin/contracts/token/ERC20/ERC20.sol";
import { IERC20 } from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
import { ERC4626 } from "@openzeppelin/contracts/token/ERC20/extensions/ERC4626.sol";

import { OFTAdapter } from "@layerzerolabs/oft-evm/contracts/OFTAdapter.sol";

/**
 * @title MyERC4626
 * @notice ERC4626 tokenized vault implementation for crosschain vault operations
 * @dev SECURITY CONSIDERATIONS:
 *      - Donation/inflation attacks on empty or low-liquidity vaults
 *      - Share price manipulation via large donations before first deposit
 *      - Slippage during deposit/redeem operations in low-liquidity conditions
 *      - First depositor advantage scenarios
 *
 *      See OpenZeppelin ERC4626 documentation for full risk analysis:
 *      https://docs.openzeppelin.com/contracts/4.x/erc4626#inflation-attack
 *
 *      MITIGATIONS:
 *      - OpenZeppelin v4.9+ includes virtual assets/shares to mitigate inflation attacks
 *      - Deployers should consider initial deposits to prevent manipulation
 */
contract MyERC4626 is ERC4626 {
    /**
     * @notice Creates a new ERC4626 vault
     * @dev Initializes the vault with virtual assets/shares protection against inflation attacks
     * @param _name The name of the vault token
     * @param _symbol The symbol of the vault token
     * @param _asset The underlying asset that the vault accepts
     */
    constructor(string memory _name, string memory _symbol, IERC20 _asset) ERC20(_name, _symbol) ERC4626(_asset) {}
}

/**
 * @title MyShareOFTAdapter
 * @notice OFT adapter for vault shares enabling crosschain transfers
 * @dev The share token MUST be an OFT adapter (lockbox).
 * @dev A mint-burn adapter would not work since it transforms `ShareERC20::totalSupply()`
 */
contract MyShareOFTAdapter is OFTAdapter {
    /**
     * @notice Creates a new OFT adapter for vault shares
     * @dev Sets up crosschain token transfer capabilities for vault shares
     * @param _token The vault share token to adapt for crosschain transfers
     * @param _lzEndpoint The LayerZero endpoint for this chain
     * @param _delegate The account with administrative privileges
     */
    constructor(
        address _token,
        address _lzEndpoint,
        address _delegate
    ) OFTAdapter(_token, _lzEndpoint, _delegate) Ownable(_delegate) {}
}

// SPDX-License-Identifier: UNLICENSED
pragma solidity ^0.8.22;

import { VaultComposerSync } from "@layerzerolabs/ovault-evm/contracts/VaultComposerSync.sol";

/**
 * @title MyOVaultComposer
 * @notice Crosschain vault composer enabling omnichain vault operations via LayerZero
 */
contract MyOVaultComposer is VaultComposerSync {
    /**
     * @notice Creates a new crosschain vault composer
     * @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 crosschain asset transfers
     * @param _shareOFT The OFT contract for crosschain share transfers
     */
    constructor(
        address _vault,
        address _assetOFT,
        address _shareOFT
    ) VaultComposerSync(_vault, _assetOFT, _shareOFT) {}
}

bytes memory composeMsg = abi.encode(
    SendParam({
        dstEid: targetChainEid,
        to: bytes32(recipientAddress),
        amountLD: 0, // Will be updated by composer
        minAmountLD: minOutputAmount, // Critical slippage protection
        extraOptions: optionsBuilder.addExecutorLzReceiveOption(200000, 0).build(),
        composeMsg: "",
        oftCmd: ""
    }),
    minMsgValue // Minimum msg.value for destination delivery
);

// Standard OFT send with compose message
assetOFT.send(
    SendParam({
        dstEid: hubEid,           // Always send to hub first
        to: bytes32(composer),    // VaultComposerSync address
        amountLD: depositAmount,
        minAmountLD: minDepositAmount,    // Slippage protection
        extraOptions: "...",      // Gas for compose + second hop
        composeMsg: composeMsg,  // Second SendParam + minMsgValue
        oftCmd: ""
    }),
    MessagingFee(msg.value, 0),
    refundAddress
);

function lzCompose(
    address _composeCaller,  // Either ASSET_OFT or SHARE_OFT
    bytes32 _guid,
    bytes calldata _message, // Contains routing instructions
    address _executor,
    bytes calldata _extraData
) external payable

// Decoded in handleCompose() - this controls Phase 2 behavior
(SendParam memory sendParam, uint256 minMsgValue) = abi.decode(
    _composeMsg,
    (SendParam, uint256)
);

// SendParam for vault output routing:
// - dstEid: Target chain for output tokens
// - to: Final recipient address
// - amountLD: Updated by composer to actual vault output
// - minAmountLD: CRITICAL - protects against vault rate slippage
// - extraOptions: Gas settings for destination transfer
// - composeMsg: Empty (no nested compose)
// - oftCmd: Empty (no OFT commands)

function _depositAndSend() {
    // 1. Deposit assets into vault
    uint256 shareAmount = VAULT.deposit(_assetAmount, address(this));

    // 2. Verify slippage protection
    _assertSlippage(shareAmount, _sendParam.minAmountLD);

    // 3. Route shares to final destination
    _send(SHARE_OFT, shareAmount, _refundAddress);
}

function _redeemAndSend() {
    // 1. Redeem shares from vault
    uint256 assetAmount = VAULT.redeem(_shareAmount, address(this), address(this));

    // 2. Verify slippage protection
    _assertSlippage(assetAmount, _sendParam.minAmountLD);

    // 3. Route assets to final destination
    _send(ASSET_OFT, assetAmount, _refundAddress);
}

function _send(address _oft, SendParam memory _sendParam, address _refundAddress) {
    if (_sendParam.dstEid == VAULT_EID) {
        // Same chain: Direct ERC20 transfer (no LayerZero fees)
        address erc20 = _oft == ASSET_OFT ? ASSET_ERC20 : SHARE_ERC20;
        IERC20(erc20).safeTransfer(_sendParam.to.bytes32ToAddress(), _sendParam.amountLD);
    } else {
        // Crosschain: Standard OFT send
        IOFT(_oft).send{ value: msg.value }(_sendParam, MessagingFee(msg.value, 0), _refundAddress);
    }
}

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);
}