Vault Integration Guide

This guide will walk you through integrating the cross-chain vault system into your DeFi application. Whether you're building a portfolio dashboard, a yield optimizer, or a wallet interface, this guide provides the architecture you need to offer seamless cross-chain vault interactions. The vaults leverage the ERC-4626 standard.

Frontend Implementation

1. Setup: Web3 Provider & Contracts

import {
  AbiCoder,
  Contract,
  JsonRpcProvider,
  formatUnits,
  parseUnits,
  Wallet,
  ethers,
} from "ethers";
import { Options } from "@layerzerolabs/lz-v2-utilities";

// Contract ABIs (import from artifacts)
import VaultABI from './abis/Vault.json';
import VaultComposerABI from './abis/VaultComposer.json';
import VaultTokenABI from './abis/VaultToken.json';
import UnderlyingOFTABI from "./abis/UnderlyingOFT.json";
import ERC20ABI from './abis/ERC20.json';
import VaultComposerABI from "./abis/VaultComposer.json"

// Contract addresses by chain
const CONTRACTS = {
  base: {
    usdc: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    vaultComposer: "0xBb801ED781dF31F660cC743bEf7Bb9D04B030923",
    vault: "0x03067bbD0d41E3Fe4A0bb6ca67c99e7352Da4CAE",
    underlyingOFT: "0xd7aBC360dfcF1B6dD0a03138235e12A2bc1c1C8B",
  },
  eth: {
    usdc: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    vaultToken: "0x07C898e77310870770f88d18a01009cB65A1c1a9",
    underlyingAdapter: "0xd58E8c1c83d598aD76B5f0E26B4a25cdB885d190",
  },
};

// LayerZero Endpoint IDs
const LZ_EID = {
  zircuit: 30303,
  mainnet: 30101,
  base: 30184,
};

2. Fetching Vault Data

async function getVaultData() {
  const provider = new JsonRpcProvider("https://mainnet.base.org");
  
  // Connect to Vault (on Base)
  const vault = new Contract(
    CONTRACTS.base.vault,
    VaultABI,
    provider
  );
  
  // Fetch vault state
  const [totalAssets, totalShares] = await Promise.all([
    vault.totalAssets(),
    vault.totalSupply(),
  ]);

  const sharePrice = 
  totalShares === 0n ? 0n : (totalAssets * parseUnits("1", 18)) / totalShares;
  
  return {
    totalAssets: formatUnits(totalAssets, 6), // USDC decimals
    totalShares: formatUnits(totalShares, 6),
    sharePrice: formatUnits(sharePrice, 18),
  };
}

3. Preview Deposit

async function previewDeposit(assetAmount: string): Promise<{ assetsIn: bigint, sharesOut: bigint }> {
  const provider = new JsonRpcProvider("https://mainnet.base.org");
  const vault = new Contract(
    CONTRACTS.base.vault,
    VaultABI,
    provider
  );
  
  const assets = parseUnits(assetAmount, 6); // USDC decimals
  const shares = await vault.previewDeposit(assets);
  
  return {
    assetsIn: assets,
    sharesOut: shares,
  };
}

4. Execute Deposit (Cross-Chain)

