@shogun-sdk/swap 0.1.0

package/src/examples/usage.ts

@@ -0,0 +1,261 @@
+/**
+ * Usage examples for SwapClient
+ */
+
+import { SwapClient, type SwapClientConfig, type UnifiedQuoteParams } from '../client/SwapClient.js';
+import { ChainID } from '@shogun-sdk/intents-sdk';
+
+// Example configuration with enhanced options
+const config: SwapClientConfig = {
+  apiKey: 'your-api-key-here',
+  apiUrl: 'https://api.shogun.network',
+  timeout: 30000, // 30 seconds
+  maxRetries: 3, // Retry failed requests up to 3 times
+  retryDelay: 1000, // Wait 1 second between retries
+  debug: true, // Enable debug logging
+  preferIntentsSdk: true, // Try intents-sdk first
+  headers: {
+    'User-Agent': 'MyApp/1.0.0'
+  }
+};
+
+// Create the client
+const swapClient = new SwapClient(config);
+
+// Example 1: Cross-chain swap quote
+export async function getCrossChainQuote() {
+  const params: UnifiedQuoteParams = {
+    sourceChainId: ChainID.Arbitrum,
+    destChainId: ChainID.Arbitrum,
+    tokenIn: '0xA0b86a33E6441b8c4C8C0C4C0C4C0C4C0C4C0C4C', // USDC on Ethereum
+    tokenOut: '0x1234567890123456789012345678901234567890', // Some token on Arbitrum
+    amount: BigInt('1000000'), // 1 USDC (6 decimals)
+    senderAddress: '0x1234567890123456789012345678901234567890',
+    destinationAddress: '0x1234567890123456789012345678901234567890',
+    slippageBps: 50, // 0.5% slippage
+  };
+
+  try {
+    const quote = await swapClient.getQuote(params);
+    console.log('Cross-chain quote:', quote);
+    return quote;
+  } catch (error) {
+    console.error('Failed to get cross-chain quote:', error);
+    throw error;
+  }
+}
+
+// Example 2: Single-chain swap quote
+export async function getSingleChainQuote() {
+  try {
+    const quote = await swapClient.getSingleChainQuote(
+      ChainID.Arbitrum,
+      '0xA0b86a33E6441b8c4C8C0C4C0C4C0C4C0C4C0C4C', // USDC
+      '0x1234567890123456789012345678901234567890', // Some other token
+      BigInt('1000000'), // 1 USDC
+      50 // 0.5% slippage
+    );
+    console.log('Single-chain quote:', quote);
+    return quote;
+  } catch (error) {
+    console.error('Failed to get single-chain quote:', error);
+    throw error;
+  }
+}
+
+// Example 3: Solana swap with Jito tip
+export async function getSolanaSwapQuote() {
+  const params: UnifiedQuoteParams = {
+    sourceChainId: ChainID.Solana,
+    destChainId: ChainID.Solana,
+    tokenIn: 'So11111111111111111111111111111111111111112', // SOL
+    tokenOut: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v', // USDC
+    amount: BigInt('1000000000'), // 1 SOL (9 decimals)
+    senderAddress: 'YourSolanaWalletAddress',
+    destinationAddress: 'YourSolanaWalletAddress',
+    slippageBps: 100, // 1% slippage
+    jitoTip: 1000000, // 0.001 SOL tip
+  };
+
+  try {
+    const quote = await swapClient.getQuote(params);
+    console.log('Solana swap quote:', quote);
+    return quote;
+  } catch (error) {
+    console.error('Failed to get Solana swap quote:', error);
+    throw error;
+  }
+}
+
+// Example 4: Using with AbortSignal for timeout control
+export async function getQuoteWithTimeout() {
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), 10000); // 10 second timeout
+
+  const params: UnifiedQuoteParams = {
+    sourceChainId: ChainID.Arbitrum,
+    destChainId: ChainID.Base,
+    tokenIn: '0xA0b86a33E6441b8c4C8C0C4C0C4C0C4C0C4C0C4C',
+    tokenOut: '0x1234567890123456789012345678901234567890',
+    amount: BigInt('1000000'),
+  };
+
+  try {
+    const quote = await swapClient.getQuote(params, controller.signal);
+    clearTimeout(timeoutId);
+    console.log('Quote with timeout:', quote);
+    return quote;
+  } catch (error: any) {
+    clearTimeout(timeoutId);
+    if (error instanceof Error && error.name === 'AbortError') {
+      console.error('Quote request timed out');
+    } else {
+      console.error('Failed to get quote:', error);
+    }
+    throw error;
+  }
+}
+
+// Example 5: Error handling and fallback behavior
+export async function getQuoteWithErrorHandling() {
+  const params: UnifiedQuoteParams = {
+    sourceChainId: ChainID.Arbitrum,
+    destChainId: ChainID.Arbitrum,
+    tokenIn: '0xA0b86a33E6441b8c4C8C0C4C0C4C0C4C0C4C0C4C',
+    tokenOut: '0x1234567890123456789012345678901234567890',
+    amount: BigInt('1000000'),
+  };
+
+  try {
+    const quote = await swapClient.getQuote(params);
+    
+    if (quote.error) {
+      console.warn('Quote returned with error:', quote.error);
+      // Handle the error case
+      return null;
+    }
+
+    // Check if we got a valid quote
+    if (quote.amountOut > 0n) {
+      console.log('Valid quote received from:', quote.source);
+      console.log('Expected output:', quote.amountOut.toString());
+      console.log('Price impact:', quote.priceImpact, '%');
+      return quote;
+    } else {
+      console.warn('Invalid quote received');
+      return null;
+    }
+  } catch (error) {
+    console.error('Failed to get quote:', error);
+    throw error;
+  }
+}
+
+// Example 6: Multiple quotes comparison
+export async function getMultipleQuotesComparison() {
+  const baseParams: UnifiedQuoteParams = {
+    sourceChainId: ChainID.Arbitrum ,
+    destChainId: ChainID.Arbitrum,
+    tokenIn: '0xA0b86a33E6441b8c4C8C0C4C0C4C0C4C0C4C0C4C',
+    tokenOut: '0x1234567890123456789012345678901234567890',
+    amount: BigInt('1000000'),
+  };
+
+  // Create multiple quote variations
+  const quoteParams = [
+    { ...baseParams, slippageBps: 50 }, // 0.5% slippage
+    { ...baseParams, slippageBps: 100 }, // 1% slippage
+    { ...baseParams, slippageBps: 200 }, // 2% slippage
+  ];
+
+  try {
+    const quotes = await swapClient.getMultipleQuotes(quoteParams);
+    console.log('Multiple quotes received:', quotes.length);
+    
+    // Find the best quote
+    const bestQuote = await swapClient.getBestQuote(quoteParams);
+    if (bestQuote) {
+      console.log('Best quote output:', bestQuote.amountOut.toString());
+      console.log('Best quote source:', bestQuote.source);
+    }
+    
+    return quotes;
+  } catch (error) {
+    console.error('Failed to get multiple quotes:', error);
+    throw error;
+  }
+}
+
+// Example 7: Token pair validation
+export async function validateTokenPair() {
+  const chainId = ChainID.Arbitrum;
+  const tokenIn = '0xA0b86a33E6441b8c4C8C0C4C0C4C0C4C0C4C0C4C'; // USDC
+  const tokenOut = '0x1234567890123456789012345678901234567890'; // Some token
+
+  try {
+    const isSupported = await swapClient.isTokenPairSupported(chainId, tokenIn, tokenOut);
+    console.log('Token pair supported:', isSupported);
+    
+    if (isSupported) {
+      // Get supported tokens for the chain
+    }
+    
+    return isSupported;
+  } catch (error) {
+    console.error('Failed to validate token pair:', error);
+    throw error;
+  }
+}
+
+// Example 8: Gas estimation
+export async function estimateSwapGas() {
+  const chainId = ChainID.Arbitrum;
+  const tokenIn = '0xA0b86a33E6441b8c4C8C0C4C0C4C0C4C0C4C0C4C';
+  const tokenOut = '0x1234567890123456789012345678901234567890';
+  const amount = BigInt('1000000');
+  const userAddress = '0x1234567890123456789012345678901234567890';
+
+  try {
+    const gasEstimate = await swapClient.estimateGas(chainId, tokenIn, tokenOut, amount, userAddress);
+    
+    if (gasEstimate) {
+      console.log('Gas estimate:', gasEstimate.gasEstimate.toString());
+      console.log('Gas price:', gasEstimate.gasPrice.toString());
+      console.log('Total gas cost:', (gasEstimate.gasEstimate * gasEstimate.gasPrice).toString());
+    } else {
+      console.log('Gas estimation not available for this chain');
+    }
+    
+    return gasEstimate;
+  } catch (error) {
+    console.error('Failed to estimate gas:', error);
+    throw error;
+  }
+}
+
+// Example 9: Dynamic configuration updates
+export async function updateClientConfiguration() {
+  try {
+    // Get current configuration
+    const currentConfig = swapClient.getConfig();
+    console.log('Current config:', currentConfig);
+
+    // Update configuration
+    swapClient.updateConfig({
+      debug: false, // Disable debug logging
+      maxRetries: 5, // Increase retry attempts
+      timeout: 60000, // Increase timeout to 60 seconds
+    });
+
+    console.log('Configuration updated successfully');
+    
+    // Verify the update
+    const updatedConfig = swapClient.getConfig();
+    console.log('Updated config:', updatedConfig);
+    
+    return updatedConfig;
+  } catch (error) {
+    console.error('Failed to update configuration:', error);
+    throw error;
+  }
+}

