sol-parser-sdk 0.5.13 → 0.5.14

package/README.md

@@ -38,12 +38,20 @@
 | Parser inputs | Yellowstone gRPC, ShredStream, RPC transactions, encoded transactions, protocol account data |
 | DEX protocols | PumpFun, PumpSwap, Pump Fees, Raydium LaunchLab, Raydium CPMM, Raydium CLMM, Raydium AMM V4, Meteora DAMM v2, Meteora DLMM, Meteora DBC, Orca Whirlpool |
 | Use cases | Real-time DEX event parsing, token launch monitoring, copy trading, sniper bots, account filling, JSON event pipelines |
-| Runtime | Node.js 18+, TypeScript, npm/yarn/pnpm projects |
+| Runtime | Node.js 20.18+, TypeScript, npm/yarn/pnpm projects |
 
 ---
 
 ## Release notes
 
+### v0.5.14
+
+- Upgrades the Yellowstone client to `@triton-one/yellowstone-grpc` 7.0.0 with its native Rust N-API transport.
+- Adds `source_to_grpc_latency_us` to distinguish provider or transport backlog from exact local processing latency.
+- Fixes Yellowstone `createdAt` timestamps represented as JavaScript `Date` objects.
+- Updates native connection, keepalive, flow-control, stream lifecycle, and unary RPC compatibility.
+- Requires Node.js 20.18 or newer.
+
 ### v0.5.8
 
 - Syncs parser parity with the Rust SDK event model and program routing.
@@ -75,7 +83,7 @@
 **From npm**
 
 ```bash
-npm install sol-parser-sdk@0.5.13
+npm install sol-parser-sdk@0.5.14
 ```
 
 **From source** (folder may be named `sol-parser-sdk-ts` in a monorepo)

package/README_CN.md

@@ -38,12 +38,20 @@
 | 解析输入 | Yellowstone gRPC、ShredStream、RPC 交易、编码交易、协议账户数据 |
 | DEX 协议 | PumpFun、PumpSwap、Pump Fees、Raydium LaunchLab、Raydium CPMM、Raydium CLMM、Raydium AMM V4、Meteora DAMM v2、Meteora DLMM、Meteora DBC、Orca Whirlpool |
 | 使用场景 | 实时 DEX 事件解析、代币发射监控、跟单交易、狙击机器人、账户填充、JSON 事件管道 |
-| 运行环境 | Node.js 18+、TypeScript、npm/yarn/pnpm 项目 |
+| 运行环境 | Node.js 20.18+、TypeScript、npm/yarn/pnpm 项目 |
 
 ---
 
 ## 发布说明
 
+### v0.5.14
+
+- 将 Yellowstone 客户端升级到 `@triton-one/yellowstone-grpc` 7.0.0，使用其原生 Rust N-API 传输层。
+- 新增 `source_to_grpc_latency_us`，用于区分服务商或传输层积压与精确的本地处理延迟。
+- 修复 Yellowstone `createdAt` 使用 JavaScript `Date` 对象表示时的时间戳解析。
+- 更新原生连接、keepalive、流量控制、流生命周期和 unary RPC 兼容处理。
+- 要求 Node.js 20.18 或更高版本。
+
 ### v0.5.8
 
 - 与 Rust SDK 的事件模型和 program 路由保持解析对齐。
@@ -75,7 +83,7 @@
 **npm**
 
 ```bash
-npm install sol-parser-sdk@0.5.13
+npm install sol-parser-sdk@0.5.14
 ```
 
 **源码**（monorepo 里目录可能是 `sol-parser-sdk-ts`）

package/dist/core/metadata.d.ts

@@ -12,6 +12,8 @@ export interface EventMetadata {
     parse_duration_us?: number;
     /** Start of the local gRPC data callback through parser completion. No RPC calls are included. */
     local_processing_latency_us?: number;
+    /** Yellowstone update creation through the local gRPC data callback; includes provider and transport delay. */
+    source_to_grpc_latency_us?: number;
     recent_blockhash?: string;
 }
 export declare function makeMetadata(signature: string, slot: number, txIndex: number, blockTimeUs: number | undefined, grpcRecvUs: number, recentBlockhash?: string): EventMetadata;

