sol-parser-sdk 0.5.12 → 0.5.13

package/README.md

@@ -75,7 +75,7 @@
 **From npm**
 
 ```bash
-npm install sol-parser-sdk@0.5.12
+npm install sol-parser-sdk@0.5.13
 ```
 
 **From source** (folder may be named `sol-parser-sdk-ts` in a monorepo)
@@ -176,6 +176,14 @@ queue with `sub.len()` / `sub.eventDropped()` and the pre-parser queue with
 `sub.ingressLen()` / `sub.ingressDropped()`. `sub.dropped()` is the combined count. Every overflow
 is counted and periodically reported through `sub.errors`.
 
+Automatic reconnect resumes from the last successfully parsed slot by default and deduplicates
+replayed transaction/account updates. Monitor transport continuity with `sub.isStreamConnected()`,
+`sub.streamDisconnects()`, `sub.reconnects()`, `sub.replayedUpdates()`, and
+`sub.continuityBreaks()`. A zero local drop count does not describe updates lost before the gRPC
+`data` callback. If a provider rejects Yellowstone `fromSlot`, the SDK reports the failure through
+`sub.errors`, increments `continuityBreaks()`, and reconnects live. Set `replayOnReconnect: false`
+only when duplicate-free live delivery is more important than recovering a disconnect window.
+
 For precise local-only measurements, set `config.enable_metrics = true`. Event metadata then includes
 `local_queue_latency_us`, `parse_duration_us`, and `local_processing_latency_us`. These values use
 Node's monotonic high-resolution clock. They measure only local queueing and parsing; the hot path

package/README_CN.md

@@ -75,7 +75,7 @@
 **npm**
 
 ```bash
-npm install sol-parser-sdk@0.5.12
+npm install sol-parser-sdk@0.5.13
 ```
 
 **源码**（monorepo 里目录可能是 `sol-parser-sdk-ts`）
