sol-parser-sdk-nodejs 0.3.0 → 0.4.0

package/dist/shredstream/client.d.ts

@@ -0,0 +1,62 @@
+import { type DexEvent } from "../core/dex_event.js";
+import { type ShredStreamConfig } from "./config.js";
+/** 订阅周期内累计（用于排查「无 gRPC 包 / 解码失败 / 无 DEX 事件」） */
+export type ShredStreamReceiveStats = {
+    entryMessagesReceived: number;
+    entryDecodeFailures: number;
+    transactionsDecoded: number;
+    dexEventsQueued: number;
+};
+/** 有界 FIFO 队列（容量与 Rust `ArrayQueue::new(100_000)` 一致；`clone()` 共享底层缓冲，同 `Arc<ArrayQueue>`） */
+export declare class ShredEventQueue {
+    private static readonly CAP;
+    private readonly buf;
+    constructor(sharedBuf?: DexEvent[]);
+    /** 当前元素个数（与 Rust `ArrayQueue::len` 一致） */
+    len(): number;
+    /** 最大容量 */
+    capacity(): number;
+    push(e: DexEvent): boolean;
+    pop(): DexEvent | undefined;
+    clone(): ShredEventQueue;
+}
+export declare class ShredStreamClient {
+    private readonly endpoint;
+    private readonly config;
+    private readonly ServiceClient;
+    private loopAbort;
+    private loopPromise;
+    private activeCall;
+    private receiveStats;
+    private constructor();
+    static connect(endpoint: string): Promise<ShredStreamClient>;
+    /** 与 Rust `ShredStreamClient::new` 一致 */
+    static new(endpoint: string): Promise<ShredStreamClient>;
+    static connectWithConfig(endpoint: string, config: ShredStreamConfig): Promise<ShredStreamClient>;
+    /** 与 Rust `ShredStreamClient::new_with_config` 一致 */
+    static newWithConfig(endpoint: string, config: ShredStreamConfig): Promise<ShredStreamClient>;
+    /** 与 Rust `#[derive(Clone)]` 一致：多句柄共享同一连接状态（TS 中为同一对象引用） */
+    clone(): ShredStreamClient;
+    /** 当前订阅周期内 gRPC Entry 条数、解码失败次数、解码出的交易数、入队 DexEvent 数 */
+    getReceiveStats(): Readonly<ShredStreamReceiveStats>;
+    /**
+     * 与 Rust `new_with_config` 中 `ShredstreamProxyClient::connect_with_config(endpoint, &config)` 一致：
+     * `connection_timeout_ms` / `request_timeout_ms` / `max_decoding_message_size` 见 `shredstream/proto/mod.rs`。
+     */
+    private pingConnection;
+    /**
+     * 订阅 DEX 事件（自动重连）；返回队列供轮询消费（与 Rust `subscribe` 一致）。
+     * 重连循环使用订阅时刻的配置快照（与 Rust 在 `tokio::spawn` 前 `config.clone()` 一致）。
+     */
+    subscribe(): Promise<ShredEventQueue>;
+    /** 停止订阅并中止当前流 */
+    stop(): Promise<void>;
+    private runReconnectLoop;
+    /** 与 Rust `stream_events` + `connect_with_config`（tonic Endpoint / Grpc 消息上限）一致 */
+    private streamOnce;
+    private processEntryMessage;
+    /** 无 RPC：仅用静态账户表 */
+    private processEntryMessageSync;
+    /** 拉取 ALT 后完整账户表解析 */
+    private processEntryMessageWithAlt;
+}

package/dist/shredstream/client.js