async function deposit(
  assetAmount: string,
  userAddress: string,
) {
  const baseRpcUrl = process.env.BASE_RPC_URL ?? "https://mainnet.base.org";
  const ethRpcUrl = process.env.ETH_RPC_URL ?? "https://eth.drpc.org";
  const privateKey = process.env.PRIVATE_KEY;
  if (!privateKey) throw new Error("Missing PRIVATE_KEY env var");

  const baseProvider = new JsonRpcProvider(baseRpcUrl);
  const ethProvider = new JsonRpcProvider(ethRpcUrl);
  const baseSigner = new Wallet(privateKey, baseProvider);
  const ethSigner = new Wallet(privateKey, ethProvider);

  const adapter = new Contract(
    CONTRACTS.eth.underlyingAdapter,
    UnderlyingAdapterABI,
    ethSigner
  );
  
  // 1. Approve USDC
  const usdc = new Contract(
    CONTRACTS.eth.usdc,
    ERC20ABI,
    baseSigner
  );

  const owner = await ethSigner.getAddress();
  const currentAllowance = await usdc.allowance(
    owner,
    CONTRACTS.eth.underlyingAdapter
  );
  

  const assets = parseUnits(assetAmount, 6);
  if (currentAllowance < assets) {
    const approveTx = await usdc.approve(CONTRACTS.eth.underlyingAdapter, assets);
    await approveTx.wait();
  }
  
  // 2. Quote second hop (BASE -> ETH) LayerZero fee
  const { assetsIn, sharesOut } = await previewDeposit(assetAmount);
  const minSharesOut = (sharesOut * 98n) / 100n; // 2% slippage

  // Second hop, BASE -> ETH
  const secondHopSendParam = {
    dstEid: LZ_EID.ETH, // chain we want the shares to be sent to
    to: ethers.zeroPadValue(ethers.getAddress(userAddress), 32), // address to receive the shares
    amountLD: 0n, // 0 means use all received
    minAmountLD: minSharesOut,
    extraOptions: "0x",
    composeMsg: "0x",
    oftCmd: "0x",
  };
  
  const vaultComposer = new Contract(
    CONTRACTS.base.vaultComposer,
    VaultComposerABI,
    baseProvider
  );
  const secondHopQuote = await vaultComposer.quoteSend(
    await baseSigner.getAddress(),
    CONTRACTS.base.vault,
    assetsIn,
    secondHopSendParam
  );

  const secondHopFee = (secondHopQuote.nativeFee * (130n)) / 100n;

  // 3. first hop (BASE -> ZRC)
  const composeMsg = AbiCoder.defaultAbiCoder().encode(
    [
      "tuple(uint32 dstEid, bytes32 to, uint256 amountLD, uint256 minAmountLD, bytes extraOptions, bytes composeMsg, bytes oftCmd)",
      "uint256",
    ],
    [secondHopSendParam, secondHopFee]
  );

  // Prepare SendParam struct for the first hop (underlying to VaultComposer)
  const [configuredVaultComposerAddress, configuredVaultComposerEid] =
    await adapter.getVaultComposerConfig();

  const lzComposeGas = 300000;
  const extraOptions = Options.newOptions()
    .addExecutorComposeOption(0, lzComposeGas, secondHopFee)
    .toHex();

  const sendParam = {
    dstEid: configuredVaultComposerEid,
    to: configuredVaultComposerAddress,
    amountLD: assetsIn,
    minAmountLD: assetsIn,
    extraOptions,
    composeMsg: composeMsg,
    oftCmd: "0x",
  };

  // First hop is on ETH: quote the underlying adapter fee
  const firstHopQuote = await adapter.quoteSend(sendParam, false);
  const firstHopFee = firstHopQuote.nativeFee;
  const messagingFee = {
    nativeFee: firstHopFee,
    lzTokenFee: 0n,
  };
  const sendTx = await adapter.send(sendParam, messagingFee, userAddress, {
    value: firstHopFee,
  });

  const receipt = await sendTx.wait();
  return receipt;
}

5. Preview Withdraw

async function previewWithdraw(shareAmount: string): Promise<{ sharesIn: bigint, assetsOut: bigint }> {
  const provider = new JsonRpcProvider("https://mainnet.base.org");
  const vault = new Contract(
    CONTRACTS.base.vault,
    VaultABI,
    provider
  );
  
  const shares = parseUnits(shareAmount, 18);
  const assets = await vault.previewRedeem(shares);
  
  return {
    sharesIn: shares,
    assetsOut: assets,
  };
}

6. Execute Withdraw (Cross-Chain)

