@xswap-link/sdk 0.10.7 → 0.10.9

package/src/services/svm/core/client/utils.ts

@@ -0,0 +1,131 @@
+import { Logger } from "../../utils/logger";
+import { ExtraArgsOptions } from "../models";
+import { BN } from "@coral-xyz/anchor";
+
+/**
+ * Creates extra arguments for CCIP send
+ * @param options Extra args options
+ * @param logger Optional logger instance
+ * @returns Buffer with encoded extra args
+ */
+export function createExtraArgs(
+  options?: ExtraArgsOptions,
+  logger?: Logger
+): Buffer {
+  if (logger) {
+    logger.debug(`Creating extraArgs buffer for CCIP message`);
+  }
+
+  // If no options provided, create a default buffer with allowOutOfOrderExecution=true
+  if (!options) {
+    if (logger) {
+      logger.warn(
+        `No options provided, creating default extraArgs with allowOutOfOrderExecution=true to avoid error 8030`
+      );
+    }
+
+    // Use the GENERIC_EXTRA_ARGS_V2_TAG which is bytes4(keccak256("CCIP EVMExtraArgsV2"))
+    const typeTag = Buffer.from([0x18, 0x1d, 0xcf, 0x10]);
+
+    // Default gas limit of 0 in little-endian format (16 bytes)
+    const gasLimitLE = Buffer.alloc(16, 0);
+
+    // Boolean true (1) for allowOutOfOrderExecution
+    const allowOutOfOrderExecutionByte = Buffer.from([1]);
+
+    // Concatenate for a properly formatted default buffer
+    const argsData = Buffer.concat([gasLimitLE, allowOutOfOrderExecutionByte]);
+    const result = Buffer.concat([typeTag, argsData]);
+
+    if (logger) {
+      logger.trace(
+        `Created default extraArgs buffer with allowOutOfOrderExecution=true`
+      );
+    }
+
+    return result;
+  }
+
+  // Get values from options with defaults
+  const gasLimit = options.gasLimit || 0;
+
+  // Handle the three cases for allowOutOfOrderExecution:
+  // 1. Undefined - we'll use true but inform the user
+  // 2. Explicitly false - we'll override to true with warning
+  // 3. Explicitly true - we'll use it as is
+
+  let warningMessage: string | null = null;
+
+  if (options.allowOutOfOrderExecution === undefined) {
+    // If undefined, we'll use true but log a message about the default behavior
+    warningMessage = `allowOutOfOrderExecution not specified, defaulting to true to avoid FeeQuoter error 8030`;
+  } else if (options.allowOutOfOrderExecution === false) {
+    // If explicitly false, we'll override it with a warning
+    warningMessage = `allowOutOfOrderExecution=false was explicitly specified but is not supported by FeeQuoter. Forcing to true to avoid error 8030.`;
+  }
+
+  // Log warning if needed
+  if (warningMessage && logger) {
+    logger.warn(warningMessage);
+  }
+
+  // Always use true regardless of what was specified
+  const allowOutOfOrderExecution = true;
+
+  // Log what we're doing
+  if (logger) {
+    const forcedMsg =
+      options.allowOutOfOrderExecution === false
+        ? " (forced)"
+        : options.allowOutOfOrderExecution === undefined
+        ? " (default)"
+        : "";
+    logger.debug(
+      `ExtraArgs options - gasLimit: ${gasLimit}, allowOutOfOrderExecution: true${forcedMsg}`
+    );
+  }
+
+  // Use the GENERIC_EXTRA_ARGS_V2_TAG which is bytes4(keccak256("CCIP EVMExtraArgsV2"))
+  // 0x181dcf10 in big-endian format
+  const typeTag = Buffer.from([0x18, 0x1d, 0xcf, 0x10]);
+  if (logger) {
+    logger.trace(`Using EVM ExtraArgs V2 type tag: 0x181dcf10`);
+  }
+
+  // Now we need to construct the serialized version of GenericExtraArgsV2
+  // Based on Anchor's serialization format:
+  // 1. gas_limit (u128) - 16 bytes
+  // 2. allow_out_of_order_execution (bool) - 1 byte (1 = true, 0 = false)
+
+  // Convert gas limit to little-endian bytes (Anchor uses little endian)
+  const gasLimitLE = new BN(gasLimit).toArrayLike(Buffer, "le", 16);
+
+  if (logger) {
+    logger.trace(
+      `Gas limit buffer (LE, 16 bytes): 0x${gasLimitLE.toString("hex")}`
+    );
+  }
+
+  // Create bool byte for allowOutOfOrderExecution - ALWAYS true (1)
+  const allowOutOfOrderExecutionByte = Buffer.from([1]);
+
+  if (logger) {
+    logger.trace(`AllowOutOfOrderExecution byte: 0x01 (true)`);
+  }
+
+  // Concatenate for the data part: gasLimit (LE) + allowOutOfOrderExecution
+  const argsData = Buffer.concat([gasLimitLE, allowOutOfOrderExecutionByte]);
+
+  // Final buffer is tag + serialized args
+  const result = Buffer.concat([typeTag, argsData]);
+
+  if (logger) {
+    logger.trace(
+      `Final extraArgs buffer (${result.length} bytes): 0x${result.toString(
+        "hex"
+      )}`
+    );
+  }
+
+  return result;
+}