package/src/index.ts

@@ -0,0 +1,12 @@
+/**
+ * @shogun-sdk/swap
+ * 
+ * Shogun Network Swap utilities and helpers
+ */
+
+export * from './types/index.js';
+export * from './utils/index.js';
+export * from './client/SwapClient.js';
+
+// Re-export ChainID for convenience
+export { ChainID } from '@shogun-sdk/intents-sdk';

package/src/types/index.ts

@@ -0,0 +1,36 @@
+/**
+ * Type definitions for swap operations
+ */
+
+export interface SwapParams {
+  /** Input token address */
+  tokenIn: string;
+  /** Output token address */
+  tokenOut: string;
+  /** Amount of input tokens */
+  amountIn: bigint;
+  /** Minimum amount of output tokens expected */
+  amountOutMin: bigint;
+  /** Recipient address */
+  to: string;
+  /** Transaction deadline (unix timestamp) */
+  deadline: number;
+}
+
+export interface SwapQuote {
+  /** Expected output amount */
+  amountOut: bigint;
+  /** Price impact percentage (0-100) */
+  priceImpact: number;
+  /** Gas estimate */
+  gasEstimate?: bigint;
+}
+
+export interface SwapResult {
+  /** Transaction hash */
+  transactionHash: string;
+  /** Actual amount received */
+  amountOut: bigint;
+  /** Gas used */
+  gasUsed?: bigint;
+}