@@ -174,6 +174,13 @@ for await (const event of sub) {
 公开事件队列，通过 `sub.ingressLen()` / `sub.ingressDropped()` 监控解析前入口队列；
 `sub.dropped()` 返回两者之和。每次溢出都会计数，并定期通过 `sub.errors` 报告。
 
+自动重连默认从最后一个成功解析的 slot 继续订阅，并对回放的 transaction/account update
+去重。可通过 `sub.isStreamConnected()`、`sub.streamDisconnects()`、`sub.reconnects()`、
+`sub.replayedUpdates()` 和 `sub.continuityBreaks()` 监控传输连续性。本地 drop 为零并不能说明
+进入 gRPC `data` 回调之前没有丢数据。如果 provider 拒绝 Yellowstone `fromSlot`，SDK 会通过
+`sub.errors` 明确报告，增加 `continuityBreaks()`，再降级为 live 重连。只有在“绝不接收回放重复”
+比“补偿断线窗口”更重要时，才应设置 `replayOnReconnect: false`。
+
 如需精确测量纯本地延迟，请设置 `config.enable_metrics = true`。事件 metadata 将包含
 `local_queue_latency_us`、`parse_duration_us` 和 `local_processing_latency_us`，这些字段使用
 Node 单调高精度时钟，只测量本地排队与解析。热路径不会调用 `getSlot`、`getTransaction`、

package/dist/grpc/client.d.ts

@@ -18,6 +18,12 @@ export interface DexEventSubscription extends AsyncIterable<DexEvent> {
     eventDropped(): number;
     ingressLen(): number;
     ingressDropped(): number;
+    isStreamConnected(): boolean;
+    streamDisconnects(): number;
+    reconnects(): number;
+    replayedUpdates(): number;
+    /** Reconnects that could not resume from the last parsed slot. */
+    continuityBreaks(): number;
 }
 export interface SubscribeDexEventsOptions {
     autoReconnect?: boolean;
@@ -30,6 +36,10 @@ export interface SubscribeDexEventsOptions {
     ingressBufferSize?: number;
     /** Maximum raw updates parsed before yielding back to Node's event loop. Defaults to 8. */
     parserBatchSize?: number;
+    /** Resume from the last parsed slot after reconnect. Defaults to true. */
+    replayOnReconnect?: boolean;
+    /** Parsed slots retained for replay deduplication. Defaults to 128. */
+    replayDedupeSlots?: number;
 }
 /** Yellowstone gRPC 客户端包装器 */
 export declare class YellowstoneGrpc {

package/dist/grpc/client.js

@@ -42,6 +42,7 @@ exports.YellowstoneGrpc = void 0;
  */
 const yellowstone_grpc_1 = __importStar(require("@triton-one/yellowstone-grpc"));
 const bs58_1 = __importDefault(require("bs58"));
+const node_buffer_1 = require("node:buffer");
 const dex_event_js_1 = require("../core/dex_event.js");
 const metadata_js_1 = require("../core/metadata.js");
 const mod_js_1 = require("../accounts/mod.js");
@@ -66,6 +67,35 @@ function positiveIntegerOption(value, fallback, name) {
     }
     return normalized;
 }
+function replayUnsupported(error) {
+    const grpcError = error;
+    if (grpcError.code === 3 || grpcError.code === 11 || grpcError.code === 12)
+        return true;
+    return /from.?slot.*(?:unsupported|disabled|unavailable|invalid)/i.test(`${grpcError.message ?? ""} ${grpcError.details ?? ""}`);
+}
+function updateSlot(update) {
+    const value = update.transaction?.slot ?? update.account?.slot;
+    if (value === undefined || value === null)
+        return undefined;
+    try {
+        return BigInt(value);
+    }
+    catch {
+        return undefined;
+    }
+}
+function bytesKey(value) {
+    return node_buffer_1.Buffer.from(value.buffer, value.byteOffset, value.byteLength).toString("base64");
+}
+function updateIdentity(update) {
+    const transaction = update.transaction?.transaction;
+    if (transaction?.signature)
+        return `t:${bytesKey(transaction.signature)}`;
+    const account = update.account?.account;
+    if (!account?.pubkey)
+        return undefined;
+    return `a:${bytesKey(account.pubkey)}:${String(update.account?.slot ?? 0)}:${String(account.writeVersion ?? 0)}`;
+}
 /** Yellowstone gRPC 客户端包装器 */
 class YellowstoneGrpc {
     client;
@@ -440,12 +470,24 @@ class YellowstoneGrpc {
         const events = new async_event_queue_js_1.AsyncEventQueue(Math.max(1, this.config.buffer_size), options?.queueOverflowStrategy);
         const ingressBufferSize = positiveIntegerOption(options?.ingressBufferSize, Math.min(this.config.buffer_size, 1024), "ingressBufferSize");
         const parserBatchSize = positiveIntegerOption(options?.parserBatchSize, 8, "parserBatchSize");
+        const replayDedupeSlots = positiveIntegerOption(options?.replayDedupeSlots, 128, "replayDedupeSlots");
+        const replayOnReconnect = options?.replayOnReconnect !== false;
         const ingress = new async_event_queue_js_1.AsyncEventQueue(ingressBufferSize, options?.queueOverflowStrategy);
         const errors = new async_event_queue_js_1.AsyncEventQueue(Math.max(1, this.config.buffer_size));
         const order = new order_buffer_js_1.OrderDispatcher(this.config);
         const eventDropped = events.dropped.bind(events);
         let nextEventDropWarningAt = 0;
         let nextIngressDropWarningAt = 0;
+        let streamConnected = false;
+        let streamDisconnectCount = 0;
+        let reconnectCount = 0;
+        let replayedUpdateCount = 0;
+        let continuityBreakCount = 0;
+        let lastParsedSlot;
+        let highestRememberedSlot = 0n;
+        let seenHead = 0;
+        const seenUpdates = new Map();
+        const seenOrder = [];
         const reportError = (error) => errors.push(error);
         const emitEvent = (event) => {
             if (events.push(event))
@@ -490,7 +532,37 @@ class YellowstoneGrpc {
                 metadata.local_processing_latency_us = processingUs;
             }
         };
+        const rememberParsedUpdate = (identity, slot) => {
+            if (slot !== undefined && (lastParsedSlot === undefined || slot > lastParsedSlot)) {
+                lastParsedSlot = slot;
+            }
+            if (!replayOnReconnect || identity === undefined || slot === undefined)
+                return;
+            seenUpdates.set(identity, slot);
+            seenOrder.push({ identity, slot });
+            if (slot > highestRememberedSlot)
+                highestRememberedSlot = slot;
+            const retainFrom = highestRememberedSlot > BigInt(replayDedupeSlots)
+                ? highestRememberedSlot - BigInt(replayDedupeSlots)
+                : 0n;
+            while (seenHead < seenOrder.length && seenOrder[seenHead].slot < retainFrom) {
+                const stale = seenOrder[seenHead++];
+                if (seenUpdates.get(stale.identity) === stale.slot)
+                    seenUpdates.delete(stale.identity);
+            }
+            if (seenHead >= 4096 && seenHead * 2 >= seenOrder.length) {
+                seenOrder.splice(0, seenHead);
+                seenHead = 0;
+            }
+        };
         const processUpdate = ({ update, grpcRecvUs, grpcRecvNs, blockTimeUs }) => {
+            const identity = updateIdentity(update);
+            const slotForReplay = updateSlot(update);
+            if (replayOnReconnect && identity !== undefined && seenUpdates.has(identity)) {
+                replayedUpdateCount++;
+                rememberParsedUpdate(undefined, slotForReplay);
+                return;
+            }
             if (order.needsTimer)
                 order.flushDue(emitEvent);
             const txUpdate = update.transaction;
@@ -525,6 +597,7 @@ class YellowstoneGrpc {
                 if (ev)
                     emitEvent(ev);
             }
+            rememberParsedUpdate(identity, slotForReplay);
         };
         const scheduleIngressDrain = () => {
             if (isCancelled || ingressDrainScheduled || ingress.len() === 0)
@@ -618,25 +691,39 @@ class YellowstoneGrpc {
             const autoReconnect = options?.autoReconnect !== false;
             const maxBackoffMs = 60_000;
             let backoffMs = this.config.retry_delay_ms;
+            let replayAllowed = replayOnReconnect;
+            let attempt = 0;
             try {
                 while (!isCancelled) {
+                    let attemptedReplay = false;
+                    let receivedData = false;
                     try {
+                        attempt++;
+                        if (attempt > 1)
+                            reconnectCount++;
                         const stream = await this.client.subscribe();
                         if (isCancelled) {
                             cancelSubscribeStream(stream);
                             break;
                         }
                         streamHolder.current = stream;
+                        const request = (0, subscribe_builder_js_1.buildSubscribeRequest)(currentTransactionFilters, currentAccountFilters);
+                        if (attempt > 1 && replayAllowed && lastParsedSlot !== undefined) {
+                            request.fromSlot = lastParsedSlot.toString();
+                            attemptedReplay = true;
+                        }
                         await new Promise((resolve, reject) => {
-                            stream.write((0, subscribe_builder_js_1.buildSubscribeRequest)(currentTransactionFilters, currentAccountFilters), (err) => {
+                            stream.write(request, (err) => {
                                 if (err)
                                     reject(err);
                                 else
                                     resolve();
                             });
                         });
+                        streamConnected = true;
                         await new Promise((resolve, reject) => {
                             const cleanup = () => {
+                                streamConnected = false;
                                 stream.removeAllListeners();
                                 if (streamHolder.current === stream) {
                                     streamHolder.current = null;
@@ -645,6 +732,7 @@ class YellowstoneGrpc {
                             stream.on("data", (update) => {
                                 if (isCancelled)
                                     return;
+                                receivedData = true;
                                 const grpcRecvNs = this.config.enable_metrics
                                     ? process.hrtime.bigint()
                                     : undefined;
@@ -676,11 +764,15 @@ class YellowstoneGrpc {
                                 scheduleIngressDrain();
                             });
                             stream.on("error", (err) => {
+                                streamDisconnectCount++;
                                 cleanup();
                                 reject(err);
                             });
                             stream.on("end", () => {
+                                streamDisconnectCount++;
                                 cleanup();
+                                if (!isCancelled)
+                                    reportError(new Error("Yellowstone stream ended; reconnecting"));
                                 resolve();
                             });
                         });
@@ -690,15 +782,38 @@ class YellowstoneGrpc {
                             break;
                         cancelSubscribeStream(streamHolder.current);
                         streamHolder.current = null;
+                        streamConnected = false;
                         reportError(err instanceof Error ? err : new Error(String(err)));
-                        if (!autoReconnect)
+                        await waitForIngressIdle();
+                        if (!autoReconnect) {
+                            if (lastParsedSlot !== undefined)
+                                continuityBreakCount++;
                             break;
+                        }
+                        let continuityBreakRecorded = false;
+                        if (attemptedReplay && !receivedData && replayUnsupported(err)) {
+                            replayAllowed = false;
+                            continuityBreakCount++;
+                            continuityBreakRecorded = true;
+                            reportError(new Error("Yellowstone provider rejected fromSlot replay; reconnecting live and continuity is not guaranteed"));
+                        }
+                        if (!replayAllowed && lastParsedSlot !== undefined && !continuityBreakRecorded) {
+                            continuityBreakCount++;
+                        }
                         await waitBeforeReconnect(backoffMs);
                         backoffMs = Math.min(backoffMs * 2, maxBackoffMs);
                         continue;
                     }
-                    if (isCancelled || !autoReconnect)
+                    await waitForIngressIdle();
+                    if (isCancelled)
                         break;
+                    if (!autoReconnect) {
+                        if (lastParsedSlot !== undefined)
+                            continuityBreakCount++;
+                        break;
+                    }
+                    if (!replayAllowed && lastParsedSlot !== undefined)
+                        continuityBreakCount++;
                     await waitBeforeReconnect(backoffMs);
                     backoffMs = Math.min(backoffMs * 2, maxBackoffMs);
                 }
@@ -706,6 +821,7 @@ class YellowstoneGrpc {
             finally {
                 cancelSubscribeStream(streamHolder.current);
                 streamHolder.current = null;
+                streamConnected = false;
                 if (flushTimer)
                     clearInterval(flushTimer);
                 if (!isCancelled) {
@@ -725,6 +841,11 @@ class YellowstoneGrpc {
             eventDropped,
             ingressLen: () => ingress.len(),
             ingressDropped: () => ingress.dropped(),
+            isStreamConnected: () => streamConnected,
+            streamDisconnects: () => streamDisconnectCount,
+            reconnects: () => reconnectCount,
+            replayedUpdates: () => replayedUpdateCount,
+            continuityBreaks: () => continuityBreakCount,
             cancel: () => {
                 cancel();
                 this.dexSubscribers.delete(id);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sol-parser-sdk",
-  "version": "0.5.12",
+  "version": "0.5.13",
   "description": "High-performance Solana DEX event parser for Node.js/TypeScript (Yellowstone gRPC, log parsing)",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",