package/src/services/svm/core/models.ts

@@ -0,0 +1,236 @@
+import {
+  PublicKey,
+  Keypair,
+  Connection,
+  Transaction,
+  VersionedTransaction,
+} from "@solana/web3.js";
+import { BN } from "@coral-xyz/anchor";
+import { LogLevel } from "../utils/logger";
+
+/**
+ * CCIP Send Request
+ */
+export interface CCIPSendRequest {
+  readonly destChainSelector: BN;
+  readonly receiver: Uint8Array;
+  readonly data: Uint8Array;
+  readonly tokenAmounts: {
+    readonly token: PublicKey;
+    readonly amount: BN;
+  }[];
+  readonly feeToken: PublicKey;
+  readonly extraArgs: Uint8Array;
+}
+
+/**
+ * CCIP Fee Request
+ */
+export interface CCIPFeeRequest {
+  readonly destChainSelector: BN;
+  readonly message: {
+    readonly receiver: Uint8Array;
+    readonly data: Uint8Array;
+    readonly tokenAmounts: {
+      readonly token: PublicKey;
+      readonly amount: BN;
+    }[];
+    readonly feeToken: PublicKey;
+    readonly extraArgs: Uint8Array;
+  };
+}
+
+/**
+ * Result of a fee calculation
+ */
+export interface GetFeeResult {
+  token: PublicKey;
+  amount: BN;
+  juels: BN;
+}
+
+/**
+ * Result of a CCIP send with message ID
+ */
+export interface CCIPSendResult {
+  txSignature: string;
+  messageId?: string;
+  destinationChainSelector?: string;
+  sequenceNumber?: string;
+}
+
+/**
+ * Extra arguments for CCIP send
+ */
+export interface ExtraArgsV1 {
+  gasLimit: number;
+  strict: boolean;
+}
+
+/**
+ * Options for creating extra arguments
+ */
+export interface ExtraArgsOptions {
+  gasLimit?: number;
+  allowOutOfOrderExecution?: boolean;
+}
+
+/**
+ * Options for CCIPClient configuration
+ */
+export interface CCIPClientOptions {
+  /**
+   * Log level for the client
+   * @default LogLevel.INFO
+   */
+  logLevel?: LogLevel;
+}
+
+/**
+ * Options for sending CCIP messages
+ */
+export interface CCIPSendOptions {
+  /**
+   * Whether to skip the preflight transaction check
+   * @default false
+   */
+  skipPreflight?: boolean;
+}
+
+/**
+ * Provider interface to abstract wallet and connection
+ */
+export interface CCIPProvider {
+  /** Solana RPC connection */
+  connection: Connection;
+
+  /** Wallet or keypair for signing transactions */
+  wallet: Keypair;
+
+  /** Get the public key address of the signer */
+  getAddress(): PublicKey;
+
+  /** Sign a transaction */
+  signTransaction(
+    tx: Transaction | VersionedTransaction,
+  ): Promise<Transaction | VersionedTransaction>;
+}
+
+/**
+ * Core configuration needed by all CCIP modules
+ */
+export interface CCIPCoreConfig {
+  /** CCIP Router program ID */
+  ccipRouterProgramId: PublicKey;
+
+  /** Fee Quoter program ID */
+  feeQuoterProgramId: PublicKey;
+
+  /** RMN Remote program ID */
+  rmnRemoteProgramId: PublicKey;
+
+  /** LINK token mint */
+  linkTokenMint: PublicKey;
+
+  /** Token mint for the application */
+  tokenMint: PublicKey;
+
+  /** Native SOL public key */
+  nativeSol: PublicKey;
+
+  /** System program ID */
+  systemProgramId: PublicKey;
+
+  /** CCIP receiver program ID */
+  programId: PublicKey;
+}
+
+/**
+ * Combined context with provider, config and logger
+ */
+export interface CCIPContext {
+  /** Provider for connecting to the blockchain */
+  provider: CCIPProvider;
+
+  /** Core configuration */
+  config: CCIPCoreConfig;
+
+  /** Optional logger */
+  logger?: Logger;
+}
+
+/**
+ * Options for creating a CCIP client from a keypair
+ */
+export interface CCIPClientKeypairOptions {
+  /** Path to keypair file */
+  keypairPath: string;
+
+  /** Core configuration */
+  config: CCIPCoreConfig;
+
+  /** Log level */
+  logLevel?: LogLevel;
+
+  /** RPC endpoint URL */
+  endpoint?: string;
+
+  /** Commitment level */
+  commitment?: string;
+}
+
+/**
+ * Logger interface imported from logger.ts
+ */
+export interface Logger {
+  trace(...message: any[]): void;
+  debug(...message: any[]): void;
+  info(...message: any[]): void;
+  warn(...message: any[]): void;
+  error(...message: any[]): void;
+  setLevel(level: LogLevel): void;
+  getLevel(): LogLevel;
+}
+
+/**
+ * Rate limit configuration for token pools in user-friendly format
+ */
+export interface TokenPoolRateLimitConfig {
+  /** Whether rate limiting is enabled */
+  isEnabled: boolean;
+  /** Maximum capacity of the rate limit bucket */
+  capacity: bigint;
+  /** Refill rate of tokens per second */
+  rate: bigint;
+  /** Last updated timestamp */
+  lastTxTimestamp: bigint;
+  /** Current number of tokens in the bucket */
+  currentBucketValue: bigint;
+}
+
+/**
+ * Chain configuration for burn-mint token pools with consistent naming
+ */
+export interface TokenPoolChainConfigResponse {
+  /** Chain config account address */
+  address: string;
+  /** Base configuration data */
+  base: {
+    /** Token decimals on remote chain */
+    decimals: number;
+    /** Pool addresses on remote chain */
+    poolAddresses: Array<{
+      /** Hex encoded address */
+      address: string;
+    }>;
+    /** Token address on remote chain */
+    tokenAddress: {
+      /** Hex encoded address */
+      address: string;
+    };
+    /** Inbound rate limit configuration */
+    inboundRateLimit: TokenPoolRateLimitConfig;
+    /** Outbound rate limit configuration */
+    outboundRateLimit: TokenPoolRateLimitConfig;
+  };
+}

