Cookbook

import { sdk } from '@avail-project/nexus';
 
// 1. Simulate a bridge
const bridgeSimulation = await sdk.simulateBridge({
  token: 'USDC',
  amount: BigInt(100),
  toChainId: 421614,
});
 
// 2. Simulate a bridgeAndExecute (bridge + contract call)
const bridgeAndExecuteSimulation = await sdk.simulateBridgeAndExecute({
  token: 'USDC',
  amount: BigInt(1_000_000),
  toChainId: 421614,
  execute: {
    to: '0xContractAddress',
    data: encodedCalldata,
    tokenApproval: {
      token: 'USDC',
      amount: BigInt(1_000_000),
      spender: '0xContractAddress',
    },
  },
});
 
// 3. Simulate a bridgeAndTransfer (cross-chain send)
const bridgeAndTransferSimulation = await sdk.simulateBridgeAndTransfer({
  token: 'USDC',
  amount: BigInt(1_000_000),
  toChainId: 421614,
  recipient: '0xRecipientAddress',
});
 

const sim = await sdk.simulateBridge({
  token: 'USDC',
  amount: BigInt(100),
  toChainId: 421614,
});
 
// Sources chosen by the solver
sim.intent.sources.forEach((source) => {
  console.log(source.chainName);        // "Arbitrum Sepolia"
  console.log(source.chainID);          // 421614
  console.log(source.chainLogo);        // "https://..."
  console.log(source.amount);           // "100"
  console.log(source.contractAddress);  // "0x..."
});
 
// All chains that had balance (superset of sources)
console.log(sim.intent.allSources);
 
// Destination chain info
console.log(sim.intent.destination.chainName);
console.log(sim.intent.destination.chainID);
 
// Total amount pulled across all sources
console.log(sim.intent.sourcesTotal);
 
// ─── Alternative: use the intent hook during execution ───
sdk.setOnIntentHook(({ intent, allow, deny, refresh }) => {
  // Same ReadableIntent structure as the simulation
  console.log(intent.sources);
  console.log(intent.destination);
  allow(); // or deny() to cancel
});
 

import {
  TOKEN_METADATA,
  CHAIN_METADATA,
} from '@avail-project/nexus';
 
// ─── A: From a simulation result ───
const sim = await sdk.simulateBridge({ token: 'USDC', amount: BigInt(100), toChainId: 421614 });
 
sim.intent.token.name;      // "USD Coin"
sim.intent.token.symbol;    // "USDC"
sim.intent.token.decimals;  // 6
sim.intent.token.logo;      // "https://..."
 
// Source chain logos
sim.intent.sources[0].chainLogo;  // "https://..."
sim.intent.sources[0].chainName;  // "Base Sepolia"
 
/*----------------------------------------*/
 
// ─── B: From static metadata constants ───
TOKEN_METADATA['USDC'];
// { symbol: "USDC", name: "USD Coin", decimals: 6, icon: "https://...", coingeckoId: "usd-coin" }
 
CHAIN_METADATA[421614];
// { id: 421614, name: "Arbitrum Sepolia", logo: "https://...", nativeCurrency: {...}, ... }
 
/*----------------------------------------*/
 
// ─── C: getSupportedChains — chains with their token lists ───
const chains = sdk.utils.getSupportedChains();
// [{ id: 421614, name: "Arbitrum Sepolia", logo: "...", tokens: [{ symbol, name, logo, ... }] }]

const sim = await sdk.simulateBridge({
  token: 'USDC',
  amount: BigInt(100),
  toChainId: 421614,
});
 
const { fees } = sim.intent;
 
console.log(fees.total);        // Total fee in token units (e.g. "0.05")
console.log(fees.protocol);     // Protocol fee
console.log(fees.solver);       // Solver / fulfillment fee
console.log(fees.caGas);        // Chain-abstraction gas fee
console.log(fees.gasSupplied);  // Gas supplied by the solver
 

// Fetch the first page of intents
const intents = await sdk.getMyIntents();
 
// Paginate
const page2 = await sdk.getMyIntents(2);
 
