KiraPay CCTP SDK

A comprehensive TypeScript SDK for interacting with the KiraPay Cross-Chain Transfer Protocol (CCTP) and various blockchain networks. This SDK enables seamless cross-chain token swaps, transfers, and DeFi operations across multiple EVM-compatible blockchains.

🚀 Features

• Multi-Chain Support: Ethereum, Arbitrum, Base, Polygon, BSC, Avalanche, Optimism, Blast, Celo, and more
• Cross-Chain Operations: Token swaps and transfers between different blockchains
• CCTP Integration: Circle's Cross-Chain Transfer Protocol for USDC transfers
• Automatic Route Finding: Intelligent routing for optimal swap paths
• Fee Estimation: Accurate gas and cross-chain transfer fee calculations
• Price Impact Analysis: Real-time price impact calculations
• Boost Mode: Fast cross-chain transfers with CCTP v2
• TypeScript Support: Full type safety and IntelliSense support

📦 Installation

npm install kirapay-cctp-sdk
# or
yarn add kirapay-cctp-sdk
# or
pnpm add kirapay-cctp-sdk

🏗️ Supported Networks

Mainnet

• Ethereum (Chain ID: 1)
• Arbitrum (Chain ID: 42161)
• Base (Chain ID: 8453)
• Polygon (Chain ID: 137)
• BSC (Chain ID: 56)
• Avalanche (Chain ID: 43114)
• Optimism (Chain ID: 10)
• Blast (Chain ID: 81457)
• Celo (Chain ID: 42220)
• Unichain (Chain ID: 130)

Testnet

• Ethereum Sepolia (Chain ID: 11155111)
• Arbitrum Sepolia (Chain ID: 421614)
• Base Sepolia (Chain ID: 84532)
• Polygon Amoy (Chain ID: 80002)
• BSC Testnet (Chain ID: 97)
• Avalanche Fuji (Chain ID: 43113)
• Optimism Sepolia (Chain ID: 11155420)
• Blast Sepolia (Chain ID: 168587773)
• Celo Alfajores (Chain ID: 44787)
• Unichain Sepolia (Chain ID: 1301)

🔧 Quick Start

Basic Setup

import { SwapRouter, ChainId, NetworkToken } from 'kirapay-cctp-sdk';

// Initialize router with default configurations
const router = new SwapRouter();

// Or with custom configurations
const customRouter = new SwapRouter(
  customContracts,  // Contract addresses
  customGmpIds,     // GMP network IDs
  1.0,             // Fee percentage (1.0%)
  '0x9b2CCBC8024438AF46EF1C9E26bb5553744DC89d'  // Fee recipient address
);

Define Tokens

import { getUSDC, getNative } from 'kirapay-cctp-sdk';

// Get native tokens
const ethOnEthereum = getNative(ChainId.EthereumMainnet);
const ethOnArbitrum = getNative(ChainId.ArbitrumMainnet);

// Get USDC tokens
const usdcOnEthereum = getUSDC(ChainId.EthereumMainnet);
const usdcOnBase = getUSDC(ChainId.BaseMainnet);

// Custom token
const customToken: NetworkToken = {
  chainId: ChainId.EthereumMainnet,
  address: '0x...', // Token contract address
  symbol: 'TOKEN',
  name: 'Custom Token',
  decimals: 18,
  logoURI: 'https://...',
};

💡 Usage Examples

1. Same-Chain Token Swap

const swapParams = {
  input: ethOnEthereum,
  output: usdcOnEthereum,
  amount: '1.0', // 1 ETH
  recipient: '0x...', // Recipient address
  slippagePercent: 0.5, // 0.5% slippage tolerance
  deadlineInSeconds: 1800, // 30 minutes
};

const route = await router.findRoute(swapParams);

if (route && route.method) {
  console.log('Swap Details:');
  console.log('Input:', route.input.amount, route.input.token.symbol);
  console.log('Output:', route.output.amount, route.output.token.symbol);
  console.log('Price Impact:', route.priceImpact + '%');
  console.log('Gas Fee:', route.fee.amount, route.fee.token.symbol);
  
  // Execute transaction
  const txParams = route.method.parameters;
  // Use with your preferred web3 library (ethers, viem, etc.)
}

2. Cross-Chain Token Transfer

const transferParams = {
  input: usdcOnEthereum,
  output: usdcOnBase,
  amount: '100', // 100 USDC
  recipient: '0x...',
  slippagePercent: 0.1,
  deadlineInSeconds: 1800,
};

const transferRoute = await router.findRoute(transferParams);

if (transferRoute && transferRoute.method) {
  console.log('Transfer Details:');
  console.log('Strategy:', transferRoute.strategy);
  console.log('Transfer Fee:', transferRoute.transferFee?.amount);
  console.log('GMP Fee:', transferRoute.gmpFee?.amount);
  
  // Execute cross-chain transfer
  const txParams = transferRoute.method.parameters;
}

3. Cross-Chain Swap (Swap + Transfer + Swap)

