sol-trade-sdk 0.1.0 → 0.1.2

package/README.md

@@ -71,19 +71,26 @@ This SDK is available in multiple languages:
 | **Python** | [sol-trade-sdk-python](https://github.com/0xfnzero/sol-trade-sdk-python) | Async/await native support |
 | **Go** | [sol-trade-sdk-golang](https://github.com/0xfnzero/sol-trade-sdk-golang) | Concurrent-safe with goroutine support |
 
+## 🔖 Current Release
+
+**npm package:** `sol-trade-sdk@0.1.2`
+
+This release refreshes PumpFun V2 and USDC quote-pool handling, keeps the default RPC submit lane active alongside SWQoS lanes, and aligns Raydium CPMM fixed-output swaps with the on-chain `swap_base_out` instruction. Trade execution requires a caller-supplied `recentBlockhash` or durable nonce; hot-path execution does not query RPC for blockhash, account, or balance data.
+
 ## ✨ Features
 
-1. **PumpFun Trading**: Support for `buy` and `sell` operations
+1. **PumpFun Trading**: Unified `buy`, `sell`, and `buy_exact_quote_in` flow with automatic legacy or V2 instruction selection for SOL and USDC quote pools
 2. **PumpSwap Trading**: Support for PumpSwap pool trading operations
 3. **Bonk Trading**: Support for Bonk trading operations
 4. **Raydium CPMM Trading**: Support for Raydium CPMM (Concentrated Pool Market Maker) trading operations
 5. **Raydium AMM V4 Trading**: Support for Raydium AMM V4 (Automated Market Maker) trading operations
 6. **Meteora DAMM V2 Trading**: Support for Meteora DAMM V2 (Dynamic AMM) trading operations
 7. **Multiple MEV Protection**: Support for Jito, Nextblock, ZeroSlot, Temporal, Bloxroute, FlashBlock, BlockRazor, Node1, Astralane and other services
-8. **Concurrent Trading**: Send transactions using multiple MEV services simultaneously; the fastest succeeds while others fail
+8. **Concurrent Trading**: Submit through every configured SWQoS provider plus the default RPC lane; the first accepted result can return early while slower routes continue submitting
 9. **Unified Trading Interface**: Use unified trading protocol types for trading operations
 10. **Middleware System**: Support for custom instruction middleware to modify, add, or remove instructions before transaction execution
 11. **Shared Infrastructure**: Share expensive RPC and SWQoS clients across multiple wallets for reduced resource usage
+12. **Hot-Path RPC Boundary**: Trade execution uses caller-supplied blockhash or durable nonce and never queries RPC for blockhash, account, or balance data
 
 ## 📦 Installation
 
@@ -117,11 +124,11 @@ Add to your `package.json`:
 ### Use NPM
 
 ```bash
-npm install sol-trade-sdk
+npm install sol-trade-sdk@0.1.2
 # or
-yarn add sol-trade-sdk
+yarn add sol-trade-sdk@0.1.2
 # or
-pnpm add sol-trade-sdk
+pnpm add sol-trade-sdk@0.1.2
 ```
 
 ## 🛠️ Usage Examples

package/dist/cache/index.d.mts

@@ -0,0 +1,70 @@
+/**
+ * High-Performance Cache Implementation for Sol Trade SDK
+ * Provides LRU, TTL, and sharded caches for optimal performance.
+ */
+interface CacheStats {
+    hits: number;
+    misses: number;
+    evictions: number;
+    size: number;
+    hitRate: number;
+}
+/**
+ * Thread-safe LRU cache with TTL support.
+ * O(1) get and set operations.
+ */
+declare class LRUCache<K, V> {
+    private cache;
+    private maxSize;
+    private ttl;
+    private hits;
+    private misses;
+    private evictions;
+    constructor(maxSize?: number, ttl?: number);
+    get(key: K): V | undefined;
+    set(key: K, value: V): void;
+    delete(key: K): boolean;
+    clear(): void;
+    cleanup(): number;
+    getStats(): CacheStats;
+}
+/**
+ * Simple TTL cache with fast reads.
+ */
+declare class TTLCache<K, V> {
+    private cache;
+    private ttl;
+    private hits;
+    private misses;
+    constructor(ttl?: number);
+    get(key: K): V | undefined;
+    set(key: K, value: V): void;
+    delete(key: K): boolean;
+    cleanup(): number;
+    getStats(): CacheStats;
+}
+/**
+ * Sharded cache for high concurrency scenarios.
+ * Distributes keys across multiple shards to reduce lock contention.
+ */
+declare class ShardedCache<K, V> {
+    private shards;
+    private shardMask;
+    constructor(shards?: number, maxSizePerShard?: number, ttl?: number);
+    private getShard;
+    private hashKey;
+    get(key: K): V | undefined;
+    set(key: K, value: V): void;
+    delete(key: K): boolean;
+    clear(): void;
+    getStats(): CacheStats;
+}
+/**
+ * Decorator for caching function results.
+ */
+declare function cached<K extends any[], R>(cache: LRUCache<string, R> | TTLCache<string, R>, keyFn?: (...args: K) => string): (target: any, propertyKey: string, descriptor: TypedPropertyDescriptor<(...args: K) => R>) => TypedPropertyDescriptor<(...args: K) => R>;
+declare const blockhashCache: TTLCache<string, string>;
+declare const accountCache: ShardedCache<string, Buffer<ArrayBufferLike>>;
+declare const priceCache: TTLCache<string, number>;
+
+export { LRUCache, ShardedCache, TTLCache, accountCache, blockhashCache, cached, priceCache };

package/dist/cache/index.d.ts

@@ -0,0 +1,70 @@
+/**
+ * High-Performance Cache Implementation for Sol Trade SDK
+ * Provides LRU, TTL, and sharded caches for optimal performance.
+ */
+interface CacheStats {
+    hits: number;
+    misses: number;
+    evictions: number;
+    size: number;
+    hitRate: number;
+}
+/**
+ * Thread-safe LRU cache with TTL support.
+ * O(1) get and set operations.
+ */
+declare class LRUCache<K, V> {
+    private cache;
+    private maxSize;
+    private ttl;
+    private hits;
+    private misses;
+    private evictions;
+    constructor(maxSize?: number, ttl?: number);
+    get(key: K): V | undefined;
+    set(key: K, value: V): void;
+    delete(key: K): boolean;
+    clear(): void;
+    cleanup(): number;
+    getStats(): CacheStats;
+}
+/**
+ * Simple TTL cache with fast reads.
+ */
+declare class TTLCache<K, V> {
+    private cache;
+    private ttl;
+    private hits;
+    private misses;
+    constructor(ttl?: number);
+    get(key: K): V | undefined;
+    set(key: K, value: V): void;
+    delete(key: K): boolean;
+    cleanup(): number;
+    getStats(): CacheStats;
+}
+/**
+ * Sharded cache for high concurrency scenarios.
+ * Distributes keys across multiple shards to reduce lock contention.
+ */
+declare class ShardedCache<K, V> {
+    private shards;
+    private shardMask;
+    constructor(shards?: number, maxSizePerShard?: number, ttl?: number);
+    private getShard;
+    private hashKey;
+    get(key: K): V | undefined;
+    set(key: K, value: V): void;
+    delete(key: K): boolean;
+    clear(): void;
+    getStats(): CacheStats;
+}
+/**
+ * Decorator for caching function results.
+ */
+declare function cached<K extends any[], R>(cache: LRUCache<string, R> | TTLCache<string, R>, keyFn?: (...args: K) => string): (target: any, propertyKey: string, descriptor: TypedPropertyDescriptor<(...args: K) => R>) => TypedPropertyDescriptor<(...args: K) => R>;
+declare const blockhashCache: TTLCache<string, string>;
+declare const accountCache: ShardedCache<string, Buffer<ArrayBufferLike>>;
+declare const priceCache: TTLCache<string, number>;
+
+export { LRUCache, ShardedCache, TTLCache, accountCache, blockhashCache, cached, priceCache };

package/dist/cache/index.js

@@ -0,0 +1,259 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/cache/index.ts
+var cache_exports = {};
+__export(cache_exports, {
+  LRUCache: () => LRUCache,
+  ShardedCache: () => ShardedCache,
+  TTLCache: () => TTLCache,
+  accountCache: () => accountCache,
+  blockhashCache: () => blockhashCache,
+  cached: () => cached,
+  priceCache: () => priceCache
+});
+module.exports = __toCommonJS(cache_exports);
+
+// src/cache/cache.ts
+var LRUCache = class {
+  cache = /* @__PURE__ */ new Map();
+  maxSize;
+  ttl;
+  hits = 0;
+  misses = 0;
+  evictions = 0;
+  constructor(maxSize = 1e3, ttl = 3e5) {
+    this.maxSize = maxSize;
+    this.ttl = ttl;
+  }
+  get(key) {
+    const entry = this.cache.get(key);
+    if (!entry) {
+      this.misses++;
+      return void 0;
+    }
+    if (Date.now() > entry.expiration) {
+      this.cache.delete(key);
+      this.misses++;
+      return void 0;
+    }
+    this.cache.delete(key);
+    this.cache.set(key, entry);
+    entry.accessCount++;
+    this.hits++;
+    return entry.value;
+  }
+  set(key, value) {
+    const expiration = Date.now() + this.ttl;
+    if (this.cache.has(key)) {
+      const entry = this.cache.get(key);
+      entry.value = value;
+      entry.expiration = expiration;
+      this.cache.delete(key);
+      this.cache.set(key, entry);
+    } else {
+      this.cache.set(key, {
+        value,
+        expiration,
+        accessCount: 0
+      });
+      while (this.cache.size > this.maxSize) {
+        const firstKey = this.cache.keys().next().value;
+        if (firstKey === void 0) {
+          break;
+        }
+        this.cache.delete(firstKey);
+        this.evictions++;
+      }
+    }
+  }
+  delete(key) {
+    return this.cache.delete(key);
+  }
+  clear() {
+    this.cache.clear();
+    this.hits = 0;
+    this.misses = 0;
+    this.evictions = 0;
+  }
+  cleanup() {
+    let removed = 0;
+    const now = Date.now();
+    for (const [key, entry] of this.cache.entries()) {
+      if (now > entry.expiration) {
+        this.cache.delete(key);
+        this.evictions++;
+        removed++;
+      }
+    }
+    return removed;
+  }
+  getStats() {
+    const total = this.hits + this.misses;
+    return {
+      hits: this.hits,
+      misses: this.misses,
+      evictions: this.evictions,
+      size: this.cache.size,
+      hitRate: total > 0 ? this.hits / total : 0
+    };
+  }
+};
+var TTLCache = class {
+  cache = /* @__PURE__ */ new Map();
+  ttl;
+  hits = 0;
+  misses = 0;
+  constructor(ttl = 3e5) {
+    this.ttl = ttl;
+  }
+  get(key) {
+    const entry = this.cache.get(key);
+    if (!entry) {
+      this.misses++;
+      return void 0;
+    }
+    if (Date.now() > entry.expiration) {
+      this.cache.delete(key);
+      this.misses++;
+      return void 0;
+    }
+    this.hits++;
+    return entry.value;
+  }
+  set(key, value) {
+    this.cache.set(key, {
+      value,
+      expiration: Date.now() + this.ttl,
+      accessCount: 0
+    });
+  }
+  delete(key) {
+    return this.cache.delete(key);
+  }
+  cleanup() {
+    let removed = 0;
+    const now = Date.now();
+    for (const [key, entry] of this.cache.entries()) {
+      if (now > entry.expiration) {
+        this.cache.delete(key);
+        removed++;
+      }
+    }
+    return removed;
+  }
+  getStats() {
+    const total = this.hits + this.misses;
+    return {
+      hits: this.hits,
+      misses: this.misses,
+      evictions: 0,
+      size: this.cache.size,
+      hitRate: total > 0 ? this.hits / total : 0
+    };
+  }
+};
+var ShardedCache = class {
+  shards;
+  shardMask;
+  constructor(shards = 16, maxSizePerShard = 1e3, ttl = 3e5) {
+    this.shards = [];
+    for (let i = 0; i < shards; i++) {
+      this.shards.push(new LRUCache(maxSizePerShard, ttl));
+    }
+    this.shardMask = shards - 1;
+  }
+  getShard(key) {
+    const hash = this.hashKey(key);
+    return this.shards[hash & this.shardMask];
+  }
+  hashKey(key) {
+    const str = String(key);
+    let hash = 0;
+    for (let i = 0; i < str.length; i++) {
+      hash = (hash << 5) - hash + str.charCodeAt(i);
+      hash = hash & hash;
+    }
+    return Math.abs(hash);
+  }
+  get(key) {
+    return this.getShard(key).get(key);
+  }
+  set(key, value) {
+    this.getShard(key).set(key, value);
+  }
+  delete(key) {
+    return this.getShard(key).delete(key);
+  }
+  clear() {
+    for (const shard of this.shards) {
+      shard.clear();
+    }
+  }
+  getStats() {
+    let totalHits = 0;
+    let totalMisses = 0;
+    let totalEvictions = 0;
+    let totalSize = 0;
+    for (const shard of this.shards) {
+      const stats = shard.getStats();
+      totalHits += stats.hits;
+      totalMisses += stats.misses;
+      totalEvictions += stats.evictions;
+      totalSize += stats.size;
+    }
+    const total = totalHits + totalMisses;
+    return {
+      hits: totalHits,
+      misses: totalMisses,
+      evictions: totalEvictions,
+      size: totalSize,
+      hitRate: total > 0 ? totalHits / total : 0
+    };
+  }
+};
+function cached(cache, keyFn) {
+  return function(target, propertyKey, descriptor) {
+    const originalMethod = descriptor.value;
+    descriptor.value = function(...args) {
+      const key = keyFn ? keyFn(...args) : `${propertyKey}:${JSON.stringify(args)}`;
+      const cached2 = cache.get(key);
+      if (cached2 !== void 0) {
+        return cached2;
+      }
+      const result = originalMethod.apply(this, args);
+      cache.set(key, result);
+      return result;
+    };
+    return descriptor;
+  };
+}
+var blockhashCache = new TTLCache(2e3);
+var accountCache = new ShardedCache(16, 500, 1e4);
+var priceCache = new TTLCache(1e3);
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  LRUCache,
+  ShardedCache,
+  TTLCache,
+  accountCache,
+  blockhashCache,
+  cached,
+  priceCache
+});

