sol-trade-sdk 0.1.0

package/src/trading/executor.ts

@@ -0,0 +1,385 @@
+/**
+ * Trade Executor for Sol Trade SDK
+ * Implements core trading execution with parallel SWQOS submissions.
+ */
+
+import {
+  Connection,
+  Transaction,
+  TransactionInstruction,
+  PublicKey,
+  Keypair,
+  BlockhashWithExpiryBlockHeight,
+  Commitment,
+} from '@solana/web3.js';
+import {
+  SwqosClient,
+  ClientFactory,
+  SwqosClientConfig,
+} from '../swqos/clients';
+import {
+  GasFeeStrategy,
+  GasFeeStrategyType,
+  SwqosType,
+  TradeType,
+} from '../common/gas-fee-strategy';
+
+// ===== Types =====
+
+export interface TradeResult {
+  signature: string;
+  success: boolean;
+  error?: string;
+  confirmationTimeMs?: number;
+}
+
+export interface ExecutorOptions {
+  waitConfirmation: boolean;
+  maxRetries: number;
+  retryDelayMs: number;
+  parallelSubmit: boolean;
+}
+
+export function defaultExecutorOptions(): ExecutorOptions {
+  return {
+    waitConfirmation: true,
+    maxRetries: 3,
+    retryDelayMs: 100,
+    parallelSubmit: true,
+  };
+}
+
+export interface TradeConfig {
+  rpcUrl: string;
+  swqosConfigs: SwqosClientConfig[];
+  gasFeeStrategy?: GasFeeStrategy;
+  confirmationTimeoutMs?: number;
+  confirmationRetryCount?: number;
+  /** RPC commitment for `Connection` (default `confirmed`); align with main `TradeConfig`. */
+  commitment?: Commitment;
+}
+
+export interface BuildTransactionOptions {
+  payer: PublicKey;
+  recentBlockhash: string;
+  instructions: TransactionInstruction[];
+  signers: Keypair[];
+  gasConfig?: GasFeeConfig;
+}
+
+export interface GasFeeConfig {
+  computeUnitLimit: number;
+  computeUnitPrice: number;
+  priorityFee: number;
+}
+
+// ===== Trade Executor =====
+
+export class TradeExecutor {
+  private clients: Map<SwqosType, SwqosClient> = new Map();
+  private connection: Connection;
+  private gasStrategy?: GasFeeStrategy;
+  private confirmationTimeout: number;
+  private confirmationRetry: number;
+
+  constructor(private config: TradeConfig) {
+    this.connection = new Connection(config.rpcUrl, {
+      commitment: config.commitment ?? 'confirmed',
+    });
+    this.gasStrategy = config.gasFeeStrategy;
+    this.confirmationTimeout = config.confirmationTimeoutMs || 30000;
+    this.confirmationRetry = config.confirmationRetryCount || 30;
+    this.initializeClients();
+  }
+
+  private initializeClients(): void {
+    for (const swqosConfig of this.config.swqosConfigs) {
+      const client = ClientFactory.createClient(swqosConfig, this.config.rpcUrl);
+      this.clients.set(swqosConfig.type, client);
+    }
+  }
+
+  addClient(config: SwqosClientConfig): void {
+    const client = ClientFactory.createClient(config, this.config.rpcUrl);
+    this.clients.set(config.type, client);
+  }
+
+  removeClient(swqosType: SwqosType): void {
+    this.clients.delete(swqosType);
+  }
+
+  getClient(swqosType: SwqosType): SwqosClient | undefined {
+    return this.clients.get(swqosType);
+  }
+
+  async execute(
+    tradeType: TradeType,
+    transaction: Buffer,
+    opts: ExecutorOptions = defaultExecutorOptions()
+  ): Promise<TradeResult> {
+    if (this.clients.size === 0) {
+      return {
+        signature: '',
+        success: false,
+        error: 'No SWQOS clients configured',
+      };
+    }
+
+    if (opts.parallelSubmit) {
+      return this.executeParallel(tradeType, transaction, opts);
+    }
+    return this.executeSequential(tradeType, transaction, opts);
+  }
+
+  private async executeParallel(
+    tradeType: TradeType,
+    transaction: Buffer,
+    opts: ExecutorOptions
+  ): Promise<TradeResult> {
+    const promises: Promise<TradeResult>[] = [];
+
+    for (const client of this.clients.values()) {
+      promises.push(this.submitToClient(client, tradeType, transaction, opts));
+    }
+
+    // Race all submissions - first successful wins
+    try {
+      const results = await Promise.allSettled(promises);
+      for (const result of results) {
+        if (result.status === 'fulfilled' && result.value.success) {
+          return result.value;
+        }
+      }
+      // All failed
+      const lastError = results.find(r => r.status === 'rejected') as PromiseRejectedResult;
+      return {
+        signature: '',
+        success: false,
+        error: lastError?.reason?.toString() || 'All parallel submissions failed',
+      };
+    } catch (error) {
+      return {
+        signature: '',
+        success: false,
+        error: error instanceof Error ? error.message : 'Unknown error',
+      };
+    }
+  }
+
+  private async executeSequential(
+    tradeType: TradeType,
+    transaction: Buffer,
+    opts: ExecutorOptions
+  ): Promise<TradeResult> {
+    for (let retry = 0; retry < opts.maxRetries; retry++) {
+      for (const client of this.clients.values()) {
+        const result = await this.submitToClient(client, tradeType, transaction, opts);
+        if (result.success) {
+          return result;
+        }
+      }
+
+      if (retry < opts.maxRetries - 1) {
+        await this.sleep(opts.retryDelayMs);
+      }
+    }
+
+    return {
+      signature: '',
+      success: false,
+      error: `All sequential submissions failed after ${opts.maxRetries} retries`,
+    };
+  }
+
+  private async submitToClient(
+    client: SwqosClient,
+    tradeType: TradeType,
+    transaction: Buffer,
+    opts: ExecutorOptions
+  ): Promise<TradeResult> {
+    const startTime = Date.now();
+
+    try {
+      const signature = await client.sendTransaction(
+        tradeType,
+        transaction,
+        false
+      );
+
+      const result: TradeResult = {
+        signature,
+        success: true,
+        confirmationTimeMs: Date.now() - startTime,
+      };
+
+      if (opts.waitConfirmation) {
+        const confirmed = await this.waitForConfirmation(signature);
+        result.confirmationTimeMs = Date.now() - startTime;
+        if (!confirmed) {
+          result.success = false;
+          result.error = 'Transaction failed to confirm';
+        }
+      }
+
+      return result;
+    } catch (error) {
+      return {
+        signature: '',
+        success: false,
+        error: error instanceof Error ? error.message : 'Unknown error',
+        confirmationTimeMs: Date.now() - startTime,
+      };
+    }
+  }
+
+  /** Rust `poll_any_transaction_confirmation`: success when err is none and status is confirmed or finalized. */
+  private async waitForConfirmation(signature: string): Promise<boolean> {
+    const startTime = Date.now();
+    const timeoutMs = this.confirmationTimeout;
+
+    while (Date.now() - startTime < timeoutMs) {
+      try {
+        const status = await this.connection.getSignatureStatus(signature);
+        if (status.value) {
+          if (status.value.err) {
+            return false;
+          }
+          const cs = status.value.confirmationStatus;
+          if (cs === 'confirmed' || cs === 'finalized') {
+            return true;
+          }
+        }
+      } catch {
+        // Continue polling on error
+      }
+
+      await this.sleep(1000);
+    }
+
+    return false;
+  }
+
+  private sleep(ms: number): Promise<void> {
+    return new Promise(resolve => setTimeout(resolve, ms));
+  }
+
+  async executeMultiple(
+    tradeType: TradeType,
+    transactions: Buffer[],
+    opts: ExecutorOptions = defaultExecutorOptions()
+  ): Promise<TradeResult[]> {
+    return Promise.all(
+      transactions.map(tx => this.execute(tradeType, tx, opts))
+    );
+  }
+
+  // ===== Gas Fee Management =====
+
+  getGasConfig(
+    swqosType: SwqosType,
+    tradeType: TradeType,
+    strategyType: GasFeeStrategyType
+  ): GasFeeConfig {
+    if (!this.gasStrategy) {
+      return {
+        computeUnitLimit: 200000,
+        computeUnitPrice: 100000,
+        priorityFee: 100000,
+      };
+    }
+
+    const value = this.gasStrategy.get(swqosType, tradeType, strategyType);
+    if (!value) {
+      return {
+        computeUnitLimit: 200000,
+        computeUnitPrice: 100000,
+        priorityFee: 100000,
+      };
+    }
+
+    return {
+      computeUnitLimit: value.cuLimit,
+      computeUnitPrice: value.cuPrice,
+      priorityFee: Math.floor(value.tip * 1_000_000_000), // Convert SOL to lamports
+    };
+  }
+
+  // ===== Utility Methods =====
+
+  async getLatestBlockhash(): Promise<BlockhashWithExpiryBlockHeight> {
+    return this.connection.getLatestBlockhash();
+  }
+
+  getConnection(): Connection {
+    return this.connection;
+  }
+}
+
+// ===== Rate Limiter =====
+
+export class RateLimiter {
+  private lastSubmit: number = 0;
+
+  constructor(private minDelayMs: number) {}
+
+  async wait(): Promise<void> {
+    const now = Date.now();
+    const elapsed = now - this.lastSubmit;
+    
+    if (elapsed < this.minDelayMs) {
+      await this.sleep(this.minDelayMs - elapsed);
+    }
+    
+    this.lastSubmit = Date.now();
+  }
+
+  private sleep(ms: number): Promise<void> {
+    return new Promise(resolve => setTimeout(resolve, ms));
+  }
+}
+
+// ===== Metrics Collector =====
+
+export class MetricsCollector {
+  private totalTrades: number = 0;
+  private successTrades: number = 0;
+  private failedTrades: number = 0;
+  private totalLatency: number = 0;
+
+  recordTrade(success: boolean, latencyMs: number): void {
+    this.totalTrades++;
+    if (success) {
+      this.successTrades++;
+    } else {
+      this.failedTrades++;
+    }
+    this.totalLatency += latencyMs;
+  }
+
+  getStats(): { total: number; success: number; failed: number; avgLatencyMs: number } {
+    return {
+      total: this.totalTrades,
+      success: this.successTrades,
+      failed: this.failedTrades,
+      avgLatencyMs: this.totalTrades > 0 ? this.totalLatency / this.totalTrades : 0,
+    };
+  }
+}
+
+// ===== Convenience Functions =====
+
+export function createTradeExecutor(
+  rpcUrl: string,
+  swqosTypes: SwqosType[],
+  apiKeys?: Map<SwqosType, string>
+): TradeExecutor {
+  const swqosConfigs: SwqosClientConfig[] = swqosTypes.map(type => ({
+    type,
+    apiKey: apiKeys?.get(type),
+  }));
+
+  return new TradeExecutor({
+    rpcUrl,
+    swqosConfigs,
+  });
+}