@@ -0,0 +1,399 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ShredStreamClient = exports.ShredEventQueue = void 0;
+/**
+ * ShredStream 客户端：与 Rust `shredstream/client.rs` 对齐（gRPC + bincode 解码 + `parseTransactionEvents`）。
+ */
+const grpc = __importStar(require("@grpc/grpc-js"));
+const protoLoader = __importStar(require("@grpc/proto-loader"));
+const node_path_1 = require("node:path");
+const unified_parser_js_1 = require("../core/unified_parser.js");
+const instruction_parse_js_1 = require("./instruction_parse.js");
+const alt_lookup_js_1 = require("./alt_lookup.js");
+const config_js_1 = require("./config.js");
+const entries_decode_js_1 = require("./entries_decode.js");
+const PROTO_PATH = (0, node_path_1.join)(__dirname, "shredstream.proto");
+function loadProtoDefinition() {
+    const packageDefinition = protoLoader.loadSync(PROTO_PATH, {
+        keepCase: true,
+        longs: String,
+        enums: String,
+        defaults: true,
+        oneofs: true,
+    });
+    return grpc.loadPackageDefinition(packageDefinition);
+}
+function grpcTarget(endpoint) {
+    try {
+        const u = new URL(endpoint.includes("://") ? endpoint : `http://${endpoint}`);
+        return u.host;
+    }
+    catch {
+        return endpoint;
+    }
+}
+/** 与 tonic 对 `https://` 端点使用 TLS 的行为对齐 */
+function grpcCredentialsForEndpoint(endpoint) {
+    try {
+        const u = new URL(endpoint.includes("://") ? endpoint : `http://${endpoint}`);
+        if (u.protocol === "https:") {
+            return grpc.credentials.createSsl();
+        }
+    }
+    catch {
+        /* use insecure */
+    }
+    return grpc.credentials.createInsecure();
+}
+function sleepMs(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+function shredDebugEnabled() {
+    const v = process.env.SHREDSTREAM_DEBUG;
+    return v === "1" || v === "true";
+}
+/** 有界 FIFO 队列（容量与 Rust `ArrayQueue::new(100_000)` 一致；`clone()` 共享底层缓冲，同 `Arc<ArrayQueue>`） */
+class ShredEventQueue {
+    static CAP = 100_000;
+    buf;
+    constructor(sharedBuf) {
+        this.buf = sharedBuf ?? [];
+    }
+    /** 当前元素个数（与 Rust `ArrayQueue::len` 一致） */
+    len() {
+        return this.buf.length;
+    }
+    /** 最大容量 */
+    capacity() {
+        return ShredEventQueue.CAP;
+    }
+    push(e) {
+        if (this.buf.length >= ShredEventQueue.CAP)
+            return false;
+        this.buf.push(e);
+        return true;
+    }
+    pop() {
+        return this.buf.shift();
+    }
+    clone() {
+        return new ShredEventQueue(this.buf);
+    }
+}
+exports.ShredEventQueue = ShredEventQueue;
+function setGrpcRecvUsMut(event, grpcRecvUs) {
+    const key = Object.keys(event)[0];
+    if (key === "Error")
+        return;
+    const inner = event[key];
+    if (inner?.metadata)
+        inner.metadata.grpc_recv_us = grpcRecvUs;
+}
+class ShredStreamClient {
+    endpoint;
+    config;
+    ServiceClient;
+    loopAbort = null;
+    loopPromise = null;
+    activeCall = null;
+    receiveStats = {
+        entryMessagesReceived: 0,
+        entryDecodeFailures: 0,
+        transactionsDecoded: 0,
+        dexEventsQueued: 0,
+    };
+    constructor(endpoint, config) {
+        this.endpoint = endpoint;
+        this.config = config;
+        const root = loadProtoDefinition();
+        const shred = root.shredstream;
+        this.ServiceClient = shred.ShredstreamProxy;
+    }
+    static async connect(endpoint) {
+        return ShredStreamClient.connectWithConfig(endpoint, (0, config_js_1.defaultShredStreamConfig)());
+    }
+    /** 与 Rust `ShredStreamClient::new` 一致 */
+    static new(endpoint) {
+        return ShredStreamClient.connect(endpoint);
+    }
+    static async connectWithConfig(endpoint, config) {
+        const client = new ShredStreamClient(endpoint, config);
+        await client.pingConnection();
+        return client;
+    }
+    /** 与 Rust `ShredStreamClient::new_with_config` 一致 */
+    static newWithConfig(endpoint, config) {
+        return ShredStreamClient.connectWithConfig(endpoint, config);
+    }
+    /** 与 Rust `#[derive(Clone)]` 一致：多句柄共享同一连接状态（TS 中为同一对象引用） */
+    clone() {
+        return this;
+    }
+    /** 当前订阅周期内 gRPC Entry 条数、解码失败次数、解码出的交易数、入队 DexEvent 数 */
+    getReceiveStats() {
+        return { ...this.receiveStats };
+    }
+    /**
+     * 与 Rust `new_with_config` 中 `ShredstreamProxyClient::connect_with_config(endpoint, &config)` 一致：
+     * `connection_timeout_ms` / `request_timeout_ms` / `max_decoding_message_size` 见 `shredstream/proto/mod.rs`。
+     */
+    pingConnection() {
+        const target = grpcTarget(this.endpoint);
+        const creds = grpcCredentialsForEndpoint(this.endpoint);
+        const channelOpts = {
+            "grpc.max_receive_message_length": this.config.max_decoding_message_size,
+            "grpc.max_send_message_length": this.config.max_decoding_message_size,
+        };
+        const c = new this.ServiceClient(target, creds, channelOpts);
+        const deadline = Date.now() + this.config.connection_timeout_ms;
+        return new Promise((resolve, reject) => {
+            c.waitForReady(deadline, (err) => {
+                c.close();
+                if (err)
+                    reject(err);
+                else
+                    resolve();
+            });
+        });
+    }
+    /**
+     * 订阅 DEX 事件（自动重连）；返回队列供轮询消费（与 Rust `subscribe` 一致）。
+     * 重连循环使用订阅时刻的配置快照（与 Rust 在 `tokio::spawn` 前 `config.clone()` 一致）。
+     */
+    async subscribe() {
+        await this.stop();
+        this.receiveStats = {
+            entryMessagesReceived: 0,
+            entryDecodeFailures: 0,
+            transactionsDecoded: 0,
+            dexEventsQueued: 0,
+        };
+        const queue = new ShredEventQueue();
+        const ac = new AbortController();
+        this.loopAbort = ac;
+        const configSnapshot = { ...this.config };
+        this.loopPromise = this.runReconnectLoop(queue, ac.signal, configSnapshot);
+        return queue;
+    }
+    /** 停止订阅并中止当前流 */
+    async stop() {
+        this.loopAbort?.abort();
+        this.loopAbort = null;
+        this.activeCall?.cancel();
+        this.activeCall = null;
+        if (this.loopPromise) {
+            await this.loopPromise.catch(() => undefined);
+            this.loopPromise = null;
+        }
+    }
+    async runReconnectLoop(queue, signal, config) {
+        let delay = config.reconnect_delay_ms;
+        let attempts = 0;
+        while (!signal.aborted) {
+            const max = config.max_reconnect_attempts;
+            if (max > 0 && attempts >= max) {
+                console.error("Max reconnection attempts reached, giving up");
+                break;
+            }
+            attempts += 1;
+            try {
+                await this.streamOnce(queue, signal, config);
+                delay = config.reconnect_delay_ms;
+                attempts = 0;
+            }
+            catch (e) {
+                if (signal.aborted)
+                    break;
+                const msg = e instanceof Error ? e.message : String(e);
+                console.error(`ShredStream error: ${msg} - retry in ${delay}ms`);
+                await sleepMs(delay);
+                if (signal.aborted)
+                    break;
+                delay = Math.min(delay * 2, 60_000);
+            }
+        }
+    }
+    /** 与 Rust `stream_events` + `connect_with_config`（tonic Endpoint / Grpc 消息上限）一致 */
+    streamOnce(queue, signal, config) {
+        if (signal.aborted)
+            return Promise.resolve();
+        const target = grpcTarget(this.endpoint);
+        const creds = grpcCredentialsForEndpoint(this.endpoint);
+        const channelOpts = {
+            "grpc.max_receive_message_length": config.max_decoding_message_size,
+            "grpc.max_send_message_length": config.max_decoding_message_size,
+        };
+        const client = new this.ServiceClient(target, creds, channelOpts);
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            const finish = (fn) => {
+                if (settled)
+                    return;
+                settled = true;
+                fn();
+            };
+            const call = client.subscribeEntries({}, new grpc.Metadata());
+            this.activeCall = call;
+            console.info("ShredStream connected, receiving entries...");
+            call.on("data", (entry) => {
+                if (signal.aborted)
+                    return;
+                try {
+                    void this.processEntryMessage(entry, queue);
+                }
+                catch (err) {
+                    console.error("processEntryMessage:", err);
+                }
+            });
+            call.on("error", (err) => {
+                client.close();
+                if (signal.aborted || err.code === grpc.status.CANCELLED) {
+                    finish(() => resolve());
+                    return;
+                }
+                console.error("Stream error:", err);
+                finish(() => reject(err));
+            });
+            call.on("end", () => {
+                client.close();
+                finish(() => resolve());
+            });
+        });
+    }
+    async processEntryMessage(entry, queue) {
+        this.receiveStats.entryMessagesReceived += 1;
+        const recvUs = (0, unified_parser_js_1.nowUs)();
+        const slotNum = toSlotNumber(entry.slot);
+        const raw = entry.entries;
+        const bytes = raw instanceof Buffer ? new Uint8Array(raw) : new Uint8Array(raw);
+        let decoded;
+        try {
+            decoded = (0, entries_decode_js_1.decodeShredstreamEntriesBincode)(bytes);
+        }
+        catch (e) {
+            this.receiveStats.entryDecodeFailures += 1;
+            const msg = e instanceof Error ? e.message : String(e);
+            console.warn(`[shredstream] bincode 解码失败 slot=${slotNum} bytes=${bytes.length}: ${msg}`);
+            return;
+        }
+        const conn = this.config.connection;
+        if (conn) {
+            try {
+                await this.processEntryMessageWithAlt(decoded, slotNum, recvUs, queue, bytes.length, conn);
+            }
+            catch (e) {
+                console.warn(`[shredstream] ALT/RPC 解析失败 slot=${slotNum}:`, e);
+                this.processEntryMessageSync(decoded, slotNum, recvUs, queue, bytes.length);
+            }
+            return;
+        }
+        this.processEntryMessageSync(decoded, slotNum, recvUs, queue, bytes.length);
+    }
+    /** 无 RPC：仅用静态账户表 */
+    processEntryMessageSync(decoded, slotNum, recvUs, queue, entriesBytesLen) {
+        let txTotal = 0;
+        let evTotal = 0;
+        /** 与 golang `shredstream_entries` 一致：单条 gRPC 消息内跨所有 Solana Entry 的连续下标 */
+        let globalTxIndex = 0;
+        for (const outer of decoded) {
+            const txs = outer;
+            txTotal += txs.length;
+            for (let i = 0; i < txs.length; i++) {
+                const tx = txs[i];
+                const txIndex = globalTxIndex++;
+                if (!tx?.signature)
+                    continue;
+                const events = (0, instruction_parse_js_1.dexEventsFromShredWasmTx)(tx, slotNum, txIndex, recvUs, undefined);
+                evTotal += events.length;
+                for (const ev of events) {
+                    setGrpcRecvUsMut(ev, recvUs);
+                    queue.push(ev);
+                }
+            }
+        }
+        this.receiveStats.transactionsDecoded += txTotal;
+        this.receiveStats.dexEventsQueued += evTotal;
+        if (shredDebugEnabled()) {
+            console.info(`[shredstream] slot=${slotNum} entries_bytes=${entriesBytesLen} solana_entries=${decoded.length} txs=${txTotal} dex_events=${evTotal} (static_accounts_only)`);
+        }
+    }
+    /** 拉取 ALT 后完整账户表解析 */
+    async processEntryMessageWithAlt(decoded, slotNum, recvUs, queue, entriesBytesLen, conn) {
+        const altKeys = new Set();
+        for (const outer of decoded) {
+            for (const tx of outer) {
+                for (const l of tx.addressTableLookups ?? []) {
+                    altKeys.add(l.accountKey);
+                }
+            }
+        }
+        const altMap = await (0, alt_lookup_js_1.loadAddressLookupTableAccounts)(conn, [...altKeys]);
+        let txTotal = 0;
+        let evTotal = 0;
+        let globalTxIndex = 0;
+        for (const outer of decoded) {
+            const txs = outer;
+            txTotal += txs.length;
+            for (let i = 0; i < txs.length; i++) {
+                const tx = txs[i];
+                const txIndex = globalTxIndex++;
+                if (!tx?.signature)
+                    continue;
+                const fullKeys = (0, alt_lookup_js_1.fullAccountKeyStringsFromShredTx)(tx, altMap);
+                const events = (0, instruction_parse_js_1.dexEventsFromShredWasmTxWithFullKeys)(tx, fullKeys, slotNum, txIndex, recvUs, undefined);
+                evTotal += events.length;
+                for (const ev of events) {
+                    setGrpcRecvUsMut(ev, recvUs);
+                    queue.push(ev);
+                }
+            }
+        }
+        this.receiveStats.transactionsDecoded += txTotal;
+        this.receiveStats.dexEventsQueued += evTotal;
+        if (shredDebugEnabled()) {
+            console.info(`[shredstream] slot=${slotNum} entries_bytes=${entriesBytesLen} solana_entries=${decoded.length} txs=${txTotal} dex_events=${evTotal} alt_tables=${altKeys.size}`);
+        }
+    }
+}
+exports.ShredStreamClient = ShredStreamClient;
+function toSlotNumber(slot) {
+    if (typeof slot === "number")
+        return slot;
+    if (typeof slot === "bigint")
+        return Number(slot);
+    const n = Number(slot);
+    return Number.isFinite(n) ? Math.floor(n) : 0;
+}

