kirapay-cctp-sdk

A comprehensive SDK for interacting with the KiraPay CCTP protocol and various blockchain networks

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
  0.25,            // Fee percentage (0.25%)
  '0x...'          // 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,
  0.3, // 0.3% fee
  '0x...' // 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.