package/src/trading/factory.ts

@@ -0,0 +1,282 @@
+/**
+ * Trading factory and executor for Sol Trade SDK
+ *
+ * Provides factory methods for creating trade executors for different DEX protocols
+ */
+
+import type { PublicKey } from '@solana/web3.js';
+
+// ===== DEX Types =====
+
+export enum DexType {
+  PumpFun = 'PumpFun',
+  PumpSwap = 'PumpSwap',
+  Bonk = 'Bonk',
+  RaydiumCpmm = 'RaydiumCpmm',
+  RaydiumAmmV4 = 'RaydiumAmmV4',
+  MeteoraDammV2 = 'MeteoraDammV2',
+}
+
+export enum TradeType {
+  Buy = 'Buy',
+  Sell = 'Sell',
+  Create = 'Create',
+  CreateAndBuy = 'CreateAndBuy',
+}
+
+// ===== Trade Result Types =====
+
+export interface TradeResult {
+  signature: string;
+  success: boolean;
+  error?: string;
+  confirmationTimeMs?: number;
+  submittedAt?: Date;
+  confirmedAt?: Date;
+  retries?: number;
+}
+
+export interface BatchTradeResult {
+  results: TradeResult[];
+  totalTimeMs: number;
+  successCount: number;
+  failedCount: number;
+}
+
+// ===== Execute Options =====
+
+export interface TradeExecuteOptions {
+  waitConfirmation?: boolean;
+  maxRetries?: number;
+  retryDelayMs?: number;
+  parallelSubmit?: boolean;
+  timeoutMs?: number;
+  priority?: number;
+  skipPreflight?: boolean;
+}
+
+export function defaultTradeExecuteOptions(): TradeExecuteOptions {
+  return {
+    waitConfirmation: true,
+    maxRetries: 3,
+    retryDelayMs: 100,
+    parallelSubmit: true,
+    timeoutMs: 30000,
+    priority: 0,
+    skipPreflight: false,
+  };
+}
+
+// ===== Protocol Params =====
+
+export interface PumpFunParams {
+  bondingCurve?: any;
+  associatedBondingCurve?: PublicKey;
+  creatorVault?: PublicKey;
+  tokenProgram?: PublicKey;
+  closeTokenAccountWhenSell?: boolean;
+}
+
+export interface PumpSwapParams {
+  pool?: PublicKey;
+  baseMint?: PublicKey;
+  quoteMint?: PublicKey;
+  poolBaseTokenAccount?: PublicKey;
+  poolQuoteTokenAccount?: PublicKey;
+  poolBaseTokenReserves?: bigint;
+  poolQuoteTokenReserves?: bigint;
+  coinCreatorVaultAta?: PublicKey;
+  coinCreatorVaultAuthority?: PublicKey;
+  baseTokenProgram?: PublicKey;
+  quoteTokenProgram?: PublicKey;
+  isMayhemMode?: boolean;
+  isCashbackCoin?: boolean;
+}
+
+export interface BonkParams {
+  virtualBase?: bigint;
+  virtualQuote?: bigint;
+  realBase?: bigint;
+  realQuote?: bigint;
+  poolState?: PublicKey;
+  baseVault?: PublicKey;
+  quoteVault?: PublicKey;
+  mintTokenProgram?: PublicKey;
+  platformConfig?: PublicKey;
+  platformAssociatedAccount?: PublicKey;
+  creatorAssociatedAccount?: PublicKey;
+  globalConfig?: PublicKey;
+}
+
+export interface RaydiumCpmmParams {
+  poolState?: PublicKey;
+  ammConfig?: PublicKey;
+  baseMint?: PublicKey;
+  quoteMint?: PublicKey;
+  baseReserve?: bigint;
+  quoteReserve?: bigint;
+  baseVault?: PublicKey;
+  quoteVault?: PublicKey;
+  baseTokenProgram?: PublicKey;
+  quoteTokenProgram?: PublicKey;
+  observationState?: PublicKey;
+}
+
+export interface RaydiumAmmV4Params {
+  amm?: PublicKey;
+  coinMint?: PublicKey;
+  pcMint?: PublicKey;
+  tokenCoin?: PublicKey;
+  tokenPc?: PublicKey;
+  coinReserve?: bigint;
+  pcReserve?: bigint;
+}
+
+export interface MeteoraDammV2Params {
+  pool?: PublicKey;
+  tokenAVault?: PublicKey;
+  tokenBVault?: PublicKey;
+  tokenAMint?: PublicKey;
+  tokenBMint?: PublicKey;
+  tokenAProgram?: PublicKey;
+  tokenBProgram?: PublicKey;
+}
+
+// ===== Trade Executor Interface =====
+
+export interface ITradeExecutor {
+  executeBuy(_params: Record<string, unknown>, _opts?: TradeExecuteOptions): Promise<TradeResult>;
+  executeSell(_params: Record<string, unknown>, _opts?: TradeExecuteOptions): Promise<TradeResult>;
+}
+
+// ===== Base Executor =====
+
+export abstract class BaseExecutor implements ITradeExecutor {
+  abstract executeBuy(_params: Record<string, unknown>, _opts?: TradeExecuteOptions): Promise<TradeResult>;
+  abstract executeSell(_params: Record<string, unknown>, _opts?: TradeExecuteOptions): Promise<TradeResult>;
+
+  protected buildResult(
+    signature: string,
+    success: boolean,
+    error?: string
+  ): TradeResult {
+    return {
+      signature,
+      success,
+      error,
+      submittedAt: new Date(),
+    };
+  }
+}
+
+// ===== PumpFun Executor =====
+
+export class PumpFunExecutor extends BaseExecutor {
+  async executeBuy(_params: Record<string, unknown>, _opts?: TradeExecuteOptions): Promise<TradeResult> {
+    return this.buildResult('', true);
+  }
+
+  async executeSell(_params: Record<string, unknown>, _opts?: TradeExecuteOptions): Promise<TradeResult> {
+    return this.buildResult('', true);
+  }
+}
+
+// ===== PumpSwap Executor =====
+
+export class PumpSwapExecutor extends BaseExecutor {
+  async executeBuy(_params: Record<string, unknown>, _opts?: TradeExecuteOptions): Promise<TradeResult> {
+    return this.buildResult('', true);
+  }
+
+  async executeSell(_params: Record<string, unknown>, _opts?: TradeExecuteOptions): Promise<TradeResult> {
+    return this.buildResult('', true);
+  }
+}
+
+// ===== Bonk Executor =====
+
+export class BonkExecutor extends BaseExecutor {
+  async executeBuy(_params: Record<string, unknown>, _opts?: TradeExecuteOptions): Promise<TradeResult> {
+    return this.buildResult('', true);
+  }
+
+  async executeSell(_params: Record<string, unknown>, _opts?: TradeExecuteOptions): Promise<TradeResult> {
+    return this.buildResult('', true);
+  }
+}
+
+// ===== Raydium CPMM Executor =====
+
+export class RaydiumCpmmExecutor extends BaseExecutor {
+  async executeBuy(_params: Record<string, unknown>, _opts?: TradeExecuteOptions): Promise<TradeResult> {
+    return this.buildResult('', true);
+  }
+
+  async executeSell(_params: Record<string, unknown>, _opts?: TradeExecuteOptions): Promise<TradeResult> {
+    return this.buildResult('', true);
+  }
+}
+
+// ===== Raydium AMM V4 Executor =====
+
+export class RaydiumAmmV4Executor extends BaseExecutor {
+  async executeBuy(_params: Record<string, unknown>, _opts?: TradeExecuteOptions): Promise<TradeResult> {
+    return this.buildResult('', true);
+  }
+
+  async executeSell(_params: Record<string, unknown>, _opts?: TradeExecuteOptions): Promise<TradeResult> {
+    return this.buildResult('', true);
+  }
+}
+
+// ===== Meteora DAMM V2 Executor =====
+
+export class MeteoraDammV2Executor extends BaseExecutor {
+  async executeBuy(_params: Record<string, unknown>, _opts?: TradeExecuteOptions): Promise<TradeResult> {
+    return this.buildResult('', true);
+  }
+
+  async executeSell(_params: Record<string, unknown>, _opts?: TradeExecuteOptions): Promise<TradeResult> {
+    return this.buildResult('', true);
+  }
+}
+
+// ===== Trade Executor Factory =====
+
+export class TradeExecutorFactory {
+  private static executors: Map<DexType, () => ITradeExecutor> = new Map([
+    [DexType.PumpFun, () => new PumpFunExecutor()],
+    [DexType.PumpSwap, () => new PumpSwapExecutor()],
+    [DexType.Bonk, () => new BonkExecutor()],
+    [DexType.RaydiumCpmm, () => new RaydiumCpmmExecutor()],
+    [DexType.RaydiumAmmV4, () => new RaydiumAmmV4Executor()],
+    [DexType.MeteoraDammV2, () => new MeteoraDammV2Executor()],
+  ]);
+
+  /**
+   * Create a trade executor for the given DEX type
+   */
+  static createExecutor(dexType: DexType): ITradeExecutor {
+    const factory = this.executors.get(dexType);
+    if (!factory) {
+      throw new Error(`No executor available for DEX type: ${dexType}`);
+    }
+    return factory();
+  }
+
+  /**
+   * Register a custom executor factory
+   */
+  static registerExecutor(dexType: DexType, factory: () => ITradeExecutor): void {
+    this.executors.set(dexType, factory);
+  }
+
+  /**
+   * Get supported DEX types
+   */
+  static getSupportedDexTypes(): DexType[] {
+    return Array.from(this.executors.keys());
+  }
+}
+
+// Main `TradingClient` lives in `src/index.ts` (parity with Rust SDK). Use `TradeExecutorFactory` for protocol stubs/tests.

package/src/trading/index.ts

@@ -0,0 +1,30 @@
+/**
+ * Trading module exports
+ */
+
+export * from './executor';
+export * from './core';
+export {
+  DexType,
+  TradeType as FactoryTradeType,
+  defaultTradeExecuteOptions,
+  PumpFunExecutor,
+  PumpSwapExecutor,
+  BonkExecutor,
+  RaydiumCpmmExecutor,
+  RaydiumAmmV4Executor,
+  MeteoraDammV2Executor,
+  TradeExecutorFactory,
+} from './factory';
+export type {
+  TradeResult as FactoryTradeResult,
+  BatchTradeResult,
+  TradeExecuteOptions,
+  PumpFunParams,
+  PumpSwapParams,
+  BonkParams,
+  RaydiumCpmmParams,
+  RaydiumAmmV4Params,
+  MeteoraDammV2Params,
+  ITradeExecutor,
+} from './factory';

package/src/types.ts

@@ -0,0 +1,8 @@
+/**
+ * Types module for Sol Trade SDK
+ */
+
+export * from './common/gas-fee-strategy';
+export * from './calc';
+export * from './swqos';
+export * from './trading';