package/dist/shredstream/config.d.ts

@@ -0,0 +1,30 @@
+import type { Connection } from "@solana/web3.js";
+/**
+ * 与 Rust `sol-parser-sdk/src/shredstream/config.rs` 字段一一对应。
+ *
+ * Rust：`connect_with_config` 使用 `connection_timeout_ms` → tonic `Endpoint::connect_timeout`，
+ * `max_decoding_message_size` → `Grpc::max_*_message_size`；**未**对长流设置 `Endpoint::timeout`
+ * （`request_timeout_ms` 保留与 Rust `config.rs` 一致，流式路径不填 deadline）。
+ * `reconnect_delay_ms` / `max_reconnect_attempts` 由 `client.rs` 重连循环使用。
+ *
+ * **TS 扩展**：`connection` 用于拉取链上 ALT，补全 V0 交易账户表以解析外层指令（主网 Pump 等必需）。
+ */
+export interface ShredStreamConfig {
+    /** 连接超时（毫秒）→ tonic `Endpoint::connect_timeout` / gRPC `waitForReady` */
+    connection_timeout_ms: number;
+    /** 与 Rust 字段一致；长流 `SubscribeEntries` 不设单 RPC deadline（避免断流） */
+    request_timeout_ms: number;
+    /** 最大编解码消息大小（字节）→ tonic `Grpc` / `@grpc/grpc-js` channel 选项 */
+    max_decoding_message_size: number;
+    /** 自动重连延迟（毫秒） */
+    reconnect_delay_ms: number;
+    /** 最大重连次数（0 表示无限重连） */
+    max_reconnect_attempts: number;
+    /** 可选：主网 RPC，用于解析 V0 地址查找表（ALT） */
+    connection?: Connection;
+}
+export declare function defaultShredStreamConfig(): ShredStreamConfig;
+/** 低延迟：更短超时与重连间隔 */
+export declare function lowLatencyShredStreamConfig(): ShredStreamConfig;
+/** 高吞吐：更大消息与更多重试 */
+export declare function highThroughputShredStreamConfig(): ShredStreamConfig;