package/src/services/svm/index.ts

@@ -0,0 +1,32 @@
+// Core components
+export * from "./core/client/accounts";
+export * from "./core/client/index";
+
+// Export models with specific names to avoid conflicts
+export type {
+  CCIPClientOptions,
+  CCIPSendRequest,
+  CCIPSendOptions,
+  CCIPFeeRequest,
+  CCIPSendResult,
+  ExtraArgsOptions,
+  ExtraArgsV1,
+  CCIPProvider,
+  CCIPCoreConfig,
+  CCIPContext,
+  CCIPClientKeypairOptions,
+} from "./core/models";
+
+// Utilities
+export * from "./utils/pdas";
+export * from "./utils/logger";
+export * from "./utils/errors";
+export * from "./utils/conversion";
+export * from "./utils/keypair";
+
+// Bindings exports
+export * from "./bindings/types";
+export * from "./bindings/accounts";
+
+// Export version
+export const SDK_VERSION = "0.1.0";

package/src/services/svm/utils/conversion.ts

@@ -0,0 +1,62 @@
+/**
+ * Utilities for Solana to EVM address conversion
+ */
+export class AddressConversion {
+  /**
+   * Converts an EVM address string (0x-prefixed) into a 32-byte left-padded Uint8Array.
+   * Required for EVM-to-Solana compatibility in programs expecting 32-byte addresses.
+   * @param evmAddress EVM address (0x-prefixed)
+   * @returns 32-byte padded address as Uint8Array
+   */
+  static evmAddressToSolanaBytes(evmAddress: string): Uint8Array {
+    return this.leftPadBytes(this.hexToBytes(evmAddress), 32);
+  }
+
+  /**
+   * Pretty prints a byte array as a 0x-prefixed hex string
+   * @param bytes Byte array
+   * @returns Hex string
+   */
+  static bytesToHexString(bytes: Uint8Array): string {
+    return '0x' + Buffer.from(bytes).toString('hex');
+  }
+
+  /**
+   * Converts a hex string to a byte array
+   * @param hex Hex string
+   * @returns Byte array
+   */
+  private static hexToBytes(hex: string): Uint8Array {
+    if (hex.startsWith('0x')) hex = hex.slice(2);
+    if (hex.length !== 40) throw new Error('Invalid Ethereum address length');
+    const bytes = new Uint8Array(20);
+    for (let i = 0; i < 40; i += 2) {
+      bytes[i / 2] = parseInt(hex.slice(i, i + 2), 16);
+    }
+    return bytes;
+  }
+
+  /**
+   * Left pads a byte array to a specified length
+   * @param data Data to pad
+   * @param length Target length
+   * @returns Padded byte array
+   */
+  private static leftPadBytes(data: Uint8Array, length: number): Uint8Array {
+    if (data.length > length) throw new Error('Data too long to pad');
+    const padded = new Uint8Array(length);
+    padded.set(data, length - data.length);
+    return padded;
+  }
+}
+
+/**
+ * Creates a buffer from a BigInt
+ * @param value BigInt value
+ * @returns Buffer
+ */
+export function createBufferFromBigInt(value: bigint): Buffer {
+  const buffer = Buffer.alloc(8);
+  buffer.writeBigUInt64LE(value);
+  return buffer;
+} 

