sol-parser-sdk 0.5.17 → 0.5.18

package/dist/logs/pump_amm.js

@@ -19,6 +19,7 @@ function bnI64(v) {
 const ZP = (0, dex_event_js_1.defaultPubkey)();
 function emptyTradeTail() {
     return {
+        creator_fee_unclaimed: 0n,
         cashback_fee_basis_points: 0n,
         cashback: 0n,
         buyback_fee_basis_points: 0n,
@@ -63,6 +64,9 @@ function parseTradeTail(data) {
         tail.holder_rewards_bps = bn64((0, binary_js_1.readU64LE)(data, 57));
         tail.holder_rewards = bn64((0, binary_js_1.readU64LE)(data, 65));
     }
+    if (data.length > 73 && data.length < 81)
+        return null;
+    tail.creator_fee_unclaimed = bn64((0, binary_js_1.readU64LE)(data, 73));
     return tail;
 }
 function readStrictBorshString(data, offset) {
@@ -198,6 +202,7 @@ function parseBuyFromData(data, metadata) {
         base_supply: tail.base_supply,
         holder_rewards_bps: tail.holder_rewards_bps,
         holder_rewards: tail.holder_rewards,
+        creator_fee_unclaimed: tail.creator_fee_unclaimed,
         is_pump_pool: false,
         base_mint: ZP,
         quote_mint: ZP,
@@ -298,6 +303,7 @@ function parseSellFromData(data, metadata) {
         base_supply: tail.base_supply,
         holder_rewards_bps: tail.holder_rewards_bps,
         holder_rewards: tail.holder_rewards,
+        creator_fee_unclaimed: tail.creator_fee_unclaimed,
         is_pump_pool: false,
         base_mint: ZP,
         quote_mint: ZP,
@@ -392,7 +398,7 @@ function parseCreatePoolFromData(data, metadata) {
     return { PumpSwapCreatePool: ev };
 }
 function parseAddLiquidityFromData(data, metadata) {
-    const REQUIRED = 10 * 8 + 5 * 32;
+    const REQUIRED = 11 * 8 + 5 * 32;
     if (data.length < REQUIRED)
         return null;
     let o = 0;
@@ -449,7 +455,7 @@ function parseAddLiquidityFromData(data, metadata) {
     return { PumpSwapLiquidityAdded: ev };
 }
 function parseRemoveLiquidityFromData(data, metadata) {
-    const REQUIRED = 10 * 8 + 5 * 32;
+    const REQUIRED = 11 * 8 + 5 * 32;
     if (data.length < REQUIRED)
         return null;
     let o = 0;

package/dist/logs/pump_upgrade.d.ts

@@ -0,0 +1,68 @@
+import type { DexEvent } from "../core/dex_event.js";
+import type { EventMetadata } from "../core/metadata.js";
+export interface PumpFunPostCompleteBuyEvent {
+    metadata: EventMetadata;
+    user: string;
+    mint: string;
+    bonding_curve: string;
+    quote_mint: string;
+    timestamp: bigint;
+    base_out: bigint;
+    quote_in: bigint;
+    fee_basis_points: bigint;
+    fee: bigint;
+    creator_fee_basis_points: bigint;
+    creator_fee: bigint;
+    buyback_fee: bigint;
+    pool_base_reserves_before: bigint;
+    pool_quote_reserves_before: bigint;
+    pool_base_reserves_after: bigint;
+    pool_quote_reserves_after: bigint;
+}
+export interface PumpFunSweepBondingCurveFeeEvent {
+    metadata: EventMetadata;
+    timestamp: bigint;
+    mint: string;
+    bonding_curve: string;
+    quote_mint: string;
+    recipient: string;
+    amount: bigint;
+    bucket: number;
+}
+export interface PumpFunCompleteEvent {
+    metadata: EventMetadata;
+    user: string;
+    mint: string;
+    bonding_curve: string;
+    timestamp: bigint;
+    quote_mint: string;
+}
+export interface PumpSwapSweepPoolFeeEvent {
+    metadata: EventMetadata;
+    timestamp: bigint;
+    pool: string;
+    base_mint: string;
+    quote_mint: string;
+    recipient: string;
+    payer: string;
+    amount: bigint;
+    bucket: number;
+}
+export declare function pumpUpgradeEventType(disc: bigint, programId?: string): "PumpFunPostCompleteBuy" | "PumpFunSweepBondingCurveFee" | "PumpFunComplete" | "PumpSwapSweepPoolFee" | null;
+export declare function parsePumpUpgradeEvent(disc: bigint, data: Uint8Array, metadata: EventMetadata, programId?: string): DexEvent | null;
+export interface PumpMultiHopIntent {
+    user: string;
+    inputAccount: string;
+    outputAccount: string;
+    amountIn: bigint;
+    minAmountOut: bigint;
+    hops: {
+        baseMint: string;
+        quoteMint: string;
+        venue: string;
+        baseVault: string;
+        quoteVault: string;
+    }[];
+}
+/** Intent amounts are limits, not execution. Each hop emits its own actual trade. */
+export declare function decodePumpMultiHopIntent(program: string, data: Uint8Array, accounts: readonly string[]): PumpMultiHopIntent | null;

package/dist/logs/pump_upgrade.js

@@ -0,0 +1,128 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pumpUpgradeEventType = pumpUpgradeEventType;
+exports.parsePumpUpgradeEvent = parsePumpUpgradeEvent;
+exports.decodePumpMultiHopIntent = decodePumpMultiHopIntent;
+const binary_js_1 = require("../util/binary.js");
+function pumpUpgradeEventType(disc, programId) {
+    if (disc === 18146529233607700591n &&
+        (!programId || programId === "6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P"))
+        return "PumpFunPostCompleteBuy";
+    if (disc === 3118876958563052404n &&
+        (!programId || programId === "6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P"))
+        return "PumpFunSweepBondingCurveFee";
+    if (disc === 619296439455019615n &&
+        (!programId || programId === "6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P"))
+        return "PumpFunComplete";
+    if (disc === 11927646055507993730n &&
+        (!programId || programId === "pAMMBay6oceH9fJKBRHGP5D4bD4sWpmSwMn52FMfXEA"))
+        return "PumpSwapSweepPoolFee";
+    return null;
+}
+function parsePumpUpgradeEvent(disc, data, metadata, programId) {
+    const type = pumpUpgradeEventType(disc, programId);
+    if (type === "PumpFunPostCompleteBuy") {
+        if (data.length != 224)
+            return null;
+        return {
+            PumpFunPostCompleteBuy: {
+                metadata,
+                user: (0, binary_js_1.readPubkey)(data, 0),
+                mint: (0, binary_js_1.readPubkey)(data, 32),
+                bonding_curve: (0, binary_js_1.readPubkey)(data, 64),
+                quote_mint: (0, binary_js_1.readPubkey)(data, 96),
+                timestamp: (0, binary_js_1.readI64LE)(data, 128),
+                base_out: (0, binary_js_1.readU64LE)(data, 136),
+                quote_in: (0, binary_js_1.readU64LE)(data, 144),
+                fee_basis_points: (0, binary_js_1.readU64LE)(data, 152),
+                fee: (0, binary_js_1.readU64LE)(data, 160),
+                creator_fee_basis_points: (0, binary_js_1.readU64LE)(data, 168),
+                creator_fee: (0, binary_js_1.readU64LE)(data, 176),
+                buyback_fee: (0, binary_js_1.readU64LE)(data, 184),
+                pool_base_reserves_before: (0, binary_js_1.readU64LE)(data, 192),
+                pool_quote_reserves_before: (0, binary_js_1.readU64LE)(data, 200),
+                pool_base_reserves_after: (0, binary_js_1.readU64LE)(data, 208),
+                pool_quote_reserves_after: (0, binary_js_1.readU64LE)(data, 216),
+            },
+        };
+    }
+    if (type === "PumpFunSweepBondingCurveFee") {
+        if (data.length != 145)
+            return null;
+        return {
+            PumpFunSweepBondingCurveFee: {
+                metadata,
+                timestamp: (0, binary_js_1.readI64LE)(data, 0),
+                mint: (0, binary_js_1.readPubkey)(data, 8),
+                bonding_curve: (0, binary_js_1.readPubkey)(data, 40),
+                quote_mint: (0, binary_js_1.readPubkey)(data, 72),
+                recipient: (0, binary_js_1.readPubkey)(data, 104),
+                amount: (0, binary_js_1.readU64LE)(data, 136),
+                bucket: data[144],
+            },
+        };
+    }
+    if (type === "PumpFunComplete") {
+        if (data.length != 136 && data.length != 104)
+            return null;
+        return {
+            PumpFunComplete: {
+                metadata,
+                user: (0, binary_js_1.readPubkey)(data, 0),
+                mint: (0, binary_js_1.readPubkey)(data, 32),
+                bonding_curve: (0, binary_js_1.readPubkey)(data, 64),
+                timestamp: (0, binary_js_1.readI64LE)(data, 96),
+                quote_mint: data.length === 104
+                    ? "So11111111111111111111111111111111111111112"
+                    : (0, binary_js_1.readPubkey)(data, 104),
+            },
+        };
+    }
+    if (type === "PumpSwapSweepPoolFee") {
+        if (data.length != 177)
+            return null;
+        return {
+            PumpSwapSweepPoolFee: {
+                metadata,
+                timestamp: (0, binary_js_1.readI64LE)(data, 0),
+                pool: (0, binary_js_1.readPubkey)(data, 8),
+                base_mint: (0, binary_js_1.readPubkey)(data, 40),
+                quote_mint: (0, binary_js_1.readPubkey)(data, 72),
+                recipient: (0, binary_js_1.readPubkey)(data, 104),
+                payer: (0, binary_js_1.readPubkey)(data, 136),
+                amount: (0, binary_js_1.readU64LE)(data, 168),
+                bucket: data[176],
+            },
+        };
+    }
+    return null;
+}
+/** Intent amounts are limits, not execution. Each hop emits its own actual trade. */
+function decodePumpMultiHopIntent(program, data, accounts) {
+    if (program !== "pAMMBay6oceH9fJKBRHGP5D4bD4sWpmSwMn52FMfXEA" ||
+        data.length !== 24 ||
+        (0, binary_js_1.readU64LE)(data, 0) !== 10696039120939607083n ||
+        accounts.length < 21 ||
+        (accounts.length - 16) % 5 !== 0)
+        return null;
+    const amountIn = (0, binary_js_1.readU64LE)(data, 8), minAmountOut = (0, binary_js_1.readU64LE)(data, 16);
+    if (!amountIn || !minAmountOut)
+        return null;
+    const hops = [];
+    for (let i = 16; i < accounts.length; i += 5)
+        hops.push({
+            baseMint: accounts[i],
+            quoteMint: accounts[i + 1],
+            venue: accounts[i + 2],
+            baseVault: accounts[i + 3],
+            quoteVault: accounts[i + 4],
+        });
+    return {
+        user: accounts[0],
+        inputAccount: accounts[1],
+        outputAccount: accounts[2],
+        amountIn,
+        minAmountOut,
+        hops,
+    };
+}

package/dist/logs/raydium_cpmm.js

@@ -12,9 +12,8 @@ function bn64(v) {
 }
 /** Current Anchor `SwapEvent` payload (the 8-byte event discriminator is removed by the caller). */
 function parseSwapEventFromData(data, metadata) {
-    // pool_id + six u64 fields + base_input. Newer IDLs append mint/fee fields,
-    // which remain wire-compatible with this stable prefix.
-    if (data.length < 32 + (6 * 8) + 1)
+    // Accept the complete legacy prefix or the complete current mint/fee suffix.
+    if (data.length < 81 || (data.length > 81 && data.length < 162) || data[80] > 1 || (data.length >= 162 && data[161] > 1))
         return null;
     let o = 0;
     const pool_id = (0, binary_js_1.readPubkey)(data, o);
@@ -40,6 +39,11 @@ function parseSwapEventFromData(data, metadata) {
         base_input == null)
         return null;
     const ev = {
+        input_mint: data.length >= 162 ? (0, binary_js_1.readPubkey)(data, 81) : undefined,
+        output_mint: data.length >= 162 ? (0, binary_js_1.readPubkey)(data, 113) : undefined,
+        trade_fee: data.length >= 162 ? (0, binary_js_1.readU64LE)(data, 145) : undefined,
+        creator_fee: data.length >= 162 ? (0, binary_js_1.readU64LE)(data, 153) : undefined,
+        creator_fee_on_input: data.length >= 162 ? data[161] !== 0 : undefined,
         metadata,
         pool_id,
         input_vault_before,

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;
 }