package/dist/shredstream/config.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultShredStreamConfig = defaultShredStreamConfig;
+exports.lowLatencyShredStreamConfig = lowLatencyShredStreamConfig;
+exports.highThroughputShredStreamConfig = highThroughputShredStreamConfig;
+function defaultShredStreamConfig() {
+    return {
+        connection_timeout_ms: 8000,
+        request_timeout_ms: 15_000,
+        max_decoding_message_size: 1024 * 1024 * 100,
+        reconnect_delay_ms: 1000,
+        max_reconnect_attempts: 3,
+    };
+}
+/** 低延迟：更短超时与重连间隔 */
+function lowLatencyShredStreamConfig() {
+    return {
+        connection_timeout_ms: 5000,
+        request_timeout_ms: 10_000,
+        max_decoding_message_size: 1024 * 1024 * 50,
+        reconnect_delay_ms: 100,
+        max_reconnect_attempts: 1,
+    };
+}
+/** 高吞吐：更大消息与更多重试 */
+function highThroughputShredStreamConfig() {
+    return {
+        connection_timeout_ms: 10_000,
+        request_timeout_ms: 30_000,
+        max_decoding_message_size: 1024 * 1024 * 200,
+        reconnect_delay_ms: 2000,
+        max_reconnect_attempts: 5,
+    };
+}