// Check status
intents.forEach((intent) => {
  if (intent.fulfilled) console.log(`Intent #${intent.id}: fulfilled`);
  else if (intent.refunded) console.log(`Intent #${intent.id}: refunded`);
  else console.log(`Intent #${intent.id}: pending (expires ${new Date(intent.expiry * 1000)})`);
});
 
// Each intent (RFF) has this shape:
// {
//   id: 42,
//   explorerUrl: "https://...",
//   deposited: true,
//   fulfilled: true,
//   refunded: false,
//   expiry: 1706000000,
//   destinationChain: { id: 421614, name: "Arbitrum Sepolia", logo: "...", universe: "..." },
//   destinations: [{
//     token: { address: "0x...", symbol: "USDC", decimals: 6 },
//     value: "1.0",
//     valueRaw: 1000000n,
//   }],
//   sources: [{
//     chain: { id: 84532, name: "Base Sepolia", logo: "...", universe: "..." },
//     token: { address: "0x...", symbol: "USDC", decimals: 6 },
//     value: "1.05",
//     valueRaw: 1050000n,
//   }],
// }

import { CHAIN_METADATA, NexusSDK } from '@avail-project/nexus-core';
 
// Option A: Static constant (no SDK initialization needed)
const arbitrumSepolia = CHAIN_METADATA[421614];
console.log(arbitrumSepolia.name);           // "Arbitrum Sepolia"
console.log(arbitrumSepolia.logo);           // "https://..."
console.log(arbitrumSepolia.nativeCurrency); // { name: "ETH", symbol: "ETH", decimals: 18 }
 
// Option B: SDK utility method
const sdk = new NexusSDK({ network: 'testnet' });
const chainMeta = sdk.utils.getChainMetadata(421614);
console.log(chainMeta?.name); // "Arbitrum Sepolia"

import { NexusSDK } from '@avail-project/nexus-core';
 
const sdk = new NexusSDK({ network: 'mainnet' });
 
// Get all supported chains with their tokens
const chains = sdk.utils.getSupportedChains();
 
chains.forEach((chain) => {
  console.log(`${chain.name} (${chain.id})`);
  console.log(`  Logo: ${chain.logo}`);
  console.log(`  Tokens:`);
  chain.tokens?.forEach((token) => {
    console.log(`    - ${token.symbol}: ${token.name}`);
  });
});
 
// For swap-specific chains and tokens
const swapOptions = sdk.utils.getSwapSupportedChainsAndTokens();

import { NexusSDK } from '@avail-project/nexus-core';
 
const sdk = new NexusSDK({ network: 'testnet' });
 
// Find chain ID by name
const chains = sdk.utils.getSupportedChains();
const baseSepolia = chains.find((c) => c.name === 'Base Sepolia');
console.log(baseSepolia?.id); // 84532
 
// Validate if a chain ID is supported
const isSupported = sdk.utils.isSupportedChain(84532); // true
 
// Convert chain ID to hex (useful for wallet_switchEthereumChain)
const hexChainId = sdk.utils.chainIdToHex(84532); // "0x14a34"
 
// Convert hex back to decimal
const decimalId = sdk.utils.hexToChainId('0x14a34'); // 84532

import { NexusSDK } from '@avail-project/nexus-core';
 
const sdk = new NexusSDK({ network: 'testnet' });
 
// Option A: Get token metadata (base info without chain-specific addresses)
const usdcMeta = sdk.utils.getTokenMetadata('USDC');
console.log(usdcMeta?.symbol);   // "USDC"
console.log(usdcMeta?.decimals); // 6
console.log(usdcMeta?.icon);     // "https://..."
 
// Option B: Get token address for a SPECIFIC chain
const chains = sdk.utils.getSupportedChains();
const arbitrumSepolia = chains.find((c) => c.id === 421614);
const usdcOnArbitrum = arbitrumSepolia?.tokens?.find((t) => t.symbol === 'USDC');
console.log(usdcOnArbitrum?.address); // "0x75faf114eafb1BDbe2F0316DF893fd58CE46AA4d"
 
// Option C: Get all addresses for a token across chains
const usdcAddresses = chains
  .map((chain) => {
    const token = chain.tokens?.find((t) => t.symbol === 'USDC');
    return token ? { chainId: chain.id, chainName: chain.name, address: token.address } : null;
  })
  .filter(Boolean);
 
