Vaults Frontend Integration

This guide provides third-party developers with everything needed to integrate Lagoon Vaults data into their frontends.

Data Sources Overview

Lagoon Vault data comes from three primary sources:

Data Type	Source	Access Method
Vault Configuration	Environment Variables	Environment Variables
Real-time Blockchain Data	Smart Contracts	RPC Calls
Computed Metrics	Event Processing	Subgraph + Calculations

Data sources

1. Get All Vaults

VAULTS=[] in .env

Response Structure:

interface Vault {
  address: string;           // Vault contract address
  chainId: number;          // Blockchain network ID
  name?: string;            // Vault display name
  logoUrl?: string;         // Vault logo URL
  shortDescription?: string; // Brief description
  description?: string;     // Full description
  averageProcessing?: string; // Settlement time
  referralShare?: string;   // Referral percentage
  assetManager?: {          // Curator information
    name: string;
    url: string;
  };
  asset?: {                 // Underlying asset
    symbol: string;
    address: string;
    decimals: number;
    chainId: number;
  };
  points?: Array<{          // Reward points
    name: string;
    value: string;
    icon: string;
  }>;
  additionalAprs?: Array<{  // Additional yield sources
    asset: string;
    estimatedRewardApr?: string;
    estimatedReward30dApr?: string;
  }>;
  visible: boolean;
}

2. Get Specific Vault

Filter on chaindId and address

3. Get Vault Events (for APR calculation)

Subgraph graphQL query

4. Get price feed

From NEXT_PUBLIC_ASSETS

Environment Configuration

Vault Configuration

Vaults are defined in the VAULTS environment variable:

[
  {
    "address": "0x5864672c5e37E4E58c261014F8E94Ee31f575d47",
    "chainId": 42161,
    "logoUrl": "/9summits.png",
    "shortDescription": "ETH yield strategies",
    "description": "Detailed strategy description...",
    "averageProcessing": "7 days",
    "referralShare": "15%",
    "assetManager": {
      "name": "9Summits",
      "url": "https://www.9summits.io"
    },
    "visible": true,
    "points": [
      {
        "name": "Eigenlayer Points",
        "value": "3x",
        "icon": "https://example.com/icon.png"
      }
    ]
  }
]

Asset Configuration

Assets are defined in NEXT_PUBLIC_ASSETS:

{
  "WETH": {
    "priceFeed": {
      "address": "0x5f4eC3Df9cbd43714FE2740f5E3616155c5b8419",
      "chainId": 1
    },
    "logo": "/weth.svg"
  }
}

Events configuration

query VaultEvents($first: Int!, $vaultAddress: Bytes!) {
    deposits(
      first: $first
      orderBy: blockTimestamp
      orderDirection: desc
      where: { vault: $vaultAddress }
    ) {
      assets
      blockNumber
      blockTimestamp
      id
      owner
      sender
      shares
      transactionHash
      vault
      logIndex
    }
    withdraws(
      first: $first
      orderBy: blockTimestamp
      orderDirection: desc
      where: { vault: $vaultAddress }
    ) {
      assets
      blockNumber
      blockTimestamp
      id
      owner
      receiver
      sender
      shares
      transactionHash
      vault
      logIndex
    }
    depositRequests(
      first: $first
      orderBy: blockTimestamp
      orderDirection: desc
      where: { vault: $vaultAddress }
    ) {
      assets
      blockNumber
      blockTimestamp
      id
      owner
      sender
      transactionHash
      controller
      requestId
      vault
      logIndex
    }
    redeemRequests(
      first: $first
      orderBy: blockTimestamp
      orderDirection: desc
      where: { vault: $vaultAddress }
    ) {
      blockNumber
      blockTimestamp
      id
      owner
      sender
      shares
      transactionHash
      controller
      requestId
      vault
      logIndex
    }
    settleRedeems(
      first: $first
      orderBy: blockTimestamp
      orderDirection: desc
      where: { vault: $vaultAddress }
    ) {
      assetsWithdrawed
      blockNumber
      blockTimestamp
      epochId
      id
      settledId
      sharesBurned
      totalAssets
      totalSupply
      transactionHash
      vault
      logIndex
    }
    settleDeposits(
      first: $first
      orderBy: blockTimestamp
      orderDirection: desc
      where: { vault: $vaultAddress }
    ) {
      assetsDeposited
      blockNumber
      blockTimestamp
      epochId
      id
      settledId
      sharesMinted
      totalSupply
      totalAssets
      transactionHash
      vault
      logIndex
    }
    totalAssetsUpdateds(
      first: $first
      orderBy: blockTimestamp
      orderDirection: desc
      where: { vault: $vaultAddress }
    ) {
      transactionHash
      totalAssets
      id
      blockNumber
      blockTimestamp
      vault
      logIndex
    }
    newTotalAssetsUpdateds(
      first: $first
      orderBy: blockTimestamp
      orderDirection: desc
      where: { vault: $vaultAddress }
    ) {
      transactionHash
      totalAssets
      totalSupply
      id
      blockNumber
      blockTimestamp
      vault
      logIndex
    }
    totalAssetsUpdateds(
      first: $first
      orderBy: blockTimestamp
      orderDirection: desc
      where: { vault: $vaultAddress }
    ) {
      transactionHash
      totalAssets
      totalSupply
      id
      blockNumber
      blockTimestamp
      logIndex
    }
    periodSummaries(
      first: $first
      orderBy: blockNumber
      orderDirection: desc
      where: { vault: $vaultAddress }
    ) {
      id
      blockTimestamp
      blockNumber
      totalAssetsAtStart
      totalSupplyAtStart
      previousPeriodNetTotalSupplyAtEnd
      previousPeriodTotalAssetsAtEnd
      previousPeriodTotalSupplyAtEnd
      vault
    }
  }

