LayerZero OFT Transfer API Usage Guide

# Required for API access
OFT_API_KEY=your-api-key-here

# Required for executing transactions
PRIVATE_KEY=your-private-key-here

import {Chain} from '@layerzerolabs/lz-definitions';
import {ethers} from 'ethers';
import axios from 'axios';
import 'dotenv/config';

/**
 * LayerZero OFT Transfer API - Ethers.js Integration Example
 *
 * This example demonstrates how to integrate the LayerZero OFT Transfer API
 * to execute OFT transfers using ethers.js and TypeScript.
 *
 * How it works:
 * 1. **Token Discovery**: Uses the LayerZero API to discover tokens
 *    across multiple chains and get their canonical contract addresses
 *
 * 2. **Fetching Transaction Data**: Requests pre-built transaction data from the
 *    LayerZero API instead of manually encoding contract calls
 *
 * 3. **Executing the Transaction**: Executes the transaction using the provider wallet
 *
 * 4. **LayerZero Scan Tracking**: Provides LayerZero scan links to track the
 *    complete crosschain journey of transfers
 *
 * Key Benefits:
 * - No need to understand complex LayerZero contract interfaces
 * - Built-in validation and error handling from the API
 * - Automatic gas estimation and fee calculation
 * - Handling for both OFTs and OFT Adapters
 * - Real-time transaction tracking across chains
 *
 */

// Configuration
const API_KEY = process.env.OFT_API_KEY!;
const API_BASE_URL = 'https://metadata.layerzero-api.com/v1/metadata/experiment/ofts';

// RPC configuration using chain names from LayerZero API
// RPCs are required only for sending the /transfer transaction, not for /list
const RPC_URLS: Record<string, string> = {
  [Chain.BSC]: 'https://bsc.drpc.org',
  [Chain.ABSTRACT]: 'https://api.mainnet.abs.xyz',
};

/**
 * Get the appropriate RPC URL for a chain name.
 * Chain names come directly from LayerZero API discovery.
 */
function getRpcUrl(chainName: string): string {
  const url = RPC_URLS[chainName];
  if (!url) {
    throw new Error(`RPC URL not configured for chain: ${chainName}`);
  }
  return url;
}

/**
 * Discover where a token is available across chains.
 * This is the typical user flow - start with a token symbol and see where it's deployed.
 */
async function discoverTokenDeployments(symbol: string) {
  try {
    console.log('🔍 Token Discovery:');
    console.log(`  Searching for ${symbol} deployments...`);

    const response = await axios.get(`${API_BASE_URL}/list`, {
      params: {symbols: symbol},
    });

    const tokenData = response.data[symbol]?.[0];
    if (!tokenData) {
      throw new Error(`Token ${symbol} not found`);
    }

    const availableChains = Object.keys(tokenData.deployments);
    console.log(`  ✓ ${symbol} found on: ${availableChains.join(', ')}`);
    console.log();

    return response.data;
  } catch (error: any) {
    console.error('Error discovering token:', error.response?.data || error.message);
    throw error;
  }
}

/**
 * Extract the OFT contract address for a token on a specific chain.
 * Prevents address lookup errors and handles chain-specific deployments.
 */
function getOftAddress(tokens: any, symbol: string, chainName: string): string {
  const tokenData = tokens[symbol]?.[0];
  if (!tokenData) {
    throw new Error(`Token ${symbol} not found`);
  }

  const address = tokenData.deployments[chainName]?.address;
  if (!address) {
    throw new Error(`Token ${symbol} not available on ${chainName}`);
  }

  return address;
}

/**
 * Generate LayerZero scan links for crosschain transaction tracking.
 * LayerZero scan shows the complete crosschain journey, unlike regular block explorers.
 */
function getLayerZeroScanLink(hash: string): string {
  // For simplicity, always use mainnet scan since we're working with mainnet chains
  return `https://layerzeroscan.com/tx/${hash}`;
}

/**
 * Execute an OFT token transfer using the LayerZero API.
 * Uses chain names discovered from the LayerZero API.
 */