package/dist/cache/index.mjs

@@ -0,0 +1,19 @@
+import {
+  LRUCache,
+  ShardedCache,
+  TTLCache,
+  accountCache,
+  blockhashCache,
+  cached,
+  priceCache
+} from "../chunk-64JY4YH6.mjs";
+import "../chunk-6BWS3CLP.mjs";
+export {
+  LRUCache,
+  ShardedCache,
+  TTLCache,
+  accountCache,
+  blockhashCache,
+  cached,
+  priceCache
+};

package/dist/chunk-64JY4YH6.mjs

@@ -0,0 +1,227 @@
+// src/cache/cache.ts
+var LRUCache = class {
+  cache = /* @__PURE__ */ new Map();
+  maxSize;
+  ttl;
+  hits = 0;
+  misses = 0;
+  evictions = 0;
+  constructor(maxSize = 1e3, ttl = 3e5) {
+    this.maxSize = maxSize;
+    this.ttl = ttl;
+  }
+  get(key) {
+    const entry = this.cache.get(key);
+    if (!entry) {
+      this.misses++;
+      return void 0;
+    }
+    if (Date.now() > entry.expiration) {
+      this.cache.delete(key);
+      this.misses++;
+      return void 0;
+    }
+    this.cache.delete(key);
+    this.cache.set(key, entry);
+    entry.accessCount++;
+    this.hits++;
+    return entry.value;
+  }
+  set(key, value) {
+    const expiration = Date.now() + this.ttl;
+    if (this.cache.has(key)) {
+      const entry = this.cache.get(key);
+      entry.value = value;
+      entry.expiration = expiration;
+      this.cache.delete(key);
+      this.cache.set(key, entry);
+    } else {
+      this.cache.set(key, {
+        value,
+        expiration,
+        accessCount: 0
+      });
+      while (this.cache.size > this.maxSize) {
+        const firstKey = this.cache.keys().next().value;
+        if (firstKey === void 0) {
+          break;
+        }
+        this.cache.delete(firstKey);
+        this.evictions++;
+      }
+    }
+  }
+  delete(key) {
+    return this.cache.delete(key);
+  }
+  clear() {
+    this.cache.clear();
+    this.hits = 0;
+    this.misses = 0;
+    this.evictions = 0;
+  }
+  cleanup() {
+    let removed = 0;
+    const now = Date.now();
+    for (const [key, entry] of this.cache.entries()) {
+      if (now > entry.expiration) {
+        this.cache.delete(key);
+        this.evictions++;
+        removed++;
+      }
+    }
+    return removed;
+  }
+  getStats() {
+    const total = this.hits + this.misses;
+    return {
+      hits: this.hits,
+      misses: this.misses,
+      evictions: this.evictions,
+      size: this.cache.size,
+      hitRate: total > 0 ? this.hits / total : 0
+    };
+  }
+};
+var TTLCache = class {
+  cache = /* @__PURE__ */ new Map();
+  ttl;
+  hits = 0;
+  misses = 0;
+  constructor(ttl = 3e5) {
+    this.ttl = ttl;
+  }
+  get(key) {
+    const entry = this.cache.get(key);
+    if (!entry) {
+      this.misses++;
+      return void 0;
+    }
+    if (Date.now() > entry.expiration) {
+      this.cache.delete(key);
+      this.misses++;
+      return void 0;
+    }
+    this.hits++;
+    return entry.value;
+  }
+  set(key, value) {
+    this.cache.set(key, {
+      value,
+      expiration: Date.now() + this.ttl,
+      accessCount: 0
+    });
+  }
+  delete(key) {
+    return this.cache.delete(key);
+  }
+  cleanup() {
+    let removed = 0;
+    const now = Date.now();
+    for (const [key, entry] of this.cache.entries()) {
+      if (now > entry.expiration) {
+        this.cache.delete(key);
+        removed++;
+      }
+    }
+    return removed;
+  }
+  getStats() {
+    const total = this.hits + this.misses;
+    return {
+      hits: this.hits,
+      misses: this.misses,
+      evictions: 0,
+      size: this.cache.size,
+      hitRate: total > 0 ? this.hits / total : 0
+    };
+  }
+};
+var ShardedCache = class {
+  shards;
+  shardMask;
+  constructor(shards = 16, maxSizePerShard = 1e3, ttl = 3e5) {
+    this.shards = [];
+    for (let i = 0; i < shards; i++) {
+      this.shards.push(new LRUCache(maxSizePerShard, ttl));
+    }
+    this.shardMask = shards - 1;
+  }
+  getShard(key) {
+    const hash = this.hashKey(key);
+    return this.shards[hash & this.shardMask];
+  }
+  hashKey(key) {
+    const str = String(key);
+    let hash = 0;
+    for (let i = 0; i < str.length; i++) {
+      hash = (hash << 5) - hash + str.charCodeAt(i);
+      hash = hash & hash;
+    }
+    return Math.abs(hash);
+  }
+  get(key) {
+    return this.getShard(key).get(key);
+  }
+  set(key, value) {
+    this.getShard(key).set(key, value);
+  }
+  delete(key) {
+    return this.getShard(key).delete(key);
+  }
+  clear() {
+    for (const shard of this.shards) {
+      shard.clear();
+    }
+  }
+  getStats() {
+    let totalHits = 0;
+    let totalMisses = 0;
+    let totalEvictions = 0;
+    let totalSize = 0;
+    for (const shard of this.shards) {
+      const stats = shard.getStats();
+      totalHits += stats.hits;
+      totalMisses += stats.misses;
+      totalEvictions += stats.evictions;
+      totalSize += stats.size;
+    }
+    const total = totalHits + totalMisses;
+    return {
+      hits: totalHits,
+      misses: totalMisses,
+      evictions: totalEvictions,
+      size: totalSize,
+      hitRate: total > 0 ? totalHits / total : 0
+    };
+  }
+};
+function cached(cache, keyFn) {
+  return function(target, propertyKey, descriptor) {
+    const originalMethod = descriptor.value;
+    descriptor.value = function(...args) {
+      const key = keyFn ? keyFn(...args) : `${propertyKey}:${JSON.stringify(args)}`;
+      const cached2 = cache.get(key);
+      if (cached2 !== void 0) {
+        return cached2;
+      }
+      const result = originalMethod.apply(this, args);
+      cache.set(key, result);
+      return result;
+    };
+    return descriptor;
+  };
+}
+var blockhashCache = new TTLCache(2e3);
+var accountCache = new ShardedCache(16, 500, 1e4);
+var priceCache = new TTLCache(1e3);
+
+export {
+  LRUCache,
+  TTLCache,
+  ShardedCache,
+  cached,
+  blockhashCache,
+  accountCache,
+  priceCache
+};

package/dist/chunk-6BWS3CLP.mjs

@@ -0,0 +1,16 @@
+var __defProp = Object.defineProperty;
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+export {
+  __require,
+  __export
+};