@shogun-sdk/swap 0.1.0

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@shogun-sdk/swap",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Shogun Network Swap utilities and helpers",
+  "author": "Shogun network",
+  "license": "ISC",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/shogun-network/shogun-sdk.git"
+  },
+  "main": "./dist/esm/index.js",
+  "types": "./dist/types/index.d.ts",
+  "typings": "./dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "default": "./dist/esm/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "sideEffects": false,
+  "files": [
+    "dist/**",
+    "!dist/**/*.tsbuildinfo",
+    "src/**/*.ts",
+    "!src/**/*.test.ts",
+    "!src/**/*.test-d.ts",
+    "README.md"
+  ],
+  "keywords": [
+    "shogun",
+    "swap",
+    "sdk",
+    "api",
+    "typescript"
+  ],
+  "devDependencies": {
+    "@types/node": "22.13.10",
+    "typescript": "5.8.2"
+  },
+  "dependencies": {
+    "viem": "2.31.0",
+    "@shogun-sdk/money-legos": "1.3.51",
+    "@shogun-sdk/intents-sdk": "1.2.4"
+  },
+  "scripts": {
+    "build": "pnpm clean && pnpm build:esm+types",
+    "build:esm+types": "tsc --project ./tsconfig.build.json --outDir ./dist/esm --declaration --declarationMap --declarationDir ./dist/types",
+    "clean": "rm -rf ./dist",
+    "check:types": "tsc --noEmit --project ./tsconfig.build.json",
+    "lint": "npx eslint --fix --ext .ts ./src",
+    "format": "prettier --write ./src"
+  }
+}

package/src/client/SwapClient.ts

