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 = {
  zircuit: {
    usdc: "0x3b952c8C9C44e8Fe201e2b26F6B2200203214cfF",
    vaultComposer: "0xa41f912a9AF4c086a6fefa5630305B44bbDfC6ef",
    vault: "0x91E6aD7CB1287eB9F6156F5969FD94292F0c7F20",
    underlyingOFT: "0xE76aa05D2cD49aeC3e1cb87Fa8B943b38522b10d",
  },
  base: {
    usdc: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    vaultToken: "0xB3589d27214fF92F40bacb6e8F2087D3FfE6113E",
    underlyingAdapter: "0x322Aa541C733661737AbF973Bc896965177B761b",
  },
};

// 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.zircuit.com");
  
  // Connect to Vault (on Zircuit)
  const vault = new Contract(
    CONTRACTS.zircuit.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.zircuit.com");
  const vault = new Contract(
    CONTRACTS.zircuit.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 zircuitRpcUrl = process.env.ZIRCUIT_RPC_URL ?? "https://mainnet.zircuit.com";
  const privateKey = process.env.PRIVATE_KEY;
  if (!privateKey) throw new Error("Missing PRIVATE_KEY env var");

  const baseProvider = new JsonRpcProvider(baseRpcUrl);
  const zircuitProvider = new JsonRpcProvider(zircuitRpcUrl);
  const baseSigner = new Wallet(privateKey, baseProvider);
  const zircuitSigner = new Wallet(privateKey, zircuitProvider);

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

  const owner = await baseSigner.getAddress();
  const currentAllowance = await usdc.allowance(
    owner,
    CONTRACTS.base.underlyingAdapter
  );
  

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

  // Second hop, ZRC -> BASE
  const secondHopSendParam = {
    dstEid: LZ_EID.base, // 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.zircuit.vaultComposer,
    VaultComposerABI,
    zircuitProvider
  );
  const secondHopQuote = await vaultComposer.quoteSend(
    await zircuitSigner.getAddress(),
    CONTRACTS.zircuit.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 Base: 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.zircuit.com");
  const vault = new Contract(
    CONTRACTS.zircuit.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 zircuitRpcUrl = process.env.ZIRCUIT_RPC_URL ?? "https://mainnet.zircuit.com";
  const privateKey = process.env.PRIVATE_KEY;
  if (!privateKey) throw new Error("Missing PRIVATE_KEY env var");

  const baseProvider = new JsonRpcProvider(baseRpcUrl);
  const zircuitProvider = new JsonRpcProvider(zircuitRpcUrl);
  const baseSigner = new Wallet(privateKey, baseProvider);
  const zircuitSigner = new Wallet(privateKey, zircuitProvider);
  const signerAddress = await baseSigner.getAddress();

  // VaultToken (shares) on BASE
  const vaultToken = new Contract(CONTRACTS.base.vaultToken, VaultTokenABI, baseSigner);

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

  // 1) Quote second hop (VaultComposer redeem -> underlying destination) fee on Zircuit
  const secondHopSendParam = {
    dstEid: LZ_EID.base,
    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.zircuit.underlyingOFT,
    UnderlyingOFTABI,
    zircuitProvider
  );

  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.zircuit,
    to: ethers.zeroPadValue(ethers.getAddress(CONTRACTS.zircuit.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;
}