sol-parser-sdk 0.5.17 → 0.5.19

package/dist/rpc_transaction.js

@@ -41,6 +41,7 @@ const SUPPORTED_INSTRUCTION_PROGRAM_IDS = new Set([
     program_ids_js_1.RAYDIUM_AMM_V4_PROGRAM_ID,
     program_ids_js_1.ORCA_WHIRLPOOL_PROGRAM_ID,
     program_ids_js_1.METEORA_POOLS_PROGRAM_ID,
+    program_ids_js_1.METEORA_DBC_PROGRAM_ID,
     program_ids_js_1.METEORA_DAMM_V2_PROGRAM_ID,
     program_ids_js_1.METEORA_DLMM_PROGRAM_ID,
 ]);
@@ -51,8 +52,8 @@ function bytesEqualAt(data, expected, offset) {
     }
     return true;
 }
-function isDlmmEventCpi(programId, data) {
-    return programId === program_ids_js_1.METEORA_DLMM_PROGRAM_ID && data.length >= 16 && (bytesEqualAt(data, EVENT_CPI_PREFIX, 0) ||
+function isEventCpi(programId, data) {
+    return [program_ids_js_1.METEORA_DLMM_PROGRAM_ID, program_ids_js_1.PUMPFUN_PROGRAM_ID, program_ids_js_1.PUMPSWAP_PROGRAM_ID].includes(programId) && data.length >= 16 && (bytesEqualAt(data, EVENT_CPI_PREFIX, 0) ||
         bytesEqualAt(data, LEGACY_EVENT_CPI_SUFFIX, 8));
 }
 function isDlmmEvent(event) {
@@ -273,6 +274,9 @@ function mergeDlmmInstruction(baseName, base, inner) {
     if (context)
         Object.assign(base, context);
 }
+function pumpIdentityKeyConflicts(a, b) {
+    return !isDefaultValue(a) && !isDefaultValue(b) && a !== b;
+}
 function mergeInstructionEvent(base, inner) {
     const baseName = eventName(base);
     const innerName = eventName(inner);
@@ -281,6 +285,8 @@ function mergeInstructionEvent(base, inner) {
     if (!baseData || !innerData)
         return false;
     if (PUMPFUN_TRADE_EVENT_NAMES.has(baseName) && PUMPFUN_TRADE_EVENT_NAMES.has(innerName)) {
+        if (baseData.is_buy !== innerData.is_buy || pumpIdentityKeyConflicts(baseData.mint, innerData.mint) || pumpIdentityKeyConflicts(baseData.user, innerData.user))
+            return false;
         mergePumpfunTradeInstruction(baseData, innerData);
         return true;
     }
@@ -290,6 +296,8 @@ function mergeInstructionEvent(base, inner) {
     }
     if ((baseName === "PumpSwapBuy" && innerName === "PumpSwapBuy") ||
         (baseName === "PumpSwapSell" && innerName === "PumpSwapSell")) {
+        if (pumpIdentityKeyConflicts(baseData.pool, innerData.pool) || pumpIdentityKeyConflicts(baseData.user, innerData.user))
+            return false;
         mergePumpSwapBuySellInstruction(baseData, innerData);
         return true;
     }
@@ -304,6 +312,10 @@ function mergeInstructionEvent(base, inner) {
     }
     return false;
 }
+function isPumpTrade(event) {
+    const name = eventName(event);
+    return PUMPFUN_TRADE_EVENT_NAMES.has(name) || name === "PumpSwapBuy" || name === "PumpSwapSell";
+}
 function mergeInstructionEvents(events) {
     if (events.length === 0)
         return [];
@@ -317,11 +329,15 @@ function mergeInstructionEvents(events) {
     const out = [];
     let outerTarget = null;
     const dlmmTargets = [];
+    const pumpTargets = [];
     for (const item of events) {
         if (item.innerIdx === null) {
             out.push(item.event);
             const resultIdx = out.length - 1;
             outerTarget = { outerIdx: item.outerIdx, resultIdx };
+            pumpTargets.length = 0;
+            if (isPumpTrade(item.event))
+                pumpTargets.push({ outerIdx: item.outerIdx, stackHeight: item.stackHeight, resultIdx, consumed: false });
             dlmmTargets.length = 0;
             if (isDlmmEvent(item.event)) {
                 dlmmTargets.push({
@@ -332,7 +348,40 @@ function mergeInstructionEvents(events) {
             }
             continue;
         }
-        if (item.isDlmmEventCpi) {
+        if (isPumpTrade(item.event) && (item.isEventCpi || !PUMPFUN_TRADE_EVENT_NAMES.has(eventName(item.event)) || eventPayload(item.event)?.ix_name)) {
+            if (item.isEventCpi) {
+                let target;
+                for (let i = pumpTargets.length - 1; i >= 0; i--) {
+                    const candidate = pumpTargets[i];
+                    if (candidate.outerIdx === item.outerIdx && (candidate.stackHeight === undefined || item.stackHeight === undefined || item.stackHeight === candidate.stackHeight + 1)) {
+                        target = candidate;
+                        break;
+                    }
+                }
+                if (target && !target.consumed) {
+                    target.consumed = true;
+                    if (mergeInstructionEvent(out[target.resultIdx], item.event))
+                        continue;
+                }
+                out.push(item.event);
+            }
+            else {
+                if (item.stackHeight === undefined)
+                    pumpTargets.length = 0;
+                else
+                    while (pumpTargets.length) {
+                        const last = pumpTargets[pumpTargets.length - 1];
+                        if (last.outerIdx !== item.outerIdx || (last.stackHeight !== undefined && last.stackHeight >= item.stackHeight))
+                            pumpTargets.pop();
+                        else
+                            break;
+                    }
+                out.push(item.event);
+                pumpTargets.push({ outerIdx: item.outerIdx, stackHeight: item.stackHeight, resultIdx: out.length - 1, consumed: false });
+            }
+            continue;
+        }
+        if (item.isEventCpi && isDlmmEvent(item.event)) {
             let merged = false;
             for (let i = dlmmTargets.length - 1; i >= 0; i--) {
                 const target = dlmmTargets[i];
@@ -403,7 +452,7 @@ function parseOuterAndInnerInstructions(message, meta, signature, slot, txIndex,
                 outerIdx,
                 innerIdx: null,
                 stackHeight: 1,
-                isDlmmEventCpi: false,
+                isEventCpi: false,
                 event: ev,
             });
     }
@@ -426,7 +475,7 @@ function parseOuterAndInnerInstructions(message, meta, signature, slot, txIndex,
                     outerIdx: group.index,
                     innerIdx,
                     stackHeight: ix.stackHeight,
-                    isDlmmEventCpi: isDlmmEventCpi(programId, data),
+                    isEventCpi: isEventCpi(programId, data),
                     event: ev,
                 });
         }
@@ -441,8 +490,36 @@ function recentBlockhashBytes(recentBlockhash) {
         return undefined;
     }
 }
-function detectPumpfunCreateInLogs(logMessages, _signature, _slot, _txIndex, _blockTimeUs, _grpcRecvUs, _recentBlockhash) {
-    return logMessages.some((log) => log.includes("Program data: G3KpTd7rY3Y"));
+function detectPumpfunCreateInLogs(logMessages, signature, slot, txIndex, blockTimeUs, grpcRecvUs, recentBlockhash) {
+    const stack = [];
+    for (const log of logMessages) {
+        const invoke = (0, optimized_matcher_js_1.parseInvokeInfo)(log);
+        if (invoke && log === `Program ${invoke.programId} invoke [${invoke.depth}]`) {
+            stack.length = Math.min(stack.length, invoke.depth - 1);
+            stack.push(invoke.programId);
+            continue;
+        }
+        // The last base64 character of the discriminator also contains payload bits.
+        if (stack[stack.length - 1] === program_ids_js_1.PUMPFUN_PROGRAM_ID &&
+            log.startsWith("Program data: G3KpTd7rY3")) {
+            const encoded = log.slice("Program data: ".length);
+            if (Buffer.from(encoded, "base64").toString("base64") === encoded) {
+                // Ignore the caller's output filter: a real create still classifies buys
+                // when Create events are excluded. Decode only rare create candidates.
+                const event = (0, optimized_matcher_js_1.parseLogOptimizedWithProgramId)(log, signature, slot, txIndex, blockTimeUs, grpcRecvUs, undefined, false, recentBlockhash, program_ids_js_1.PUMPFUN_PROGRAM_ID);
+                if (event && ("PumpFunCreate" in event || "PumpFunCreateV2" in event))
+                    return true;
+            }
+        }
+        const completed = (0, optimized_matcher_js_1.parseProgramCompleteInfo)(log);
+        if (completed && (log === `Program ${completed} success` ||
+            log.startsWith(`Program ${completed} failed: `))) {
+            const index = stack.lastIndexOf(completed);
+            if (index >= 0)
+                stack.length = index;
+        }
+    }
+    return false;
 }
 function applyRpcFills(events, msg, meta) {
     const resolver = (0, rpc_invoke_map_js_1.getAccountKeyResolver)(msg, meta);

package/dist/shredstream/alt_cache.d.ts

@@ -0,0 +1,26 @@
+import type { AddressLookupTableAccount, Connection } from "@solana/web3.js";
+import type { ShredWasmTx } from "./instruction_parse.js";
+/** Bounded ALT cache. resolve() only reads memory; its misses are refreshed by a timer. */
+export declare class AddressLookupTableCache {
+    private readonly connection?;
+    private readonly refreshIntervalMs;
+    private static readonly CAPACITY;
+    private readonly tables;
+    private readonly pending;
+    private timer?;
+    private refreshing;
+    private generation;
+    private refreshOffset;
+    private failures;
+    constructor(connection?: Connection | undefined, initial?: readonly AddressLookupTableAccount[], refreshIntervalMs?: number);
+    get refreshFailures(): number;
+    private store;
+    private schedule;
+    /** null means this transaction is unresolved; callers must skip it, never emit guessed keys. */
+    resolve(tx: ShredWasmTx): string[] | null;
+    /** Explicit pre-subscription network operation, batched to the RPC's 100-account limit. */
+    preload(addresses: readonly string[]): Promise<void>;
+    start(): void;
+    stop(): void;
+    private refresh;
+}

package/dist/shredstream/alt_cache.js

@@ -0,0 +1,138 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AddressLookupTableCache = void 0;
+const alt_lookup_js_1 = require("./alt_lookup.js");
+/** Bounded ALT cache. resolve() only reads memory; its misses are refreshed by a timer. */
+class AddressLookupTableCache {
+    connection;
+    refreshIntervalMs;
+    static CAPACITY = 2048;
+    tables = new Map();
+    pending = new Set();
+    timer;
+    refreshing = false;
+    generation = 0;
+    refreshOffset = 0;
+    failures = 0;
+    constructor(connection, initial = [], refreshIntervalMs = 1000) {
+        this.connection = connection;
+        this.refreshIntervalMs = refreshIntervalMs;
+        if (!Number.isFinite(refreshIntervalMs) || refreshIntervalMs < 1) {
+            throw new RangeError("alt_refresh_interval_ms must be positive");
+        }
+        this.store(initial);
+    }
+    get refreshFailures() { return this.failures; }
+    store(tables) {
+        for (const table of tables) {
+            const key = table.key.toBase58();
+            // Encode each loaded pubkey once during refresh, never per transaction.
+            this.tables.set(key, table.state.addresses.map(address => address.toBase58()));
+            this.pending.delete(key);
+            if (this.tables.size > AddressLookupTableCache.CAPACITY) {
+                this.tables.delete(this.tables.keys().next().value);
+            }
+        }
+    }
+    schedule(key) {
+        if (this.pending.has(key))
+            return;
+        // Keep new misses eligible even when old tables remain unavailable forever.
+        if (this.pending.size >= AddressLookupTableCache.CAPACITY) {
+            this.pending.delete(this.pending.keys().next().value);
+        }
+        this.pending.add(key);
+    }
+    /** null means this transaction is unresolved; callers must skip it, never emit guessed keys. */
+    resolve(tx) {
+        if (tx.messageVersion !== "v0" || !tx.addressTableLookups?.length)
+            return tx.accounts;
+        let missing = false;
+        for (const lookup of tx.addressTableLookups) {
+            if (!this.tables.has(lookup.accountKey)) {
+                missing = true;
+                this.schedule(lookup.accountKey);
+            }
+        }
+        if (missing)
+            return null;
+        const keys = tx.accounts.slice();
+        // Runtime layout is all writable keys across tables, then all readonly keys.
+        for (const kind of ["writableIndexes", "readonlyIndexes"]) {
+            for (const lookup of tx.addressTableLookups) {
+                const table = this.tables.get(lookup.accountKey);
+                for (const index of lookup[kind]) {
+                    const key = table[index];
+                    if (key === undefined) {
+                        // A snapshot can predate an ALT extension. Refresh outside parsing.
+                        this.schedule(lookup.accountKey);
+                        return null;
+                    }
+                    keys.push(key);
+                }
+            }
+        }
+        return keys;
+    }
+    /** Explicit pre-subscription network operation, batched to the RPC's 100-account limit. */
+    async preload(addresses) {
+        if (!this.connection)
+            throw new Error("ALT preloading requires config.connection");
+        const unique = [...new Set(addresses)];
+        for (let start = 0; start < unique.length; start += 100) {
+            this.store((await (0, alt_lookup_js_1.loadAddressLookupTableAccounts)(this.connection, unique.slice(start, start + 100))).values());
+        }
+    }
+    start() {
+        if (!this.connection || this.timer)
+            return;
+        const generation = ++this.generation;
+        this.timer = setInterval(() => { void this.refresh(generation); }, this.refreshIntervalMs);
+        this.timer.unref?.();
+    }
+    stop() {
+        if (this.timer)
+            clearInterval(this.timer);
+        this.timer = undefined;
+        this.generation++;
+    }
+    async refresh(generation) {
+        if (!this.connection || this.refreshing)
+            return;
+        // Reserve a share of each batch for existing snapshots under a full miss queue.
+        const pendingLimit = 100 - Math.min(25, this.tables.size);
+        const keys = [...this.pending].slice(0, pendingLimit);
+        // Rotate unresolved misses too; absent tables must not starve the rest of the queue.
+        for (const key of keys) {
+            this.pending.delete(key);
+            this.pending.add(key);
+        }
+        // Rotate cached snapshots as well, so existing tables can acquire appended addresses.
+        const cached = [...this.tables.keys()];
+        if (cached.length) {
+            let visited = 0;
+            while (visited < cached.length && keys.length < 100) {
+                const key = cached[(this.refreshOffset + visited) % cached.length];
+                visited++;
+                if (!keys.includes(key))
+                    keys.push(key);
+            }
+            this.refreshOffset = (this.refreshOffset + visited) % cached.length;
+        }
+        if (!keys.length)
+            return;
+        this.refreshing = true;
+        try {
+            const tables = await (0, alt_lookup_js_1.loadAddressLookupTableAccounts)(this.connection, keys);
+            if (generation === this.generation)
+                this.store(tables.values());
+        }
+        catch {
+            this.failures++;
+        }
+        finally {
+            this.refreshing = false;
+        }
+    }
+}
+exports.AddressLookupTableCache = AddressLookupTableCache;

package/dist/shredstream/client.d.ts

@@ -7,6 +7,8 @@ export type ShredStreamReceiveStats = {
     entryDecodeFailures: number;
     transactionsDecoded: number;
     dexEventsQueued: number;
+    /** V0 transactions skipped because a complete cached ALT snapshot was unavailable. */
+    altCacheMissTransactions: number;
 };
 /** 有界 FIFO 队列（容量与 Rust `ArrayQueue::new(100_000)` 一致；`clone()` 共享底层缓冲，同 `Arc<ArrayQueue>`） */
 export declare class ShredEventQueue {
@@ -25,9 +27,11 @@ export declare class ShredStreamClient {
     private readonly endpoint;
     private readonly config;
     private readonly ServiceClient;
+    private lifecycleTail;
     private loopAbort;
     private loopPromise;
     private activeCall;
+    private readonly altCache;
     private receiveStats;
     private constructor();
     static connect(endpoint: string): Promise<ShredStreamClient>;
@@ -40,6 +44,10 @@ export declare class ShredStreamClient {
     clone(): ShredStreamClient;
     /** 当前订阅周期内 gRPC Entry 条数、解码失败次数、解码出的交易数、入队 DexEvent 数 */
     getReceiveStats(): Readonly<ShredStreamReceiveStats>;
+    /** Prewarm required ALTs before subscribe(); this explicit call may perform RPC. */
+    preloadAddressLookupTables(addresses: readonly string[]): Promise<void>;
+    /** Background refresh failures; cache misses are reported separately in receive stats. */
+    getAltRefreshFailures(): number;
     /**
      * 与 Rust `new_with_config` 中 `ShredstreamProxyClient::connect_with_config(endpoint, &config)` 一致：
      * `connection_timeout_ms` / `request_timeout_ms` / `max_decoding_message_size` 见 `shredstream/proto/mod.rs`。
@@ -54,12 +62,12 @@ export declare class ShredStreamClient {
     subscribeWithFilter(eventTypeFilter?: EventTypeFilter): Promise<ShredEventQueue>;
     /** 停止订阅并中止当前流 */
     stop(): Promise<void>;
+    private serializeLifecycle;
+    private stopUnlocked;
     private runReconnectLoop;
     /** 与 Rust `stream_events` + `connect_with_config`（tonic Endpoint / Grpc 消息上限）一致 */
     private streamOnce;
     private processEntryMessage;
-    /** 无 RPC：仅用静态账户表 */
+    /** Synchronous parsing: static keys or complete prewarmed ALT snapshots only. */
     private processEntryMessageSync;
-    /** 拉取 ALT 后完整账户表解析 */
-    private processEntryMessageWithAlt;
 }

package/dist/shredstream/client.js

@@ -43,7 +43,7 @@ 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 alt_cache_js_1 = require("./alt_cache.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");
@@ -79,8 +79,18 @@ function grpcCredentialsForEndpoint(endpoint) {
     }
     return grpc.credentials.createInsecure();
 }
-function sleepMs(ms) {
-    return new Promise((r) => setTimeout(r, ms));
+function sleepMs(ms, signal) {
+    if (signal.aborted)
+        return Promise.resolve();
+    return new Promise((resolve) => {
+        const finish = () => {
+            clearTimeout(timer);
+            signal.removeEventListener("abort", finish);
+            resolve();
+        };
+        const timer = setTimeout(finish, ms);
+        signal.addEventListener("abort", finish, { once: true });
+    });
 }
 function shredDebugEnabled() {
     const v = process.env.SHREDSTREAM_DEBUG;
@@ -127,18 +137,22 @@ class ShredStreamClient {
     endpoint;
     config;
     ServiceClient;
+    lifecycleTail = Promise.resolve();
     loopAbort = null;
     loopPromise = null;
     activeCall = null;
+    altCache;
     receiveStats = {
         entryMessagesReceived: 0,
         entryDecodeFailures: 0,
         transactionsDecoded: 0,
         dexEventsQueued: 0,
+        altCacheMissTransactions: 0,
     };
     constructor(endpoint, config) {
         this.endpoint = endpoint;
         this.config = config;
+        this.altCache = new alt_cache_js_1.AddressLookupTableCache(config.connection, config.address_lookup_tables, config.alt_refresh_interval_ms);
         const root = loadProtoDefinition();
         const shred = root.shredstream;
         this.ServiceClient = shred.ShredstreamProxy;
@@ -167,6 +181,12 @@ class ShredStreamClient {
     getReceiveStats() {
         return { ...this.receiveStats };
     }
+    /** Prewarm required ALTs before subscribe(); this explicit call may perform RPC. */
+    async preloadAddressLookupTables(addresses) {
+        await this.altCache.preload(addresses);
+    }
+    /** Background refresh failures; cache misses are reported separately in receive stats. */
+    getAltRefreshFailures() { return this.altCache.refreshFailures; }
     /**
      * 与 Rust `new_with_config` 中 `ShredstreamProxyClient::connect_with_config(endpoint, &config)` 一致：
      * `connection_timeout_ms` / `request_timeout_ms` / `max_decoding_message_size` 见 `shredstream/proto/mod.rs`。
@@ -195,19 +215,27 @@ class ShredStreamClient {
      * 重连循环使用订阅时刻的配置快照（与 Rust 在 `tokio::spawn` 前 `config.clone()` 一致）。
      */
     async subscribe(eventTypeFilter) {
-        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, eventTypeFilter);
-        return queue;
+        return this.serializeLifecycle(async () => {
+            await this.stopUnlocked();
+            this.receiveStats = {
+                entryMessagesReceived: 0,
+                entryDecodeFailures: 0,
+                transactionsDecoded: 0,
+                dexEventsQueued: 0,
+                altCacheMissTransactions: 0,
+            };
+            const queue = new ShredEventQueue();
+            const ac = new AbortController();
+            this.loopAbort = ac;
+            const configSnapshot = { ...this.config };
+            this.altCache.start();
+            this.loopPromise = this.runReconnectLoop(queue, ac.signal, configSnapshot, eventTypeFilter)
+                .finally(() => {
+                if (this.loopAbort === ac)
+                    this.altCache.stop();
+            });
+            return queue;
+        });
     }
     /** 与 Rust `subscribe_with_filter` 对齐：在解析热路径按事件类型预过滤。 */
     async subscribeWithFilter(eventTypeFilter) {
@@ -215,6 +243,15 @@ class ShredStreamClient {
     }
     /** 停止订阅并中止当前流 */
     async stop() {
+        await this.serializeLifecycle(() => this.stopUnlocked());
+    }
+    serializeLifecycle(operation) {
+        const result = this.lifecycleTail.then(operation);
+        this.lifecycleTail = result.then(() => undefined, () => undefined);
+        return result;
+    }
+    async stopUnlocked() {
+        this.altCache.stop();
         this.loopAbort?.abort();
         this.loopAbort = null;
         this.activeCall?.cancel();
@@ -244,7 +281,7 @@ class ShredStreamClient {
                     break;
                 const msg = e instanceof Error ? e.message : String(e);
                 console.error(`ShredStream error: ${msg} - retry in ${delay}ms`);
-                await sleepMs(delay);
+                await sleepMs(delay, signal);
                 if (signal.aborted)
                     break;
                 delay = Math.min(delay * 2, 60_000);
@@ -268,23 +305,31 @@ class ShredStreamClient {
                 if (settled)
                     return;
                 settled = true;
+                signal.removeEventListener("abort", abort);
+                if (this.activeCall === call)
+                    this.activeCall = null;
+                client.close();
                 fn();
             };
+            const abort = () => {
+                call.cancel();
+                finish(resolve);
+            };
             const call = client.subscribeEntries({}, new grpc.Metadata());
             this.activeCall = call;
+            signal.addEventListener("abort", abort, { once: true });
             console.info("ShredStream connected, receiving entries...");
             call.on("data", (entry) => {
-                if (signal.aborted)
+                if (signal.aborted || settled)
                     return;
                 try {
-                    void this.processEntryMessage(entry, queue, eventTypeFilter);
+                    this.processEntryMessage(entry, queue, eventTypeFilter);
                 }
                 catch (err) {
                     console.error("processEntryMessage:", err);
                 }
             });
             call.on("error", (err) => {
-                client.close();
                 if (signal.aborted || err.code === grpc.status.CANCELLED) {
                     finish(() => resolve());
                     return;
@@ -293,12 +338,11 @@ class ShredStreamClient {
                 finish(() => reject(err));
             });
             call.on("end", () => {
-                client.close();
                 finish(() => resolve());
             });
         });
     }
-    async processEntryMessage(entry, queue, eventTypeFilter) {
+    processEntryMessage(entry, queue, eventTypeFilter) {
         this.receiveStats.entryMessagesReceived += 1;
         const recvUs = (0, unified_parser_js_1.nowUs)();
         const slotNum = toSlotNumber(entry.slot);
@@ -314,20 +358,9 @@ class ShredStreamClient {
             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, eventTypeFilter);
-            }
-            catch (e) {
-                console.warn(`[shredstream] ALT/RPC 解析失败 slot=${slotNum}:`, e);
-                this.processEntryMessageSync(decoded, slotNum, recvUs, queue, bytes.length, eventTypeFilter);
-            }
-            return;
-        }
         this.processEntryMessageSync(decoded, slotNum, recvUs, queue, bytes.length, eventTypeFilter);
     }
-    /** 无 RPC：仅用静态账户表 */
+    /** Synchronous parsing: static keys or complete prewarmed ALT snapshots only. */
     processEntryMessageSync(decoded, slotNum, recvUs, queue, entriesBytesLen, eventTypeFilter) {
         let txTotal = 0;
         let evTotal = 0;
@@ -341,44 +374,15 @@ class ShredStreamClient {
                 const txIndex = globalTxIndex++;
                 if (!tx?.signature)
                     continue;
-                const events = (0, instruction_parse_js_1.dexEventsFromShredWasmTx)(tx, slotNum, txIndex, recvUs, eventTypeFilter);
-                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, eventTypeFilter) {
-        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)
+                const useCache = this.config.connection || this.config.address_lookup_tables;
+                const fullKeys = useCache ? this.altCache.resolve(tx) : tx.accounts;
+                if (!fullKeys) {
+                    this.receiveStats.altCacheMissTransactions++;
                     continue;
-                const fullKeys = (0, alt_lookup_js_1.fullAccountKeyStringsFromShredTx)(tx, altMap);
-                const events = (0, instruction_parse_js_1.dexEventsFromShredWasmTxWithFullKeys)(tx, fullKeys, slotNum, txIndex, recvUs, eventTypeFilter);
+                }
+                const events = useCache
+                    ? (0, instruction_parse_js_1.dexEventsFromShredWasmTxWithFullKeys)(tx, fullKeys, slotNum, txIndex, recvUs, eventTypeFilter)
+                    : (0, instruction_parse_js_1.dexEventsFromShredWasmTx)(tx, slotNum, txIndex, recvUs, eventTypeFilter);
                 evTotal += events.length;
                 for (const ev of events) {
                     setGrpcRecvUsMut(ev, recvUs);
@@ -389,7 +393,7 @@ class ShredStreamClient {
         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}`);
+            console.info(`[shredstream] slot=${slotNum} entries_bytes=${entriesBytesLen} solana_entries=${decoded.length} txs=${txTotal} dex_events=${evTotal} (static_accounts_only)`);
         }
     }
 }

package/dist/shredstream/config.d.ts

@@ -1,4 +1,4 @@
-import type { Connection } from "@solana/web3.js";
+import type { AddressLookupTableAccount, Connection } from "@solana/web3.js";
 /**
  * 与 Rust `sol-parser-sdk/src/shredstream/config.rs` 字段一一对应。
  *
@@ -7,7 +7,7 @@ import type { Connection } from "@solana/web3.js";
  * （`request_timeout_ms` 保留与 Rust `config.rs` 一致，流式路径不填 deadline）。
  * `reconnect_delay_ms` / `max_reconnect_attempts` 由 `client.rs` 重连循环使用。
  *
- * **TS 扩展**：`connection` 用于拉取链上 ALT，补全 V0 交易账户表以解析外层指令（主网 Pump 等必需）。
+ * **TS 扩展**：ALT 使用预热快照和独立刷新任务；解析热路径不发送 RPC。
  */
 export interface ShredStreamConfig {
     /** 连接超时（毫秒）→ tonic `Endpoint::connect_timeout` / gRPC `waitForReady` */
@@ -20,8 +20,12 @@ export interface ShredStreamConfig {
     reconnect_delay_ms: number;
     /** 最大重连次数（0 表示无限重连） */
     max_reconnect_attempts: number;
-    /** 可选：主网 RPC，用于解析 V0 地址查找表（ALT） */
+    /** 可选：只供显式预热及后台 ALT 刷新使用，解析热路径不发送 RPC。 */
     connection?: Connection;
+    /** 可选：订阅前已加载的 ALT 快照；未命中时跳过整笔 V0 交易并累计计数。 */
+    address_lookup_tables?: readonly AddressLookupTableAccount[];
+    /** 独立 ALT 刷新间隔（毫秒），默认 1000；最多一个刷新请求在途。 */
+    alt_refresh_interval_ms?: number;
 }
 export declare function defaultShredStreamConfig(): ShredStreamConfig;
 /** 低延迟：更短超时与重连间隔 */