async function withdraw(
  shareAmount: string,
  userAddress: string
) {
  const baseRpcUrl = process.env.BASE_RPC_URL ?? "https://mainnet.base.org";
  const ethRpcUrl = process.env.ETH_RPC_URL ?? "https://eth.drpc.org";
  const privateKey = process.env.PRIVATE_KEY;
  if (!privateKey) throw new Error("Missing PRIVATE_KEY env var");

  const baseProvider = new JsonRpcProvider(baseRpcUrl);
  const ethProvider = new JsonRpcProvider(ethRpcUrl);
  const baseSigner = new Wallet(privateKey, baseProvider);
  const ethSigner = new Wallet(privateKey, ethProvider);
  const signerAddress = await ethSigner.getAddress();

  // VaultToken (shares) on ETH
  const vaultToken = new Contract(CONTRACTS.eth.vaultToken, VaultTokenABI, ethSigner);

  const { sharesIn, assetsOut } = await previewWithdraw(shareAmount);
  const minAssetsOut = (assetsOut * 98n) / 100n; // 2% slippage

  // 1) Quote second hop (VaultComposer redeem -> underlying destination) fee on BASE
  const secondHopSendParam = {
    dstEid: LZ_EID.eth,
    to: ethers.zeroPadValue(ethers.getAddress(userAddress), 32),
    amountLD: 0n, // set by VaultComposer based on redeemed amount
    minAmountLD: minAssetsOut,
    extraOptions: "0x",
    composeMsg: "0x",
    oftCmd: "0x",
  };

  const underlyingOFT = new Contract(
    CONTRACTS.base.underlyingOFT,
    UnderlyingOFTABI,
    baseProvider
  );

  const secondHopQuote = await underlyingOFT.quoteSend(
    { ...secondHopSendParam, amountLD: assetsOut },
    false
  );
  const secondHopFee = (secondHopQuote.nativeFee * (130n)) / 100n;
  const composeMsg = AbiCoder.defaultAbiCoder().encode(
    [
      "tuple(uint32 dstEid, bytes32 to, uint256 amountLD, uint256 minAmountLD, bytes extraOptions, bytes composeMsg, bytes oftCmd)",
      "uint256",
    ],
    [secondHopSendParam, secondHopFee]
  );

  // 2) Build first hop (shares -> VaultComposer) SendParam + extraOptions (compose enabled)
  const lzComposeGas = 300000;
    const extraOptions = Options.newOptions()
      .addExecutorComposeOption(0, lzComposeGas, secondHopFee)
      .toHex();

  const sendParam = {
    dstEid: LZ_EID.base,
    to: ethers.zeroPadValue(ethers.getAddress(CONTRACTS.base.vaultComposer), 32),
    amountLD: sharesIn,
    minAmountLD: 0n, // no min for sending shares
    extraOptions,
    composeMsg,
    oftCmd: "0x",
  };

  // 3) Quote + send (msg.value must include first hop fee + second hop forwarded value)
  const firstHopQuote = await vaultToken.quoteSend(sendParam, false);
  const firstHopFee = firstHopQuote.nativeFee;

  const refundAddress = process.env.REFUND_ADDRESS ?? signerAddress;

  const messagingFee = {
    nativeFee: firstHopFee,
    lzTokenFee: 0n,
  };

  const sendTx = await vaultToken.send(sendParam, messagingFee, refundAddress, {
    value: firstHopFee,
  });
  const receipt = await sendTx.wait();
  return receipt;
}

---

Error Handling

Common Errors

const ERRORS = {
  // ERC20 errors
  INSUFFICIENT_ALLOWANCE: 'Please approve USDC spending',
  INSUFFICIENT_BALANCE: 'Insufficient USDC balance',
  
  // Vault errors
  DEPOSIT_PAUSED: 'Deposits are currently paused',
  WITHDRAWAL_PAUSED: 'Withdrawals are currently paused',
  MIN_AMOUNT: 'Amount below minimum deposit',
  MAX_AMOUNT: 'Amount exceeds maximum deposit',
  
  // LayerZero errors
  INSUFFICIENT_FEE: 'Insufficient LayerZero fee',
  INVALID_DESTINATION: 'Invalid destination chain',
  
  // Slippage
  SLIPPAGE_EXCEEDED: 'Price moved unfavorably, try again',
};

function handleError(error: any) {
  const errorString = error.toString();
  
  if (errorString.includes('ERC20: insufficient allowance')) {
    return ERRORS.INSUFFICIENT_ALLOWANCE;
  }
  if (errorString.includes('ERC20: transfer amount exceeds balance')) {
    return ERRORS.INSUFFICIENT_BALANCE;
  }
  if (errorString.includes('Pausable: paused')) {
    return ERRORS.DEPOSIT_PAUSED;
  }
  if (errorString.includes('MinShareAmountNotMet')) {
    return ERRORS.SLIPPAGE_EXCEEDED;
  }
  
  return 'Transaction failed: ' + error.message;
}