package/src/services/svm/utils/errors.ts

@@ -0,0 +1,51 @@
+import { Logger } from "./logger";
+
+/**
+ * Base CCIP error class for standardized error handling
+ */
+export class CCIPError extends Error {
+  constructor(message: string, public context?: Record<string, unknown>) {
+    super(message);
+    this.name = "CCIPError";
+  }
+}
+
+/**
+ * Enhances an error with additional context for better diagnostics
+ * @param error Original error
+ * @param context Additional context to add
+ * @param logger Optional logger instance
+ * @returns Enhanced error with context attached
+ */
+export function enhanceError(
+  error: unknown,
+  context: Record<string, unknown>,
+  logger?: Logger
+): Error {
+  const enhancedError =
+    error instanceof Error ? error : new Error(String(error));
+
+  // Attach context to the error
+  (enhancedError as any).context = context;
+
+  // Log the enhanced error if a logger is provided
+  if (logger) {
+    logger.error(`Error: ${enhancedError.message}`, {
+      context,
+      stack: enhancedError.stack,
+    });
+  }
+
+  return enhancedError;
+}
+
+/**
+ * Creates a type-safe error enhancer bound to a specific logger instance
+ * @param logger Logger instance to use for error logging
+ * @returns A function that enhances errors with context
+ */
+export function createErrorEnhancer(logger: Logger) {
+  return (error: unknown, context: Record<string, unknown>): Error => {
+    return enhanceError(error, context, logger);
+  };
+} 

package/src/services/svm/utils/keypair.ts

@@ -0,0 +1,19 @@
+import { Keypair } from "@solana/web3.js";
+
+// Default file paths
+export const DEFAULT_KEYPAIR_PATH = "";
+
+/**
+ * Loads a keypair from a file
+ * @param filePath Path to keypair file
+ * @returns Keypair
+ */
+export function loadKeypair(filePath: string = DEFAULT_KEYPAIR_PATH): Keypair {
+  try {
+    const keypairJson = JSON.parse("keypairData");
+    return Keypair.fromSecretKey(Buffer.from(keypairJson));
+  } catch (error) {
+    console.error(`Error loading keypair from ${filePath}:`, error);
+    throw error;
+  }
+}

package/src/services/svm/utils/logger.ts