Blockchain Data Access

Key Contract Functions

1. Vault Information to complete .env data

// Get vault state
const vaultState = await publicClient.readContract({
  address: vaultAddress,
  abi: vaultAbi,
  functionName: 'totalAssets' | 'totalSupply' | 'paused'
});

// Get price per share
const pricePerShare = await publicClient.readContract({
  address: vaultAddress,
  abi: vaultAbi,
  functionName: 'convertToAssets',
  args: [parseUnits('1', vaultDecimals)]
});

2. Asset Information for tvl calculation

// Get asset price from Chainlink
const assetPrice = await publicClient.readContract({
  address: priceFeedAddress,
  abi: chainlinkAbi,
  functionName: 'latestRoundData'
});

Data Integration Examples

1. Vault APR (Computed)

APR is calculated from historical vault events:

// Fetch vault events for APR calculation from the alchemy subgraph

// APR calculation logic (simplified)
function calculateAPR(events, vault) {
  const settlements = events.settleDeposits.concat(events.settleRedeems)
    .sort((a, b) => Number(a.blockTimestamp) - Number(b.blockTimestamp));
  
  if (settlements.length < 2) return 0;
  
  const newest = settlements[settlements.length - 1];
  const oldest = settlements[0];
  
  const timeSpan = Number(newest.blockTimestamp) - Number(oldest.blockTimestamp);
  const priceChange = newest.pricePerShare / oldest.pricePerShare;
  
  // Annualized return
  const yearsElapsed = timeSpan / (365.25 * 24 * 60 * 60);
  return (Math.pow(priceChange, 1 / yearsElapsed) - 1) * 100;
}

2. TVL (Computed)

TVL is calculated from environment config

const { totalAssets, decimals, asset } = vault;
const totalAssetFormatted = convertBigIntToNumber({
        value: BigInt(totalAssets),
        decimals: asset.decimals,
        precision: decimals,
      });

const usdPriceFormatted = convertBigIntToNumber({
        value: BigInt(asset.usdPrice.value),
        decimals: asset.usdPrice.decimals,
        precision: asset.usdPrice.precision,
      });

const vaultTvl = totalAssetFormatted * usdPriceFormatted;

3. Vault Curators (Off-chain)

// Curator info comes from vault configuration
// From assetManager attribute in Vault env variable

4. Vault Rewards (Off-chain + External APIs)

// Curator info comes from vault configuration
// From rewards attribute in Vault env variab

Quick Reference

Data Source Summary

Information	Source
Vault Name	Environment Config
Vault Address	Environment Config
Underlying Asset	Environment Config + Blockchain
Vault APR	Computed from Events
Vault Curators	Environment Config
Vault Rewards	Environment Config
TVL	Computed from Events

Key Environment Variables

• VAULTS: JSON array of vault configurations

• NEXT_PUBLIC_ASSETS: Asset definitions with price feeds

• THEGRAPH_URLS: GraphQL endpoints for event data

Important Notes

1. APR Calculation: Requires historical settlement events and may return 0 for new vaults

2. Asset Prices: Sourced from Chainlink price feeds defined in asset configuration

3. Real-time Data: Use blockchain RPC calls for most current vault state