package/dist/shredstream/entries_decode.d.ts

@@ -0,0 +1,28 @@
+/**
+ * gRPC `Entry.entries` 负载解码：对齐 sol-parser-sdk-golang `shredstream/entries_decode.go`
+ *（bincode Vec<Entry> 前缀 + 每笔线格式交易定长扫描）。
+ */
+import type { ShredWasmTx } from "./instruction_parse.js";
+export type DecodedWireTransaction = {
+    raw: Uint8Array;
+    /** 全部签名（每笔交易至少一枚；展示用首签） */
+    signatures: Uint8Array[];
+};
+/** 与 Go `BincodeVecEntryCount` 一致 */
+export declare function bincodeVecEntryCount(entriesBytes: Uint8Array): bigint;
+/** compact-u16，与 Go `decodeCompactU16` 一致 */
+export declare function decodeCompactU16(buf: Uint8Array, pos: number): {
+    value: number;
+    bytes: number;
+} | null;
+/** 返回 (txWireLength, signatures)；失败返回 null */
+export declare function parseTransaction(buf: Uint8Array, pos: number): {
+    txLen: number;
+    sigs: Uint8Array[];
+} | null;
+export declare function decodeEntriesBincodeFlat(entriesBytes: Uint8Array): DecodedWireTransaction[];
+export declare function decodeEntriesBincodeNested(entriesBytes: Uint8Array): DecodedWireTransaction[][];
+/**
+ * 解码 gRPC `entries` 字节并展开为与旧 WASM 相同的嵌套 `ShredWasmTx`（跳过无法反序列化的单笔交易）。
+ */
+export declare function decodeShredstreamEntriesBincode(bytes: Uint8Array): ShredWasmTx[][];