console.log(usdcAddresses);
// [
//   { chainId: 421614, chainName: "Arbitrum Sepolia", address: "0x75faf..." },
//   { chainId: 84532, chainName: "Base Sepolia", address: "0x036cb..." },
//   ...
// ]
 
// Validate if a token is supported
const isSupported = sdk.utils.isSupportedToken('USDC'); // true

import { NexusSDK, NEXUS_EVENTS } from '@avail-project/nexus-core';
 
const sdk = new NexusSDK({ network: 'testnet' });
await sdk.initialize(window.ethereum);
 
const result = await sdk.bridge(
  {
    token: 'USDC',
    amount: BigInt(1_000_000), // 1 USDC (6 decimals)
    toChainId: 421614,
  },
  {
    onEvent: (event) => {
      switch (event.name) {
        case NEXUS_EVENTS.STEPS_LIST:
          // Emitted when intent is created - contains all steps
          console.log('All steps:', event.args);
          // Use this to initialize a progress stepper UI
          break;
 
        case NEXUS_EVENTS.STEP_COMPLETE:
          // Emitted for each completed step
          const step = event.args;
          console.log(`Step completed: ${step.type}`);
          console.log(`  Status: ${step.status}`);
          if (step.explorerURL) {
            console.log(`  Explorer: ${step.explorerURL}`);
          }
          break;
      }
    },
  }
);

import { NexusSDK, NEXUS_EVENTS } from '@avail-project/nexus-core';
 
const sdk = new NexusSDK({ network: 'mainnet' });
await sdk.initialize(window.ethereum);
 
const result = await sdk.swapWithExactIn(
  {
    fromToken: 'USDC',
    toToken: 'ETH',
    amount: BigInt(100_000_000), // 100 USDC
    toChainId: 42161,
  },
  {
    onEvent: (event) => {
      if (event.name === NEXUS_EVENTS.SWAP_STEP_COMPLETE) {
        const step = event.args;
        console.log(`Swap step: ${step.type}`);
 
        // Get explorer URLs from specific steps
        if (step.type === 'SOURCE_SWAP_HASH' && step.explorerURL) {
          console.log(`Source swap tx: ${step.explorerURL}`);
        }
        if (step.type === 'DESTINATION_SWAP_HASH' && step.explorerURL) {
          console.log(`Destination swap tx: ${step.explorerURL}`);
        }
      }
    },
  }
);

// Intent approval hook - review before execution
sdk.setOnIntentHook(({ intent, allow, deny, refresh }) => {
  console.log('Sources:', intent.sources);
  console.log('Destination:', intent.destination);
  console.log('Fees:', intent.fees);
 
  // Programmatically approve or deny
  if (userConfirmed) {
    allow();
  } else {
    deny();
  }
});
 
// Allowance approval hook - control approval amounts
sdk.setOnAllowanceHook(({ sources, allow, deny }) => {
  allow(['min']); // Options: 'max', 'min', or custom bigint[]
});

npm install vite-plugin-node-polyfills

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import { nodePolyfills } from 'vite-plugin-node-polyfills';
 
export default defineConfig({
  plugins: [
    react(),
    nodePolyfills({
      include: ['buffer', 'crypto', 'stream', 'util'],
      globals: {
        Buffer: true,
        global: true,
        process: true,
      },
    }),
  ],
  define: {
    global: 'globalThis',
  },
});

{
  "scripts": {
    "dev": "next dev"
  }
}

/** @type {import('next').NextConfig} */
const nextConfig = {
  webpack: (config, { isServer }) => {
    if (!isServer) {
      config.resolve.fallback = {
        ...config.resolve.fallback,
        crypto: require.resolve('crypto-browserify'),
        buffer: require.resolve('buffer/'),
        stream: require.resolve('stream-browserify'),
      };
    }
    return config;
  },
};
 
module.exports = nextConfig;

npm install crypto-browserify buffer stream-browserify

// Bad
const sdk = require('@avail-project/nexus-core');
 
// Good
import { NexusSDK } from '@avail-project/nexus-core';

export async function GET() {
  // Node.js modules work here
  return Response.json({ data: 'ok' });
}

if (typeof window === 'undefined') {
  const serverModule = await import('server-only-module');
}