async function transferOFT(fromChain: string, toChain: string, oftAddress: string, amount: string) {
  try {
    console.log('🚀 OFT Transfer:');
    console.log(`  Route: ${fromChain} → ${toChain}`);
    console.log();

    // Get RPC URL for the source chain
    const rpcUrl = getRpcUrl(fromChain);

    // Initialize wallet on the source chain
    const provider = new ethers.providers.JsonRpcProvider(rpcUrl);
    const wallet = new ethers.Wallet(process.env.PRIVATE_KEY!, provider);

    // Check wallet balance
    const balance = await wallet.getBalance();

    console.log('Wallet Information:');
    console.log(`  Address: ${wallet.address}`);
    console.log(`  Balance: ${ethers.utils.formatEther(balance)} native tokens`);
    console.log();

    // Request pre-built transaction data from LayerZero API
    console.log('Transaction Preparation:');
    console.log('  Requesting transaction data from LayerZero API...');

    const response = await axios.get(`${API_BASE_URL}/transfer`, {
      params: {
        srcChainName: fromChain,
        dstChainName: toChain,
        srcAddress: oftAddress, // Source chain OFT contract address
        amount, // Amount in token's smallest unit (wei)
        from: wallet.address,
        to: wallet.address, // Same address on destination chain
        validate: true, // Pre-validate balances and parameters
      },
      headers: {'x-layerzero-api-key': API_KEY},
    });

    const {transactionData} = response.data;
    console.log('  ✓ Transaction data prepared');
    console.log();

    // Handle token approval if required (for OFT adapters wrapping existing ERC20s)
    if (transactionData.approvalTransaction) {
      console.log('Token Approval:');
      console.log('  Sending approval transaction...');
      const approvalTx = await wallet.sendTransaction(transactionData.approvalTransaction);
      await approvalTx.wait();
      console.log('  ✓ Approval confirmed');
      console.log();
    }

    // Execute the omnichain transfer transaction (includes LayerZero messaging fees)
    console.log('OFT Transfer:');
    console.log('  Sending transfer transaction...');
    const transferTx = await wallet.sendTransaction(transactionData.populatedTransaction);
    await transferTx.wait();
    console.log('  ✓ Transaction confirmed');
    console.log();

    // Provide tracking link for the complete crosschain journey
    const scanLink = getLayerZeroScanLink(transferTx.hash);

    console.log('🎉 Transaction Results:');
    console.log(`  LayerZero Scan: ${scanLink}`);
    console.log();

    return transferTx.hash;
  } catch (error: any) {
    // Extract meaningful error messages from API responses
    if (error.response?.data) {
      throw new Error(`API Error: ${JSON.stringify(error.response.data)}`);
    }
    throw error;
  }
}

/**
 * Example: OFT transfer
 *
 * Demonstrates the complete integration flow:
 * 1. Use explicit LayerZero chain names for chain identification
 * 2. Dynamically discover contract addresses
 * 3. Execute transfers with automatic approval handling
 * 4. Provide LayerZero transaction tracking
 */
async function main() {
  try {
    console.log('LayerZero OFT API - Ethers.js Example');
    console.log('==========================================\n');

    // Discover where PENGU is available and choose transfer route
    const tokens = await discoverTokenDeployments('PENGU');

    // Choose source and destination chains from available deployments
    const fromChain = 'abstract';
    const toChain = 'bsc';

    // Extract the source chain OFT contract address (always use FROM chain address)
    const oftAddress = getOftAddress(tokens, 'PENGU', fromChain);
    console.log(`OFT contract: ${oftAddress}`);
    console.log();

    // Execute the crosschain transfer using chain names from API
    await transferOFT(
      fromChain, // Source chain name
      toChain, // Destination chain name
      oftAddress, // Source chain OFT contract address
      '1000000000000', // Amount in token's smallest unit
    );

    console.log('Example completed successfully!');
  } catch (error: any) {
    // Handle errors gracefully with actionable feedback
    if (error.response?.data) {
      console.error('API Error:', error.response.data);
    } else if (error.message) {
      console.error('Error:', error.message);
    } else {
      console.error('Unknown error:', error);
    }
  }
}

// Export functions for use in other scripts
export {discoverTokenDeployments, transferOFT, getRpcUrl, getOftAddress};

// Run main function if this script is executed directly
if (require.main === module) {
  main();
}

✗ npx ts-node scripts/testOFTAPI.ts

LayerZero OFT API - Ethers.js Example
==========================================

🔍 Token Discovery:
  Searching for PENGU deployments...
  ✓ PENGU found on: abstract, bsc, ethereum, solana

OFT contract: 0x9ebe3a824ca958e4b3da772d2065518f009cba62

🚀 OFT Transfer:
  Route: abstract → bsc

Wallet Information:
  Address: 0xed422098669cBB60CAAf26E01485bAFdbAF9eBEA
  Balance: 0.009736997308229952 native tokens

Transaction Preparation:
  Requesting transaction data from LayerZero API...
  ✓ Transaction data prepared

OFT Transfer:
  Sending transfer transaction...
  ✓ Transaction confirmed

🎉 Transaction Results:
  LayerZero Scan: https://layerzeroscan.com/tx/0x49c44f1ff5ab82ceaeee6c780e991863d75ad544cb6123583c2e335b314b77ab

Example completed successfully!