const crossChainSwapParams = {
  input: ethOnEthereum,     // ETH on Ethereum
  output: ethOnArbitrum,    // ETH on Arbitrum
  amount: '0.5',            // 0.5 ETH
  recipient: '0x...',
  slippagePercent: 1.0,     // Higher slippage for cross-chain
  deadlineInSeconds: 3600,  // 1 hour for cross-chain
};

const crossChainRoute = await router.findRoute(crossChainSwapParams);

if (crossChainRoute && crossChainRoute.method) {
  console.log('Cross-Chain Swap Strategy:', crossChainRoute.strategy);
  console.log('Total Routes:', crossChainRoute.routes.length);
  
  // This will perform: ETH → USDC (Ethereum) → USDC (Arbitrum) → ETH (Arbitrum)
}

4. Boost Mode for Fast Transfers

const boostParams = {
  maxFeeAmount: { token: usdcOnEthereum, amount: '1.0' }, // Max 1 USDC fee
  rewardAmount: { token: usdcOnEthereum, amount: '0.1' }, // 0.1 USDC reward
  premiumAmount: { token: usdcOnEthereum, amount: '0.05' }, // 0.05 USDC premium
  minFinalityThreshold: 1, // Minimum confirmations
};

const boostRoute = await router.findRoute(transferParams, boostParams);

if (boostRoute?.boostOptions) {
  console.log('Boost enabled for faster transfer');
  console.log('Max Fee:', boostRoute.boostOptions.maxFeeAmount.amount);
}

5. Quote Without Execution

const quote = await router.quote(swapParams);

if (quote) {
  console.log('Quote Details:');
  console.log('Estimated Output:', quote.output.amount);
  console.log('Price Impact:', quote.priceImpact + '%');
  console.log('Gas Fee:', quote.fee.amount);
  
  // No transaction parameters - just estimation
}

6. Wrap/Unwrap Native Tokens

// Wrap ETH to WETH
const wrapParams = {
  input: ethOnEthereum,
  output: getWETH9(ChainId.EthereumMainnet),
  amount: '1.0',
  recipient: '0x...',
  slippagePercent: 0,
  deadlineInSeconds: 1800,
};

const wrapRoute = await router.findRoute(wrapParams);
// Strategy will be 'Wrap'

// Unwrap WETH to ETH
const unwrapParams = {
  input: getWETH9(ChainId.EthereumMainnet),
  output: ethOnEthereum,
  amount: '1.0',
  recipient: '0x...',
  slippagePercent: 0,
  deadlineInSeconds: 1800,
};

const unwrapRoute = await router.findRoute(unwrapParams);
// Strategy will be 'Unwrap'

🔧 Advanced Configuration

Custom Contract Addresses

import { ZenswapContracts, GmpIds } from 'kirapay-cctp-sdk';

const customContracts: ZenswapContracts = {
  [ChainId.EthereumMainnet]: {
    zenswap: '0x...', // KiraPay main contract
    gmpPlugin: '0x...', // GMP plugin for cross-chain messaging
    gmpGateway: '0x...', // GMP gateway contract
    cctpV2Plugin: '0x...', // CCTP v2 plugin for boost mode
  },
  // Add other chains...
};

const customGmpIds: GmpIds = {
  [ChainId.EthereumMainnet]: 1,
  [ChainId.ArbitrumMainnet]: 2,
  // Add other chains...
};

const router = new SwapRouter(
  customContracts,
  customGmpIds,
  1.0, // 1.0% fee (default)
  '0x9b2CCBC8024438AF46EF1C9E26bb5553744DC89d' // Fee recipient
);

Error Handling

try {
  const route = await router.findRoute(swapParams);
  
  if (route.error) {
    console.error('Route error:', route.error.message);
    return;
  }
  
  if (!route.method) {
    console.error('No executable method found');
    return;
  }
  
  // Execute transaction
  const tx = await signer.sendTransaction(route.method.parameters);
  await tx.wait();
  
} catch (error) {
  console.error('Swap failed:', error);
}

📊 Swap Strategies

The SDK automatically determines the optimal strategy based on input/output tokens:

• Swap: Same-chain token swap using DEX aggregation
• Transfer: Direct cross-chain token transfer (same token)
• SwapAndTransfer: Swap on source chain, then transfer to destination
• TransferAndSwap: Transfer to destination chain, then swap
• SwapAndSwap: Swap on source, transfer, then swap on destination
• Wrap: Convert native token to wrapped version (ETH → WETH)
• Unwrap: Convert wrapped token to native version (WETH → ETH)

🔗 Supported Protocols

• Uniswap V2/V3: Automated Market Maker
• Circle CCTP: Cross-Chain Transfer Protocol for USDC
• General Message Passing (GMP): Cross-chain messaging
• DEX Aggregation: Optimal routing across multiple DEXs

🛠️ Development

# Install dependencies
npm install

# Build the SDK
npm run build

# Run tests
npm test

# Run examples
npm run example:js

📄 License

MIT License - see LICENSE file for details.

🤝 Contributing

Contributions are welcome! Please read CONTRIBUTING.md for guidelines.

📞 Support

For questions and support, please open an issue on the GitHub repository.

Note: This SDK is designed for testnet usage. For mainnet deployment, ensure proper testing and security audits.