sol-parser-sdk 0.5.9 → 0.5.11

package/README.md

@@ -16,12 +16,6 @@
     <a href="https://discord.gg/vuazbGkqQE">Discord</a>
 </p>
 
-> ☕ **Support This Project**
->
-> This SDK is completely free and open source. However, maintaining and continuously updating it requires significant AI computing resources and token consumption. If this SDK helps with your development, consider making a monthly SOL donation — any amount is appreciated and helps keep this project alive!
->
-> **Donation Wallet:** `6oW7AXz1yRb57pYSxysuXnMs2aR1ha5rzGzReZ1MjPV8`
-
 ---
 
 ## Other language SDKs
@@ -81,7 +75,7 @@
 **From npm**
 
 ```bash
-npm install sol-parser-sdk@0.5.9
+npm install sol-parser-sdk@0.5.11
 ```
 
 **From source** (folder may be named `sol-parser-sdk-ts` in a monorepo)
@@ -153,6 +147,37 @@ const sub = await client.subscribeTransactions(filter, {
 console.log("subscribed", sub.id);
 ```
 
+### Long-running low-latency DEX subscriptions
+
+The public API remains queue-based, matching the Rust SDK's `subscribe_dex_events` shape. The Node
+subscription is an async iterable instead of Rust's `ArrayQueue`, while ring-buffer dequeue,
+Yellowstone update parsing, HTTP/2 receive-window tuning, and reconnect behavior are handled inside
+the SDK:
+
+```typescript
+import { YellowstoneGrpc, lowLatencyClientConfig } from "sol-parser-sdk";
+
+const client = new YellowstoneGrpc(ENDPOINT, X_TOKEN, lowLatencyClientConfig());
+const sub = await client.subscribeDexEvents(txFilters, accountFilters, eventTypeFilter);
+
+void (async () => {
+  for await (const error of sub.errors) console.error("subscription error", error);
+})();
+
+for await (const event of sub) {
+  handleEvent(event);
+}
+```
+
+If using `for await`, the default overflow behavior remains `drop-newest` for compatibility. A
+tip-oriented consumer can choose `queueOverflowStrategy: "drop-oldest"` and monitor `sub.len()` and
+`sub.dropped()`. Every overflow is counted and periodically reported through `sub.errors`.
+
+No bounded in-memory stream can guarantee both zero loss and bounded latency when the consumer's
+average processing rate is below the filtered input rate. Keep the loop body CPU-light, avoid
+per-event synchronous logging, filter at the server, and persist or dispatch slow work outside the
+consumer loop.
+
 **Lighter path:** `parseLogsOnly(logs, signature, slot, …)` — no `transactionRaw`; use `applyAccountFillsToLogEvents` if you need filled accounts without full gRPC meta.
 
 ### 5. ShredStream (HTTP — not Yellowstone gRPC)
@@ -179,6 +204,7 @@ From the **package root** after `npm install`. Examples use `npx tsx` and load `
 | gRPC integration test (PumpFun + PumpSwap, account-filled `DexEvent`) | `npx tsx scripts/test-grpc-ts.ts` | [test-grpc-ts.ts](https://github.com/0xfnzero/sol-parser-sdk-nodejs/blob/main/scripts/test-grpc-ts.ts) |
 | Debug: print `metaRaw` / log structure | `npx tsx scripts/debug-grpc-ts.ts` | [debug-grpc-ts.ts](https://github.com/0xfnzero/sol-parser-sdk-nodejs/blob/main/scripts/debug-grpc-ts.ts) |
 | **PumpFun** | | |
+| CREATE + dev BUY/SELL, long-running low latency | `npx tsx examples/devtrades_low_latency.ts` | [devtrades_low_latency.ts](https://github.com/0xfnzero/sol-parser-sdk-nodejs/blob/main/examples/devtrades_low_latency.ts) |
 | Pretty-print full JSON `DexEvent` over gRPC | `npx tsx examples/pumpfun_grpc_json.ts` | [pumpfun_grpc_json.ts](https://github.com/0xfnzero/sol-parser-sdk-nodejs/blob/main/examples/pumpfun_grpc_json.ts) |
 | PumpFun events + metrics | `npx tsx examples/pumpfun_with_metrics.ts` | [pumpfun_with_metrics.ts](https://github.com/0xfnzero/sol-parser-sdk-nodejs/blob/main/examples/pumpfun_with_metrics.ts) |
 | PumpFun trade filter | `npx tsx examples/pumpfun_trade_filter.ts` | [pumpfun_trade_filter.ts](https://github.com/0xfnzero/sol-parser-sdk-nodejs/blob/main/examples/pumpfun_trade_filter.ts) |
@@ -204,7 +230,7 @@ From the **package root** after `npm install`. Examples use `npx tsx` and load `
 - `npm run example:shredstream:subscribe` → [shredstream_example.ts](https://github.com/0xfnzero/sol-parser-sdk-nodejs/blob/main/examples/shredstream_example.ts)
 - `npm run example:shredstream:pumpfun-json` → [shredstream_pumpfun_json.ts](https://github.com/0xfnzero/sol-parser-sdk-nodejs/blob/main/examples/shredstream_pumpfun_json.ts)
 
-**Env:** gRPC examples need **`GRPC_URL`** + **`GRPC_TOKEN`**. ShredStream uses **`SHREDSTREAM_URL`** / **`SHRED_URL`** or **`--url`**; `shredstream_pumpfun_json` also needs **`RPC_URL`** / **`--rpc`**. See **`.env.example`**.
+**Env:** gRPC examples need **`GRPC_URL`** + **`GRPC_TOKEN`**. Exported shell values take precedence; `.env` supplies values that are not already present. ShredStream uses **`SHREDSTREAM_URL`** / **`SHRED_URL`** or **`--url`**; `shredstream_pumpfun_json` also needs **`RPC_URL`** / **`--rpc`**. See **`.env.example`**.
 
 ---
 

package/README_CN.md

@@ -16,12 +16,6 @@
     <a href="https://discord.gg/vuazbGkqQE">Discord</a>
 </p>
 
-> ☕ **支持本项目**
->
-> 本 SDK 完全免费且开源。但维护和持续更新需要消耗大量 AI 算力与 Token。如果这个 SDK 对您的开发有帮助，欢迎每月捐赠任意数量的 SOL，您的支持将帮助这个项目持续运行！
->
-> **捐赠钱包：** `6oW7AXz1yRb57pYSxysuXnMs2aR1ha5rzGzReZ1MjPV8`
-
 ---
 
 ## 其他语言 SDK
@@ -81,7 +75,7 @@
 **npm**
 
 ```bash
-npm install sol-parser-sdk@0.5.9
+npm install sol-parser-sdk@0.5.11
 ```
 
 **源码**（monorepo 里目录可能是 `sol-parser-sdk-ts`）
@@ -153,6 +147,35 @@ const sub = await client.subscribeTransactions(filter, {
 console.log("subscribed", sub.id);
 ```
 
+### 长时间运行的低延迟 DEX 订阅
+
+公开 API 保持队列式调用，与 Rust SDK 的 `subscribe_dex_events` 形态一致。Node 使用异步
+迭代器代替 Rust 的 `ArrayQueue`；环形队列出队、Yellowstone update 解析、HTTP/2 接收窗口
+和重连优化全部由 SDK 内部完成：
+
+```typescript
+import { YellowstoneGrpc, lowLatencyClientConfig } from "sol-parser-sdk";
+
+const client = new YellowstoneGrpc(ENDPOINT, X_TOKEN, lowLatencyClientConfig());
+const sub = await client.subscribeDexEvents(txFilters, accountFilters, eventTypeFilter);
+
+void (async () => {
+  for await (const error of sub.errors) console.error("subscription error", error);
+})();
+
+for await (const event of sub) {
+  handleEvent(event);
+}
+```
+
+若使用 `for await`，默认溢出策略仍是 `drop-newest`，以保持兼容。更重视贴近链尖的消费者
+可以设置 `queueOverflowStrategy: "drop-oldest"`，并监控 `sub.len()` 和 `sub.dropped()`。
+每次溢出都会计数，并定期通过 `sub.errors` 报告。
+
+当消费者平均处理速度低于过滤后的入流速度时，任何有界内存流都无法同时保证零丢失和
+有界延迟。消费循环应保持轻量，避免逐事件同步日志，在服务端尽量缩小过滤范围，并把
+慢 I/O 的持久化或分发移出消费循环。
+
 更轻量：仅用日志用 `parseLogsOnly`；要补账户可再配合 `applyAccountFillsToLogEvents`。
 
 ### 5. ShredStream（HTTP，不是 Yellowstone gRPC）
@@ -179,6 +202,7 @@ npx tsx examples/shredstream_example.ts -- --url=http://127.0.0.1:10800
 | gRPC 集成测试（PumpFun + PumpSwap，账户填充后的 `DexEvent`） | `npx tsx scripts/test-grpc-ts.ts` | [test-grpc-ts.ts](https://github.com/0xfnzero/sol-parser-sdk-nodejs/blob/main/scripts/test-grpc-ts.ts) |
 | 调试：打印 `metaRaw` / 日志结构 | `npx tsx scripts/debug-grpc-ts.ts` | [debug-grpc-ts.ts](https://github.com/0xfnzero/sol-parser-sdk-nodejs/blob/main/scripts/debug-grpc-ts.ts) |
 | **PumpFun** | | |
+| CREATE + dev BUY/SELL 长时间低延迟订阅 | `npx tsx examples/devtrades_low_latency.ts` | [devtrades_low_latency.ts](https://github.com/0xfnzero/sol-parser-sdk-nodejs/blob/main/examples/devtrades_low_latency.ts) |
 | gRPC 输出完整 JSON `DexEvent` | `npx tsx examples/pumpfun_grpc_json.ts` | [pumpfun_grpc_json.ts](https://github.com/0xfnzero/sol-parser-sdk-nodejs/blob/main/examples/pumpfun_grpc_json.ts) |
 | PumpFun 事件 + 性能指标 | `npx tsx examples/pumpfun_with_metrics.ts` | [pumpfun_with_metrics.ts](https://github.com/0xfnzero/sol-parser-sdk-nodejs/blob/main/examples/pumpfun_with_metrics.ts) |
 | PumpFun 交易类型过滤 | `npx tsx examples/pumpfun_trade_filter.ts` | [pumpfun_trade_filter.ts](https://github.com/0xfnzero/sol-parser-sdk-nodejs/blob/main/examples/pumpfun_trade_filter.ts) |
@@ -204,7 +228,7 @@ npx tsx examples/shredstream_example.ts -- --url=http://127.0.0.1:10800
 - `npm run example:shredstream:subscribe` → [shredstream_example.ts](https://github.com/0xfnzero/sol-parser-sdk-nodejs/blob/main/examples/shredstream_example.ts)
 - `npm run example:shredstream:pumpfun-json` → [shredstream_pumpfun_json.ts](https://github.com/0xfnzero/sol-parser-sdk-nodejs/blob/main/examples/shredstream_pumpfun_json.ts)
 
-**环境变量：** gRPC 示例需要 **`GRPC_URL`**、**`GRPC_TOKEN`**。ShredStream 使用 **`SHREDSTREAM_URL`** / **`SHRED_URL`** 或 **`--url`**；**`shredstream_pumpfun_json`** 另需 **`RPC_URL`** / **`--rpc`**。详见 **`.env.example`**。
+**环境变量：** gRPC 示例需要 **`GRPC_URL`**、**`GRPC_TOKEN`**。已 export 的 shell 环境变量优先，`.env` 只补充尚未设置的值。ShredStream 使用 **`SHREDSTREAM_URL`** / **`SHRED_URL`** 或 **`--url`**；**`shredstream_pumpfun_json`** 另需 **`RPC_URL`** / **`--rpc`**。详见 **`.env.example`**。
 
 ---
 

package/dist/accounts/pumpswap.js

@@ -11,7 +11,8 @@ const program_ids_js_1 = require("../instr/program_ids.js");
 const GLOBAL_DISC = Uint8Array.from([149, 8, 156, 202, 160, 252, 176, 217]);
 const POOL_DISC = Uint8Array.from([241, 154, 109, 4, 17, 177, 109, 188]);
 const GLOBAL_BODY = 634;
-const POOL_BODY = 244;
+const POOL_LEGACY_BODY = 244;
+const POOL_BODY = 253;
 function isGlobalConfigAccount(data) {
     return (0, utils_js_1.hasDiscriminator)(data, GLOBAL_DISC);
 }
@@ -103,8 +104,11 @@ function parsePumpswapGlobalConfig(account, metadata) {
     return { PumpSwapGlobalConfigAccount: ev };
 }
 function parsePumpswapPool(account, metadata) {
-    if (account.data.length < 8 + POOL_BODY)
+    if (account.data.length < 8 + POOL_LEGACY_BODY)
         return null;
+    if (account.data.length !== 8 + POOL_LEGACY_BODY && account.data.length < 8 + POOL_BODY) {
+        return null;
+    }
     if (!isPoolAccount(account.data))
         return null;
     const d = account.data.subarray(8);
@@ -156,6 +160,14 @@ function parsePumpswapPool(account, metadata) {
     const cashback = (0, binary_js_1.readU8)(d, o);
     if (cashback === null)
         return null;
+    o += 1;
+    let virtual_quote_reserves = 0n;
+    if (d.length >= POOL_BODY) {
+        const virtual = (0, binary_js_1.readU128LE)(d, o);
+        if (virtual === null)
+            return null;
+        virtual_quote_reserves = BigInt.asIntN(128, virtual);
+    }
     const pool = {
         pool_bump,
         index,
@@ -169,6 +181,7 @@ function parsePumpswapPool(account, metadata) {
         coin_creator,
         is_mayhem_mode: mayhem !== 0,
         is_cashback_coin: cashback !== 0,
+        virtual_quote_reserves,
     };
     const ev = {
         metadata,

package/dist/core/account_fill_raydium.d.ts

@@ -11,7 +11,7 @@ export declare function fillRaydiumClmmOpenPositionWithTokenExtNftAccounts(e: Ra
 export declare function fillRaydiumClmmClosePositionAccounts(e: RaydiumClmmClosePositionEvent, get: (i: number) => string): void;
 export declare function fillRaydiumClmmIncreaseLiquidityAccounts(e: RaydiumClmmIncreaseLiquidityEvent, get: (i: number) => string): void;
 export declare function fillRaydiumClmmDecreaseLiquidityAccounts(e: RaydiumClmmDecreaseLiquidityEvent, get: (i: number) => string): void;
-export declare function fillRaydiumCpmmSwapAccounts(_e: RaydiumCpmmSwapEvent, _get: (i: number) => string): void;
+export declare function fillRaydiumCpmmSwapAccounts(e: RaydiumCpmmSwapEvent, get: (i: number) => string): void;
 export declare function fillRaydiumCpmmDepositAccounts(e: RaydiumCpmmDepositEvent, get: (i: number) => string): void;
 export declare function fillRaydiumCpmmWithdrawAccounts(e: RaydiumCpmmWithdrawEvent, get: (i: number) => string): void;
 export declare function fillRaydiumCpmmInitializeAccounts(e: RaydiumCpmmInitializeEvent, get: (i: number) => string): void;

package/dist/core/account_fill_raydium.js

@@ -63,7 +63,11 @@ function fillRaydiumClmmDecreaseLiquidityAccounts(e, get) {
     if (!e.user || e.user === zero)
         e.user = get(0);
 }
-function fillRaydiumCpmmSwapAccounts(_e, _get) { }
+function fillRaydiumCpmmSwapAccounts(e, get) {
+    const zero = Z();
+    if (!e.pool_id || e.pool_id === zero)
+        e.pool_id = get(3);
+}
 function fillRaydiumCpmmDepositAccounts(e, get) {
     const zero = Z();
     if (!e.user || e.user === zero)

package/dist/core/dex_event.d.ts

@@ -480,6 +480,11 @@ export interface PumpSwapBuyEvent {
     /** 与 `PumpSwapBuyEvent`：PUMP_CASHBACK / IDL */
     cashback_fee_basis_points: bigint;
     cashback: bigint;
+    buyback_fee_basis_points: bigint;
+    buyback_fee: bigint;
+    virtual_quote_reserves: bigint;
+    can_boost: boolean;
+    base_supply: bigint;
     /** 由 fees 指令数据填充（见 `fillDataRpc`） */
     is_pump_pool: boolean;
     /** 自指令账户填充（account_fillers/pumpswap） */
@@ -522,6 +527,11 @@ export interface PumpSwapSellEvent {
     coin_creator_fee: bigint;
     cashback_fee_basis_points: bigint;
     cashback: bigint;
+    buyback_fee_basis_points: bigint;
+    buyback_fee: bigint;
+    virtual_quote_reserves: bigint;
+    can_boost: boolean;
+    base_supply: bigint;
     is_pump_pool: boolean;
     base_mint: string;
     quote_mint: string;
@@ -1432,6 +1442,7 @@ export interface PumpSwapPool {
     coin_creator: string;
     is_mayhem_mode: boolean;
     is_cashback_coin: boolean;
+    virtual_quote_reserves: bigint;
 }
 export interface PumpSwapPoolAccountEvent {
     metadata: EventMetadata;

package/dist/grpc/async_event_queue.d.ts

@@ -0,0 +1,19 @@
+export type EventQueueOverflowStrategy = "drop-newest" | "drop-oldest";
+/** Internal O(1) queue used by the public async-iterable subscription. */
+export declare class AsyncEventQueue<T> implements AsyncIterable<T>, AsyncIterator<T> {
+    private readonly maxSize;
+    private readonly overflowStrategy;
+    private readonly items;
+    private readonly waiters;
+    private closed;
+    private droppedCount;
+    private head;
+    private size;
+    constructor(maxSize: number, overflowStrategy?: EventQueueOverflowStrategy);
+    push(item: T): boolean;
+    len(): number;
+    dropped(): number;
+    close(): void;
+    next(): Promise<IteratorResult<T>>;
+    [Symbol.asyncIterator](): AsyncIterator<T>;
+}

package/dist/grpc/async_event_queue.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AsyncEventQueue = void 0;
+/** Internal O(1) queue used by the public async-iterable subscription. */
+class AsyncEventQueue {
+    maxSize;
+    overflowStrategy;
+    items;
+    waiters = [];
+    closed = false;
+    droppedCount = 0;
+    head = 0;
+    size = 0;
+    constructor(maxSize, overflowStrategy = "drop-newest") {
+        this.maxSize = maxSize;
+        this.overflowStrategy = overflowStrategy;
+        if (!Number.isInteger(maxSize) || maxSize < 1) {
+            throw new RangeError("AsyncEventQueue maxSize must be a positive integer");
+        }
+        this.items = new Array(maxSize);
+    }
+    push(item) {
+        if (this.closed)
+            return false;
+        const waiter = this.waiters.shift();
+        if (waiter) {
+            waiter({ value: item, done: false });
+            return true;
+        }
+        if (this.size < this.maxSize) {
+            this.items[(this.head + this.size) % this.maxSize] = item;
+            this.size++;
+            return true;
+        }
+        this.droppedCount++;
+        if (this.overflowStrategy === "drop-oldest") {
+            this.items[this.head] = item;
+            this.head = (this.head + 1) % this.maxSize;
+        }
+        return false;
+    }
+    len() {
+        return this.size;
+    }
+    dropped() {
+        return this.droppedCount;
+    }
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        for (const waiter of this.waiters.splice(0)) {
+            waiter({ value: undefined, done: true });
+        }
+    }
+    next() {
+        if (this.size > 0) {
+            const item = this.items[this.head];
+            this.items[this.head] = undefined;
+            this.head = (this.head + 1) % this.maxSize;
+            this.size--;
+            return Promise.resolve({ value: item, done: false });
+        }
+        if (this.closed) {
+            return Promise.resolve({ value: undefined, done: true });
+        }
+        return new Promise((resolve) => this.waiters.push(resolve));
+    }
+    [Symbol.asyncIterator]() {
+        return this;
+    }
+}
+exports.AsyncEventQueue = AsyncEventQueue;

package/dist/grpc/client.d.ts

@@ -3,13 +3,25 @@
  */
 import { CommitmentLevel } from "@triton-one/yellowstone-grpc";
 import type { DexEvent } from "../core/dex_event.js";
+import { type EventQueueOverflowStrategy } from "./async_event_queue.js";
 import { type AccountFilter, type ClientConfig, type EventTypeFilter, type TransactionFilter, type SubscribeCallbacks } from "./types.js";
 export { SubscribeCallbacks };
+export type { EventQueueOverflowStrategy } from "./async_event_queue.js";
 export interface DexEventSubscription extends AsyncIterable<DexEvent> {
     id: string;
     errors: AsyncIterable<Error>;
     cancel(): void;
     next(): Promise<IteratorResult<DexEvent>>;
+    len(): number;
+    dropped(): number;
+}
+export interface SubscribeDexEventsOptions {
+    autoReconnect?: boolean;
+    /**
+     * Queue behavior when an async-iterator consumer cannot keep up. The default
+     * preserves the existing behavior; `drop-oldest` favors staying near chain tip.
+     */
+    queueOverflowStrategy?: EventQueueOverflowStrategy;
 }
 /** Yellowstone gRPC 客户端包装器 */
 export declare class YellowstoneGrpc {
@@ -41,6 +53,7 @@ export declare class YellowstoneGrpc {
     private static protobufNumber;
     private static timestampToMicros;
     private parseAccountEvent;
+    private parseAccountEventRaw;
     private initialSubscribeRequest;
     /** 订阅交易 */
     subscribeTransactions(filter: TransactionFilter, callbacks: SubscribeCallbacks): Promise<{
@@ -51,11 +64,9 @@ export declare class YellowstoneGrpc {
      * 订阅并直接产出 `DexEvent`。
      *
      * 交易更新走统一交易解析（外层/内层指令 + 日志 + 数据填充）；账户更新走 `parseAccountUnified`。
-     * 事件队列满时丢弃新事件，避免回调阻塞 gRPC 读循环，保持低延迟。
+     * 事件队列满时按配置丢弃事件，避免回调阻塞 gRPC 读循环并让丢弃可观测。
      */
-    subscribeDexEvents(transactionFilters?: TransactionFilter[], accountFilters?: AccountFilter[], eventTypeFilter?: EventTypeFilter, options?: {
-        autoReconnect?: boolean;
-    }): Promise<DexEventSubscription>;
+    subscribeDexEvents(transactionFilters?: TransactionFilter[], accountFilters?: AccountFilter[], eventTypeFilter?: EventTypeFilter, options?: SubscribeDexEventsOptions): Promise<DexEventSubscription>;
     /** 取消订阅 */
     unsubscribe(subId: string): void;
     /** 动态更新当前 DEX 订阅过滤器（与 Rust update_subscription 语义对齐）。 */