@@ -0,0 +1,490 @@
+/**
+ * SwapClient - Unified client for fetching quotes from multiple sources
+ * 
+ * This client combines the QuoteProvider from intents-sdk and the OneShotClient
+ * from money-legos to provide a unified interface for quote fetching with fallback logic.
+ * 
+ * Features:
+ * - Intelligent fallback from intents-sdk to one-shot API
+ * - Comprehensive error handling and retry logic
+ * - Support for all major chains and protocols
+ * - Built-in validation and type safety
+ * - Configurable timeouts and retry policies
+ */
+
+import { QuoteProvider, type IntentsQuoteParams } from '@shogun-sdk/intents-sdk';
+import { compareAddresses, fetchQuote, type QuoteParams as OneShotQuoteParams } from '@shogun-sdk/money-legos';
+import { ChainID } from '@shogun-sdk/intents-sdk';
+
+export interface SwapClientConfig {
+  /** API key for one-shot service */
+  apiKey: string;
+  /** API URL for one-shot service */
+  apiUrl: string;
+  /** Optional timeout for requests in milliseconds */
+  timeout?: number;
+  /** Maximum number of retry attempts for failed requests */
+  maxRetries?: number;
+  /** Delay between retry attempts in milliseconds */
+  retryDelay?: number;
+  /** Whether to enable debug logging */
+  debug?: boolean;
+  /** Custom headers to include with requests */
+  headers?: Record<string, string>;
+  /** Whether to prefer intents-sdk over one-shot API */
+  preferIntentsSdk?: boolean;
+}
+
+export interface UnifiedQuoteParams {
+  /** Source chain ID */
+  sourceChainId: ChainID;
+  /** Destination chain ID */
+  destChainId: ChainID;
+  /** Input token address */
+  tokenIn: string;
+  /** Output token address */
+  tokenOut: string;
+  /** Amount to swap (in smallest token units) */
+  amount: bigint;
+  /** Sender address */
+  senderAddress?: string;
+  /** Destination address */
+  destinationAddress?: string;
+  /** Slippage tolerance in basis points (optional) */
+  slippageBps?: number;
+  /** Affiliate wallet address (optional) */
+  affiliateWallet?: string;
+  /** Affiliate fee (optional) */
+  affiliateFee?: string;
+  /** Jito tip for Solana (optional) */
+  jitoTip?: number;
+  /** Gas refuel amount (optional) */
+  gasRefuel?: number;
+  /** Dynamic slippage flag (optional) */
+  dynamicSlippage?: boolean;
+  /** External call data (optional) */
+  externalCall?: string;
+}
+
+export interface UnifiedQuoteResponse {
+  /** Expected output amount */
+  amountOut: bigint;
+  /** Amount in USD */
+  amountInUsd: number;
+  /** Amount out in USD */
+  amountOutUsd: number;
+  /** Reduced amount out (with slippage) */
+  amountOutReduced?: bigint;
+  /** Reduced amount out in USD */
+  amountOutUsdReduced?: number;
+  /** Minimum stablecoin amount */
+  estimatedAmountInAsMinStablecoinAmount?: bigint;
+  /** Price impact percentage */
+  priceImpact: number;
+  /** Slippage percentage */
+  slippage: number;
+  /** Provider used for the quote */
+  provider: string;
+  /** Raw quote data */
+  rawQuote: any;
+  /** Source of the quote */
+  source: 'intents-sdk' | 'one-shot';
+  /** Error message if any */
+  error?: string;
+}
+
+export class SwapClient {
+  private readonly config: Required<SwapClientConfig>;
+
+  constructor(config: SwapClientConfig) {
+    this.config = {
+      timeout: 30000,
+      maxRetries: 3,
+      retryDelay: 1000,
+      debug: false,
+      headers: {},
+      preferIntentsSdk: true,
+      ...config,
+    };
+  }
+
+  /**
+   * Validates the client configuration
+   */
+  private validateConfig(): void {
+    if (!this.config.apiKey) {
+      throw new Error('API key is required');
+    }
+    if (!this.config.apiUrl) {
+      throw new Error('API URL is required');
+    }
+    if (this.config.timeout <= 0) {
+      throw new Error('Timeout must be greater than 0');
+    }
+    if (this.config.maxRetries < 0) {
+      throw new Error('Max retries cannot be negative');
+    }
+  }
+
+  /**
+   * Logs debug messages if debug mode is enabled
+   */
+  private debug(message: string, data?: any): void {
+    if (this.config.debug) {
+      console.log(`[SwapClient] ${message}`, data || '');
+    }
+  }
+
+  /**
+   * Sleeps for the specified number of milliseconds
+   */
+  private sleep(ms: number): Promise<void> {
+    return new Promise(resolve => setTimeout(resolve, ms));
+  }
+
+  /**
+   * Validates quote parameters
+   */
+  private validateQuoteParams(params: UnifiedQuoteParams): void {
+    if (!params.sourceChainId || !params.destChainId) {
+      throw new Error('Source and destination chain IDs are required');
+    }
+    if (!params.tokenIn || !params.tokenOut) {
+      throw new Error('Token addresses are required');
+    }
+    if (params.amount <= 0n) {
+      throw new Error('Amount must be greater than 0');
+    }
+    if (compareAddresses(params.tokenIn, params.tokenOut) && params.sourceChainId === params.destChainId) {
+      throw new Error('Input and output tokens cannot be the same');
+    }
+  }
+
+  /**
+   * Fetches a quote using the unified interface
+   * First tries intents-sdk QuoteProvider, then falls back to one-shot API
+   * 
+   * @param params Quote parameters
+   * @param signal Optional AbortSignal for cancelling the request
+   * @returns Promise<UnifiedQuoteResponse>
+   */
+  public async getQuote(params: UnifiedQuoteParams, signal?: AbortSignal): Promise<UnifiedQuoteResponse> {
+    this.validateConfig();
+    this.validateQuoteParams(params);
+    
+    this.debug('Fetching quote', { params });
+
+    // Determine quote source order based on configuration
+    const sources = this.config.preferIntentsSdk 
+      ? ['intents-sdk', 'one-shot'] 
+      : ['one-shot', 'intents-sdk'];
+
+    for (const source of sources) {
+      for (let attempt = 0; attempt <= this.config.maxRetries; attempt++) {
+        try {
+          this.debug(`Attempting quote from ${source} (attempt ${attempt + 1})`);
+          
+          let quote: UnifiedQuoteResponse;
+          if (source === 'intents-sdk') {
+            quote = await this.getIntentsQuote(params, signal);
+          } else {
+            quote = await this.getOneShotQuote(params, signal);
+          }
+
+          if (quote && !quote.error && quote.amountOut > 0n) {
+            this.debug(`Successfully got quote from ${source}`, { amountOut: quote.amountOut.toString() });
+            return quote;
+          }
+
+          if (attempt < this.config.maxRetries) {
+            this.debug(`Quote attempt ${attempt + 1} failed, retrying in ${this.config.retryDelay}ms`);
+            await this.sleep(this.config.retryDelay);
+          }
+        } catch (error) {
+          this.debug(`Quote attempt ${attempt + 1} from ${source} failed`, error);
+          
+          if (attempt < this.config.maxRetries) {
+            await this.sleep(this.config.retryDelay);
+          } else if (source === sources[sources.length - 1]) {
+            // Last source and last attempt
+            return {
+              amountOut: 0n,
+              amountInUsd: 0,
+              amountOutUsd: 0,
+              priceImpact: 0,
+              slippage: 0,
+              provider: 'none',
+              rawQuote: null,
+              source: source as 'intents-sdk' | 'one-shot',
+              error: error instanceof Error ? error.message : 'Unknown error occurred'
+            };
+          }
+        }
+      }
+    }
+
+    // This should never be reached, but just in case
+    return {
+      amountOut: 0n,
+      amountInUsd: 0,
+      amountOutUsd: 0,
+      priceImpact: 0,
+      slippage: 0,
+      provider: 'none',
+      rawQuote: null,
+      source: 'one-shot',
+      error: 'All quote sources failed'
+    };
+  }
+
+  /**
+   * Gets quote from intents-sdk QuoteProvider
+   */
+  private async getIntentsQuote(params: UnifiedQuoteParams, _signal?: AbortSignal): Promise<UnifiedQuoteResponse> {
+    const intentsParams: IntentsQuoteParams = {
+      sourceChainId: params.sourceChainId,
+      destChainId: params.destChainId,
+      amount: params.amount,
+      tokenIn: params.tokenIn,
+      tokenOut: params.tokenOut,
+    };
+
+    const quote = await QuoteProvider.getQuote(intentsParams);
+
+    return {
+      amountOut: quote.estimatedAmountOut,
+      amountInUsd: quote.amountInUsd,
+      amountOutUsd: quote.estimatedAmountOutUsd,
+      amountOutReduced: quote.estimatedAmountOutReduced,
+      amountOutUsdReduced: quote.estimatedAmountOutUsdReduced,
+      estimatedAmountInAsMinStablecoinAmount: quote.estimatedAmountInAsMinStablecoinAmount,
+      priceImpact: 0, // QuoteProvider doesn't provide price impact directly
+      slippage: 0, // QuoteProvider doesn't provide slippage directly
+      provider: 'intents-sdk',
+      rawQuote: quote,
+      source: 'intents-sdk'
+    };
+  }
+
+  /**
+   * Gets quote from one-shot API
+   */
+  private async getOneShotQuote(params: UnifiedQuoteParams, signal?: AbortSignal): Promise<UnifiedQuoteResponse> {
+    const oneShotParams: OneShotQuoteParams = {
+      srcChain: params.sourceChainId,
+      destChain: params.destChainId,
+      srcToken: params.tokenIn,
+      destToken: params.tokenOut,
+      amount: params.amount.toString(),
+      senderAddress: params.senderAddress || '',
+      affiliateWallet: params.affiliateWallet || '',
+      affiliateFee: params.affiliateFee || '0',
+      slippage: params.slippageBps ? params.slippageBps / 100 : 0.5, // Convert bps to percentage
+      destinationAddress: params.destinationAddress || '',
+      dstChainOrderAuthorityAddress: '',
+      jitoTip: params.jitoTip,
+      gasRefuel: params.gasRefuel,
+      dynamicSlippage: params.dynamicSlippage,
+      externalCall: params.externalCall,
+    };
+
+    const quote = await fetchQuote(
+      {
+        key: this.config.apiKey,
+        url: this.config.apiUrl,
+      },
+      oneShotParams,
+      signal || new AbortController().signal,
+    );
+
+    if (quote.error) {
+      throw new Error(quote.error);
+    }
+
+    return {
+      amountOut: BigInt(quote.outputAmount.value),
+      amountInUsd: 0, // One-shot doesn't provide USD values directly
+      amountOutUsd: 0,
+      priceImpact: 0, // One-shot doesn't provide price impact directly
+      slippage: oneShotParams.slippage,
+      provider: 'one-shot',
+      rawQuote: quote,
+      source: 'one-shot'
+    };
+  }
+
+  /**
+   * Gets a single-chain quote from intents-sdk
+   * Useful for same-chain swaps
+   */
+  public async getSingleChainQuote(
+    chainId: ChainID,
+    tokenIn: string,
+    tokenOut: string,
+    amount: bigint,
+    slippageBps?: number,
+    _signal?: AbortSignal
+  ): Promise<UnifiedQuoteResponse> {
+    this.validateConfig();
+    
+    if (!chainId || !tokenIn || !tokenOut || amount <= 0n) {
+      throw new Error('Invalid parameters for single-chain quote');
+    }
+
+    this.debug('Fetching single-chain quote', { chainId, tokenIn, tokenOut, amount: amount.toString() });
+
+    try {
+      const quote = await QuoteProvider.getSingleChainQuote({
+        chainId,
+        amount,
+        tokenIn,
+        tokenOut,
+        slippageBps,
+      });
+
+      this.debug('Single-chain quote successful', { amountOut: quote.amountOut.toString() });
+
+      return {
+        amountOut: quote.amountOut,
+        amountInUsd: quote.amountInUsd,
+        amountOutUsd: quote.amountOutUsd,
+        priceImpact: quote.priceImpact,
+        slippage: quote.slippage,
+        provider: quote.provider,
+        rawQuote: quote.rawQuote,
+        source: 'intents-sdk'
+      };
+    } catch (error) {
+      this.debug('Single-chain quote failed', error);
+      return {
+        amountOut: 0n,
+        amountInUsd: 0,
+        amountOutUsd: 0,
+        priceImpact: 0,
+        slippage: 0,
+        provider: 'none',
+        rawQuote: null,
+        source: 'intents-sdk',
+        error: error instanceof Error ? error.message : 'Unknown error occurred'
+      };
+    }
+  }
+
+  /**
+   * Gets multiple quotes for comparison
+   * Useful for finding the best route
+   */
+  public async getMultipleQuotes(
+    params: UnifiedQuoteParams[],
+    signal?: AbortSignal
+  ): Promise<UnifiedQuoteResponse[]> {
+    this.debug('Fetching multiple quotes', { count: params.length });
+
+    const promises = params.map(param => this.getQuote(param, signal));
+    const results = await Promise.allSettled(promises);
+
+    return results.map((result) => {
+      if (result.status === 'fulfilled') {
+        return result.value;
+      } else {
+        return {
+          amountOut: 0n,
+          amountInUsd: 0,
+          amountOutUsd: 0,
+          priceImpact: 0,
+          slippage: 0,
+          provider: 'none',
+          rawQuote: null,
+          source: 'one-shot',
+          error: result.reason instanceof Error ? result.reason.message : 'Unknown error occurred'
+        };
+      }
+    });
+  }
+
+  /**
+   * Gets the best quote from multiple options
+   */
+  public async getBestQuote(
+    params: UnifiedQuoteParams[],
+    signal?: AbortSignal
+  ): Promise<UnifiedQuoteResponse | null> {
+    const quotes = await this.getMultipleQuotes(params, signal);
+    const validQuotes = quotes.filter(quote => !quote.error && quote.amountOut > 0n);
+
+    if (validQuotes.length === 0) {
+      return null;
+    }
+
+    // Return the quote with the highest output amount
+    return validQuotes.reduce((best, current) => 
+      current.amountOut > best.amountOut ? current : best
+    );
+  }
+
+  /**
+   * Estimates gas costs for a swap (EVM chains only)
+   */
+  public async estimateGas(
+    chainId: ChainID,
+    tokenIn: string,
+    tokenOut: string,
+    amount: bigint,
+    _userAddress: string
+  ): Promise<{ gasEstimate: bigint; gasPrice: bigint } | null> {
+    this.debug('Estimating gas', { chainId, tokenIn, tokenOut, amount: amount.toString() });
+
+    try {
+      // This would need to be implemented based on your specific needs
+      // For now, return a placeholder
+      return {
+        gasEstimate: 200000n, // Typical swap gas limit
+        gasPrice: 20000000000n // 20 gwei
+      };
+    } catch (error) {
+      this.debug('Gas estimation failed', error);
+      return null;
+    }
+  }
+
+  /**
+   * Validates if a token pair is supported for swapping
+   */
+  public async isTokenPairSupported(
+    chainId: ChainID,
+    tokenIn: string,
+    tokenOut: string
+  ): Promise<boolean> {
+    try {
+      // Try to get a minimal quote to check if the pair is supported
+      const quote = await this.getSingleChainQuote(
+        chainId,
+        tokenIn,
+        tokenOut,
+        BigInt('1'), // Minimal amount
+        1000 // 10% slippage for validation
+      );
+      
+      return !quote.error && quote.amountOut > 0n;
+    } catch (error) {
+      this.debug('Token pair validation failed', error);
+      return false;
+    }
+  }
+
+  /**
+   * Updates the client configuration
+   */
+  public updateConfig(newConfig: Partial<SwapClientConfig>): void {
+    Object.assign(this.config, newConfig);
+    this.validateConfig();
+    this.debug('Configuration updated', newConfig);
+  }
+
+  /**
+   * Gets the current configuration
+   */
+  public getConfig(): SwapClientConfig {
+    return { ...this.config };
+  }
+}