package/src/utils/index.ts

@@ -0,0 +1,77 @@
+/**
+ * Utility functions for swap operations
+ */
+
+import type { SwapParams } from '../types/index.js';
+
+/**
+ * Calculate price impact for a swap
+ * @param amountIn Input amount
+ * @param amountOut Expected output amount
+ * @param tokenInPrice Price of input token in USD
+ * @param tokenOutPrice Price of output token in USD
+ * @returns Price impact as percentage
+ */
+export function calculatePriceImpact(
+  amountIn: bigint,
+  amountOut: bigint,
+  tokenInPrice: number,
+  tokenOutPrice: number
+): number {
+  const inputValue = Number(amountIn) * tokenInPrice;
+  const outputValue = Number(amountOut) * tokenOutPrice;
+  
+  if (inputValue === 0) return 0;
+  
+  return Math.abs((inputValue - outputValue) / inputValue) * 100;
+}
+
+/**
+ * Validate swap parameters
+ * @param params Swap parameters to validate
+ * @throws Error if parameters are invalid
+ */
+export function validateSwapParams(params: SwapParams): void {
+  if (!params.tokenIn || !params.tokenOut) {
+    throw new Error('Token addresses are required');
+  }
+  
+  if (params.tokenIn === params.tokenOut) {
+    throw new Error('Input and output tokens cannot be the same');
+  }
+  
+  if (params.amountIn <= 0n) {
+    throw new Error('Input amount must be greater than 0');
+  }
+  
+  if (params.amountOutMin < 0n) {
+    throw new Error('Minimum output amount cannot be negative');
+  }
+  
+  if (!params.to) {
+    throw new Error('Recipient address is required');
+  }
+  
+  if (params.deadline <= Math.floor(Date.now() / 1000)) {
+    throw new Error('Deadline must be in the future');
+  }
+}
+
+/**
+ * Format token amount for display
+ * @param amount Token amount in smallest units
+ * @param decimals Token decimals
+ * @returns Formatted string
+ */
+export function formatTokenAmount(amount: bigint, decimals: number): string {
+  const divisor = BigInt(10 ** decimals);
+  const whole = amount / divisor;
+  const remainder = amount % divisor;
+  
+  if (remainder === 0n) {
+    return whole.toString();
+  }
+  
+  const fractional = remainder.toString().padStart(decimals, '0').replace(/0+$/, '');
+  return `${whole}.${fractional}`;
+}