@@ -0,0 +1,171 @@
+import loglevel from 'loglevel';
+
+/**
+ * Log levels available in the CCIP SDK
+ */
+export enum LogLevel {
+  TRACE = 0,
+  DEBUG = 1,
+  INFO = 2,
+  WARN = 3,
+  ERROR = 4,
+  SILENT = 5
+}
+
+/**
+ * SDK logging namespace prefix
+ */
+export const NAMESPACE = 'ccip';
+
+/**
+ * Logger interface with all available logging methods
+ */
+export interface Logger {
+  trace(...message: any[]): void;
+  debug(...message: any[]): void;
+  info(...message: any[]): void;
+  warn(...message: any[]): void;
+  error(...message: any[]): void;
+  setLevel(level: LogLevel): void;
+  getLevel(): LogLevel;
+}
+
+/**
+ * Logger options for configuration
+ */
+export interface LoggerOptions {
+  level?: LogLevel;
+  timestamps?: boolean;
+}
+
+/**
+ * Default logger options
+ */
+const DEFAULT_OPTIONS: LoggerOptions = {
+  level: LogLevel.INFO,
+  timestamps: true
+};
+
+/**
+ * Creates a namespaced logger with the given component name
+ * @param component Component name to create a logger for
+ * @param options Logger configuration options
+ * @returns A configured logger instance
+ */
+export function createLogger(component: string, options?: LoggerOptions): Logger {
+  const fullOptions = { ...DEFAULT_OPTIONS, ...options };
+  const loggerName = component ? `${NAMESPACE}:${component}` : NAMESPACE;
+  
+  // Get the underlying loglevel logger
+  const baseLogger = loglevel.getLogger(loggerName);
+  
+  // Set the initial level
+  baseLogger.setLevel(fullOptions.level as unknown as loglevel.LogLevelDesc);
+  
+  // Create our wrapper logger with timestamps if enabled
+  const logger: Logger = {
+    trace: createLogMethod(baseLogger, 'trace', fullOptions),
+    debug: createLogMethod(baseLogger, 'debug', fullOptions),
+    info: createLogMethod(baseLogger, 'info', fullOptions),
+    warn: createLogMethod(baseLogger, 'warn', fullOptions),
+    error: createLogMethod(baseLogger, 'error', fullOptions),
+    
+    setLevel(level: LogLevel) {
+      baseLogger.setLevel(level as unknown as loglevel.LogLevelDesc);
+    },
+    
+    getLevel(): LogLevel {
+      return baseLogger.getLevel() as unknown as LogLevel;
+    }
+  };
+  
+  return logger;
+}
+
+/**
+ * Create a log method with optional timestamp
+ */
+function createLogMethod(
+  logger: loglevel.Logger,
+  method: 'trace' | 'debug' | 'info' | 'warn' | 'error',
+  options: LoggerOptions
+): (...args: any[]) => void {
+  return function(...args: any[]) {
+    // Skip logging if the current level is higher than this method's level
+    const methodLevel = getMethodLogLevel(method);
+    if (methodLevel < (logger.getLevel() as unknown as LogLevel)) {
+      return;
+    }
+    
+    if (options.timestamps) {
+      const timestamp = new Date().toISOString();
+      
+      // For trace level, customize the output to avoid showing stack traces
+      if (method === 'trace') {
+        // Format objects for better readability
+        const formattedArgs = args.map(arg => {
+          if (typeof arg === 'object' && arg !== null) {
+            return JSON.stringify(arg, null, 2);
+          }
+          return arg;
+        });
+        
+        // Use console.log directly with a prefix for trace level
+        console.log(`TRACE: [${timestamp}]`, ...formattedArgs);
+      } else {
+        // Use loglevel for other log levels
+        logger[method](`[${timestamp}]`, ...args);
+      }
+    } else {
+      if (method === 'trace') {
+        // Format objects for better readability
+        const formattedArgs = args.map(arg => {
+          if (typeof arg === 'object' && arg !== null) {
+            return JSON.stringify(arg, null, 2);
+          }
+          return arg;
+        });
+        
+        // Use console.log directly without timestamps
+        console.log(`TRACE:`, ...formattedArgs);
+      } else {
+        // Use loglevel for other log levels
+        logger[method](...args);
+      }
+    }
+  };
+}
+
+/**
+ * Convert method name to LogLevel enum value
+ */
+function getMethodLogLevel(method: 'trace' | 'debug' | 'info' | 'warn' | 'error'): LogLevel {
+  switch (method) {
+    case 'trace': return LogLevel.TRACE;
+    case 'debug': return LogLevel.DEBUG;
+    case 'info': return LogLevel.INFO;
+    case 'warn': return LogLevel.WARN;
+    case 'error': return LogLevel.ERROR;
+    default: return LogLevel.INFO;
+  }
+}
+
+/**
+ * Root SDK logger instance
+ */
+export const rootLogger = createLogger('');
+
+/**
+ * Set the global log level for all CCIP loggers
+ * @param level The log level to set globally
+ */
+export function setGlobalLogLevel(level: LogLevel): void {
+  loglevel.setLevel(level as unknown as loglevel.LogLevelDesc);
+}
+
+/**
+ * Reset all loggers to their default levels
+ */
+export function resetLoggers(): void {
+  loglevel.setDefaultLevel(loglevel.levels.INFO);
+}