package/dist/grpc/client.d.ts

@@ -46,6 +46,7 @@ export declare class YellowstoneGrpc {
     private client;
     private config;
     private connected;
+    private connectPromise?;
     private subscribers;
     private dexSubscribers;
     constructor(endpoint: string, xToken: string, config?: ClientConfig);

package/dist/grpc/client.js

@@ -55,10 +55,10 @@ const types_js_1 = require("./types.js");
 function cancelSubscribeStream(stream) {
     if (!stream)
         return;
-    // grpc-js emits CANCELLED through `error`; guard the short setup window before
+    // Stream destruction can emit an error during the short setup window before
     // the normal lifecycle listeners have been installed.
     stream.once("error", () => { });
-    stream.cancel();
+    stream.destroy();
 }
 function positiveIntegerOption(value, fallback, name) {
     const normalized = value ?? fallback;
@@ -101,6 +101,7 @@ class YellowstoneGrpc {
     client;
     config;
     connected = false;
+    connectPromise;
     subscribers = new Map();
     dexSubscribers = new Map();
     constructor(endpoint, xToken, config = (0, types_js_1.defaultClientConfig)()) {
@@ -117,10 +118,20 @@ class YellowstoneGrpc {
     }
     /** 连接到 gRPC 服务器 */
     async connect() {
-        if (this.connected) {
+        if (this.connected)
             return;
+        if (!this.connectPromise) {
+            this.connectPromise = this.client.connect().then(() => {
+                this.connected = true;
+            });
+        }
+        try {
+            await this.connectPromise;
+        }
+        catch (error) {
+            this.connectPromise = undefined;
+            throw error;
         }
-        this.connected = true;
     }
     /** 断开连接 */
     async disconnect() {
@@ -133,6 +144,7 @@ class YellowstoneGrpc {
         }
         this.dexSubscribers.clear();
         this.connected = false;
+        this.connectPromise = undefined;
     }
     /** 检查是否已连接 */
     isConnected() {
@@ -283,6 +295,10 @@ class YellowstoneGrpc {
         return Number.NaN;
     }
     static timestampToMicros(value) {
+        if (value instanceof Date) {
+            const milliseconds = value.getTime();
+            return Number.isFinite(milliseconds) ? Math.trunc(milliseconds * 1_000) : undefined;
+        }
         if (!value || typeof value !== "object")
             return undefined;
         const ts = value;
@@ -351,6 +367,7 @@ class YellowstoneGrpc {
     }
     /** 订阅交易 */
     async subscribeTransactions(filter, callbacks) {
+        await this.connect();
         const id = `sub_${Date.now()}_${Math.random().toString(36).slice(2)}`;
         let isCancelled = false;
         const streamHolder = { current: null };
@@ -516,7 +533,7 @@ class YellowstoneGrpc {
             for (const resolve of ingressIdleWaiters.splice(0))
                 resolve();
         };
-        const annotateLocalMetrics = (events, grpcRecvNs, parseStartedNs, parseFinishedNs) => {
+        const annotateLocalMetrics = (events, grpcRecvNs, parseStartedNs, parseFinishedNs, sourceToGrpcLatencyUs) => {
             if (grpcRecvNs === undefined || parseStartedNs === undefined || parseFinishedNs === undefined) {
                 return;
             }
@@ -530,6 +547,9 @@ class YellowstoneGrpc {
                 metadata.local_queue_latency_us = queueUs;
                 metadata.parse_duration_us = parseUs;
                 metadata.local_processing_latency_us = processingUs;
+                if (sourceToGrpcLatencyUs !== undefined) {
+                    metadata.source_to_grpc_latency_us = sourceToGrpcLatencyUs;
+                }
             }
         };
         const rememberParsedUpdate = (identity, slot) => {
@@ -555,7 +575,7 @@ class YellowstoneGrpc {
                 seenHead = 0;
             }
         };
-        const processUpdate = ({ update, grpcRecvUs, grpcRecvNs, blockTimeUs }) => {
+        const processUpdate = ({ update, grpcRecvUs, grpcRecvNs, blockTimeUs, sourceToGrpcLatencyUs, }) => {
             const identity = updateIdentity(update);
             const slotForReplay = updateSlot(update);
             if (replayOnReconnect && identity !== undefined && seenUpdates.has(identity)) {
@@ -585,15 +605,16 @@ class YellowstoneGrpc {
                     eventTypeFilter,
                 });
                 const parseFinishedNs = grpcRecvNs === undefined ? undefined : process.hrtime.bigint();
-                annotateLocalMetrics(txEvents, grpcRecvNs, parseStartedNs, parseFinishedNs);
+                annotateLocalMetrics(txEvents, grpcRecvNs, parseStartedNs, parseFinishedNs, sourceToGrpcLatencyUs);
                 order.pushTransactionEvents(txEvents, fallbackSlot, fallbackTxIndex, emitEvent);
             }
             if (update.account) {
                 const parseStartedNs = grpcRecvNs === undefined ? undefined : process.hrtime.bigint();
                 const ev = this.parseAccountEventRaw(update.account, grpcRecvUs, eventTypeFilter, blockTimeUs);
                 const parseFinishedNs = grpcRecvNs === undefined ? undefined : process.hrtime.bigint();
-                if (ev)
-                    annotateLocalMetrics([ev], grpcRecvNs, parseStartedNs, parseFinishedNs);
+                if (ev) {
+                    annotateLocalMetrics([ev], grpcRecvNs, parseStartedNs, parseFinishedNs, sourceToGrpcLatencyUs);
+                }
                 if (ev)
                     emitEvent(ev);
             }
@@ -746,11 +767,13 @@ class YellowstoneGrpc {
                                     });
                                     return;
                                 }
+                                const createdAtUs = YellowstoneGrpc.timestampToMicros(update.createdAt ?? update.created_at);
                                 const accepted = ingress.push({
                                     update,
                                     grpcRecvUs,
                                     grpcRecvNs,
-                                    blockTimeUs: YellowstoneGrpc.timestampToMicros(update.createdAt ?? update.created_at),
+                                    blockTimeUs: createdAtUs,
+                                    sourceToGrpcLatencyUs: createdAtUs === undefined ? undefined : Math.max(0, grpcRecvUs - createdAtUs),
                                 });
                                 if (!accepted) {
                                     const now = Date.now();
@@ -878,6 +901,7 @@ class YellowstoneGrpc {
     }
     /** 获取最新区块哈希 */
     async getLatestBlockhash(commitment) {
+        await this.connect();
         const resp = await this.client.getLatestBlockhash(commitment);
         return {
             slot: Number(resp.slot),
@@ -887,21 +911,25 @@ class YellowstoneGrpc {
     }
     /** 获取区块高度 */
     async getBlockHeight(commitment) {
+        await this.connect();
         const resp = await this.client.getBlockHeight(commitment);
-        return Number(resp);
+        return Number(resp.blockHeight);
     }
     /** 获取当前 Slot */
     async getSlot(commitment) {
+        await this.connect();
         const resp = await this.client.getSlot(commitment);
-        return Number(resp);
+        return Number(resp.slot);
     }
     /** 获取服务器版本 */
     async getVersion() {
+        await this.connect();
         const resp = await this.client.getVersion();
-        return String(resp);
+        return resp.version;
     }
     /** 验证区块哈希是否有效 */
     async isBlockhashValid(blockhash, commitment) {
+        await this.connect();
         const resp = await this.client.isBlockhashValid(blockhash, commitment);
         return {
             slot: Number(resp.slot),

package/dist/grpc/geyser_connect.d.ts

@@ -4,8 +4,7 @@
  * `@triton-one/yellowstone-grpc` 的 `Client` 通过构造函数第三参传入 `ChannelOptions`；
  * `connectTimeoutMs` 无与 tonic 完全一一对应的项，仅作文档与默认值对齐（可配合环境网络调优）。
  */
-import type { ChannelOptions } from "@grpc/grpc-js";
-import Client from "@triton-one/yellowstone-grpc";
+import Client, { type ChannelOptions } from "@triton-one/yellowstone-grpc";
 /** 与 Rust `GeyserConnectConfig` 字段对应（毫秒 / 字节） */
 export interface GeyserConnectConfig {
     /** 对应 Rust `connect_timeout`（毫秒） */

package/dist/grpc/geyser_connect.js

@@ -6,6 +6,12 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.defaultGeyserConnectConfig = defaultGeyserConnectConfig;
 exports.geyserGrpcChannelOptions = geyserGrpcChannelOptions;
 exports.connectYellowstoneGeyser = connectYellowstoneGeyser;
+/**
+ * 与 Rust `sol-parser-sdk/src/grpc/geyser_connect.rs` 对齐：Yellowstone Geyser gRPC 连接选项。
+ *
+ * `@triton-one/yellowstone-grpc` 的 `Client` 通过构造函数第三参传入 `ChannelOptions`；
+ * `connectTimeoutMs` 无与 tonic 完全一一对应的项，仅作文档与默认值对齐（可配合环境网络调优）。
+ */
 const yellowstone_grpc_1 = __importDefault(require("@triton-one/yellowstone-grpc"));
 /** 公共字段与 Rust `GeyserConnectConfig::default` 一致，并包含 Node gRPC 通道默认值。 */
 function defaultGeyserConnectConfig() {
@@ -26,15 +32,17 @@ function geyserGrpcChannelOptions(config = defaultGeyserConnectConfig()) {
     const interval = config.keepAliveIntervalMs ?? 30_000;
     const timeout = config.keepAliveTimeoutMs ?? 5000;
     return {
-        "grpc.max_receive_message_length": max,
-        "grpc.max_send_message_length": max,
-        "grpc.keepalive_time_ms": interval,
-        "grpc.keepalive_timeout_ms": timeout,
-        /** 无活跃 RPC 时仍发 keepalive，避免长时间仅订阅时被中间设备掐断 */
-        "grpc.keepalive_permit_without_calls": 1,
-        "grpc.initial_reconnect_backoff_ms": config.initialReconnectBackoffMs,
-        "grpc.max_reconnect_backoff_ms": config.maxReconnectBackoffMs,
-        "grpc-node.flow_control_window": config.flowControlWindowBytes,
+        grpcConnectTimeout: config.connectTimeoutMs,
+        grpcMaxDecodingMessageSize: max,
+        grpcMaxEncodingMessageSize: max,
+        grpcHttp2KeepAliveInterval: interval,
+        grpcKeepAliveTimeout: timeout,
+        grpcTcpKeepalive: interval,
+        grpcInitialConnectionWindowSize: config.flowControlWindowBytes,
+        grpcInitialStreamWindowSize: config.flowControlWindowBytes,
+        grpcHttp2AdaptiveWindow: true,
+        grpcKeepAliveWhileIdle: true,
+        grpcTcpNodelay: true,
     };
 }
 /**
@@ -42,5 +50,7 @@ function geyserGrpcChannelOptions(config = defaultGeyserConnectConfig()) {
  * Rust 为 async；此处构造同步完成，返回 `Promise` 以保持 `await connectYellowstoneGeyser(...)` 写法。
  */
 async function connectYellowstoneGeyser(endpoint, config = defaultGeyserConnectConfig()) {
-    return new yellowstone_grpc_1.default(endpoint, config.xToken, geyserGrpcChannelOptions(config));
+    const client = new yellowstone_grpc_1.default(endpoint, config.xToken, geyserGrpcChannelOptions(config));
+    await client.connect();
+    return client;
 }

package/dist/grpc/rpc_to_grpc.d.ts

@@ -1,6 +1,8 @@
-import type { Transaction as YTransaction, TransactionStatusMeta } from "@triton-one/yellowstone-grpc/dist/grpc/solana-storage.js";
+import type { SubscribeUpdateTransactionInfo } from "@triton-one/yellowstone-grpc";
 import { type VersionedTransactionResponse } from "@solana/web3.js";
 import type { ParseError } from "../core/error.js";
+type YTransaction = NonNullable<SubscribeUpdateTransactionInfo["transaction"]>;
+type TransactionStatusMeta = NonNullable<SubscribeUpdateTransactionInfo["meta"]>;
 export type ConvertRpcToGrpcOk = {
     ok: true;
     meta: TransactionStatusMeta;
@@ -16,3 +18,4 @@ export type ConvertRpcToGrpcErr = {
 export declare function convertRpcToGrpc(tx: VersionedTransactionResponse): ConvertRpcToGrpcOk | ConvertRpcToGrpcErr;
 /** Rust 蛇形命名 */
 export declare const convert_rpc_to_grpc: typeof convertRpcToGrpc;
+export {};

package/dist/grpc/transaction_meta.d.ts

@@ -1,4 +1,7 @@
-import type { TokenBalance, Transaction, TransactionStatusMeta } from "@triton-one/yellowstone-grpc/dist/grpc/solana-storage.js";
+import type { SubscribeUpdateTransactionInfo } from "@triton-one/yellowstone-grpc";
+type Transaction = NonNullable<SubscribeUpdateTransactionInfo["transaction"]>;
+type TransactionStatusMeta = NonNullable<SubscribeUpdateTransactionInfo["meta"]>;
+type TokenBalance = TransactionStatusMeta["preTokenBalances"][number];
 /** 32 字节公钥 → Base58（无效长度返回 `null`） */
 export declare function pubkeyBytesToBs58(bytes: Uint8Array): string | null;
 /**
@@ -27,3 +30,4 @@ export declare function splTokenCounterpartyByOwner(meta: TransactionStatusMeta,
 export declare function collectWatchTransferCounterpartyPairs(tx: Transaction, meta: TransactionStatusMeta, watchedBs58: string[], minNativeOutflowLamports: bigint, splMinWatchDecreaseRaw: bigint): [string, string][] | null;
 /** Yellowstone 交易签名原始字节（64）→ Base58 签名字符串；长度非 64 返回 `null` */
 export declare function tryYellowstoneSignature(sig: Uint8Array): string | null;
+export {};

package/dist/grpc/yellowstone_transaction_adapter.d.ts

@@ -1,4 +1,7 @@
 import { type VersionedTransactionResponse } from "@solana/web3.js";
-import type { Transaction as YellowstoneTransaction, TransactionStatusMeta as YellowstoneMeta } from "@triton-one/yellowstone-grpc/dist/grpc/solana-storage.js";
+import type { SubscribeUpdateTransactionInfo } from "@triton-one/yellowstone-grpc";
+type YellowstoneTransaction = NonNullable<SubscribeUpdateTransactionInfo["transaction"]>;
+type YellowstoneMeta = NonNullable<SubscribeUpdateTransactionInfo["meta"]>;
 /** Convert Yellowstone protobuf objects directly, without a WASM/Base58 serialization round trip. */
 export declare function yellowstoneTransactionToWeb3(transaction: YellowstoneTransaction, meta: YellowstoneMeta, slot: number, blockTime: number | null): VersionedTransactionResponse;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sol-parser-sdk",
-  "version": "0.5.13",
+  "version": "0.5.14",
   "description": "High-performance Solana DEX event parser for Node.js/TypeScript (Yellowstone gRPC, log parsing)",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -20,7 +20,7 @@
   },
   "homepage": "https://github.com/0xfnzero/sol-parser-sdk-nodejs#readme",
   "engines": {
-    "node": ">=18"
+    "node": ">=20.18.0"
   },
   "scripts": {
     "build": "tsc && mkdir -p dist/shredstream && cp src/shredstream/shredstream.proto dist/shredstream/",
@@ -58,7 +58,7 @@
     "@grpc/grpc-js": "^1.12.4",
     "@grpc/proto-loader": "^0.7.13",
     "@solana/web3.js": "^1.95.4",
-    "@triton-one/yellowstone-grpc": "^1.0.0",
+    "@triton-one/yellowstone-grpc": "7.0.0",
     "bs58": "^6.0.0"
   }
 }