sol-parser-sdk 0.5.15 → 0.5.16

package/NATIVE_PUMPFUN_SETTLEMENT_EVIDENCE_20261004.json

@@ -0,0 +1,70 @@
+{
+  "date": "2026-10-04",
+  "overall_alignment_complete": false,
+  "broadcasts": 0,
+  "hot_path_rpc_calls": 0,
+  "rust_baseline": {
+    "trade": "5.0.6",
+    "parser": "0.7.7"
+  },
+  "current_pumpfun_fee_oracle": {
+    "package": "@pump-fun/pump-sdk",
+    "version": "2.0.0",
+    "vectors_per_language": 240,
+    "runtime_dependency": false
+  },
+  "simulations": {
+    "direct_sol": {
+      "wire_bytes": 1044,
+      "err": null,
+      "evidence": "examples/fixtures/pumpfun_direct_sol_simulations_20261004.json"
+    },
+    "funded_wsol": {
+      "wire_bytes": 1238,
+      "wire_sha256": "76b18c71a930080a4c937483ed1ab670e7ade2188cfef6cf1d00ec8a1538adfd",
+      "err": null,
+      "actual_wsol_debit": "10000",
+      "verified_asset_payment": true,
+      "evidence": "examples/fixtures/pumpfun_settled_funded_wsol_evidence_20261004.json",
+      "cross_language_wire_match": [
+        "go",
+        "nodejs",
+        "python"
+      ]
+    }
+  },
+  "verification": {
+    "full_suites_before_final_added_regressions": {
+      "trade_nodejs": 3326,
+      "parser_nodejs": 213,
+      "parser_nodejs_skipped": 8,
+      "trade_python": 3406,
+      "parser_python": 199,
+      "go_trade": "go test ./... passed",
+      "go_parser": "go test ./... passed"
+    },
+    "final_targeted": {
+      "trade_nodejs": 8,
+      "trade_python": 12,
+      "parser_nodejs_simulation": 47,
+      "parser_python_simulation": 49,
+      "go_parser_failed_intent_and_mainnet_corpus": "passed"
+    },
+    "go_vet": "both passed",
+    "go_race": "both full suites passed",
+    "node_trade_types_and_build": "passed",
+    "node_trade_example_types": "passed",
+    "node_parser_types": "passed",
+    "installed_wheel_verified_wire": "passed",
+    "installed_npm_public_api_verified_wire": "passed",
+    "six_repo_diff_check": "passed"
+  },
+  "not_verified": [
+    "current PumpFun funded sell simulation",
+    "native-quote PumpFun multi-hop settlement (explicitly rejected)",
+    "non-native USDC/stock PumpFun mainnet simulations",
+    "legacy low-level builder current-chain compatibility",
+    "SWQOS online V1 broadcast compatibility",
+    "full Rust public API/field alignment matrix and remaining lifecycle acceptance"
+  ]
+}

package/README.md

@@ -44,6 +44,12 @@
 
 ## Release notes
 
+### v0.5.16
+
+- Adds native gRPC lifecycle and block metadata support, instruction-level route analysis and StonkFun registry/snapshot examples.
+- Improves exact metadata serialization, account matching and wire transaction bounds validation.
+- Includes native alignment evidence and simulation route fixtures. These language releases do not yet implement the new CPMM creator-fee collection event API.
+
 ### v0.5.15
 
 - Syncs with Rust `sol-parser-sdk` **0.7.3**, including the current PumpFun, PumpSwap, Pump Fees, and Meteora DAMM v2 protocol surfaces.
@@ -90,7 +96,7 @@
 **From npm**
 
 ```bash
-npm install sol-parser-sdk@0.5.15
+npm install sol-parser-sdk@0.5.16
 ```
 
 **From source** (folder may be named `sol-parser-sdk-ts` in a monorepo)
@@ -328,3 +334,13 @@ npm run check:migration   # parity checks; needs build
 ## License
 
 MIT — https://github.com/0xfnzero/sol-parser-sdk-nodejs
+
+## Native alignment status
+
+See [NATIVE_ALIGNMENT.md](NATIVE_ALIGNMENT.md) for implemented native APIs, Rust golden tests, mainnet simulation evidence, examples, and remaining parity gaps. Full cross-language parity is still in progress.
+
+
+实时 parser → trade 接入使用 Yellowstone **gRPC**；见 [gRPC 缓存接入与三语言示例](examples/GRPC_CACHE.md)。此路径不使用 WebSocket，报价和构建热路径不调用 RPC。
+
+
+[本轮原生对齐 API 迁移](NATIVE_MIGRATION.md)（实施中，尚未发布）。

package/README_CN.md

@@ -44,6 +44,12 @@
 
 ## 发布说明
 
+### v0.5.16
+
+- Adds native gRPC lifecycle and block metadata support, instruction-level route analysis and StonkFun registry/snapshot examples.
+- Improves exact metadata serialization, account matching and wire transaction bounds validation.
+- Includes native alignment evidence and simulation route fixtures. These language releases do not yet implement the new CPMM creator-fee collection event API.
+
 ### v0.5.15
 
 - 对齐 Rust sol-parser-sdk **0.7.3**，覆盖当前 PumpFun、PumpSwap、Pump Fees 与 Meteora DAMM v2 协议字段。
@@ -90,7 +96,7 @@
 **npm**
 
 ```bash
-npm install sol-parser-sdk@0.5.15
+npm install sol-parser-sdk@0.5.16
 ```
 
 **源码**（monorepo 里目录可能是 `sol-parser-sdk-ts`）
@@ -321,3 +327,10 @@ npm run check:migration   # 对齐与校验，需先 build
 ## 许可证
 
 MIT — https://github.com/0xfnzero/sol-parser-sdk-nodejs
+
+## Native alignment status
+
+See [NATIVE_ALIGNMENT.md](NATIVE_ALIGNMENT.md) for implemented native APIs, Rust golden tests, mainnet simulation evidence, examples, and remaining parity gaps. Full cross-language parity is still in progress.
+
+
+[本轮原生对齐 API 迁移](NATIVE_MIGRATION.md)（实施中，尚未发布）。

package/dist/accounts/mod.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.rpcResolveUserWalletPubkey = exports.userWalletPubkeyForOnchainAccount = exports.hasDiscriminator = exports.isOrcaWhirlpoolsConfigAccount = exports.isOrcaFeeTierAccount = exports.isOrcaTickArrayAccount = exports.isOrcaPositionAccount = exports.isOrcaWhirlpoolAccount = exports.isRaydiumCpmmPoolStateAccount = exports.isRaydiumCpmmAmmConfigAccount = exports.isRaydiumClmmTickArrayStateAccount = exports.isRaydiumClmmPoolStateAccount = exports.isRaydiumClmmAmmConfigAccount = exports.parseOrcaWhirlpoolsConfig = exports.parseOrcaFeeTier = exports.parseOrcaTickArray = exports.parseOrcaPosition = exports.parseOrcaWhirlpool = exports.parseOrcaWhirlpoolAccount = exports.parseRaydiumCpmmPoolState = exports.parseRaydiumCpmmAmmConfig = exports.parseRaydiumCpmmAccount = exports.parseRaydiumClmmTickArrayState = exports.parseRaydiumClmmPoolState = exports.parseRaydiumClmmAmmConfig = exports.parseRaydiumClmmAccount = exports.isPoolAccount = exports.isGlobalConfigAccount = exports.parsePumpswapAccount = exports.parsePumpswapPool = exports.parsePumpswapGlobalConfig = exports.isPumpfunUserVolumeAccumulatorAccount = exports.isPumpfunGlobalVolumeAccumulatorAccount = exports.isPumpfunSharingConfigAccount = exports.isPumpfunFeeConfigAccount = exports.isPumpfunBondingCurveAccount = exports.isPumpfunGlobalAccount = exports.parsePumpfunAccount = exports.parsePumpfunUserVolumeAccumulator = exports.parsePumpfunGlobalVolumeAccumulator = exports.parsePumpfunSharingConfig = exports.parsePumpfunFeeConfig = exports.parsePumpfunBondingCurve = exports.parsePumpfunGlobal = exports.parseTokenAccount = exports.isNonceAccount = exports.parseNonceAccount = void 0;
 exports.parseAccountUnified = parseAccountUnified;
+const liquidity_snapshot_js_1 = require("../liquidity_snapshot.js");
 const types_js_1 = require("../grpc/types.js");
 const program_ids_js_1 = require("../instr/program_ids.js");
 const nonce_js_1 = require("./nonce.js");
@@ -86,6 +87,7 @@ const ACCOUNT_EVENT_TYPES = [
     "AccountOrcaTickArray",
     "AccountOrcaFeeTier",
     "AccountOrcaWhirlpoolsConfig",
+    "AccountLiquiditySnapshot",
 ];
 function filterParsedEvent(ev, eventTypeFilter) {
     if (!ev || !eventTypeFilter)
@@ -101,6 +103,11 @@ function parseAccountUnified(account, metadata, eventTypeFilter) {
         if (!shouldParse)
             return null;
     }
+    if (!eventTypeFilter || eventTypeFilter.shouldInclude('AccountLiquiditySnapshot')) {
+        const snapshot = (0, liquidity_snapshot_js_1.parseLiquidityAccount)(account, metadata);
+        if (snapshot)
+            return { LiquidityAccountSnapshot: snapshot };
+    }
     if (account.owner === program_ids_js_1.PUMPSWAP_PROGRAM_ID) {
         if (!eventTypeFilter ||
             eventTypeFilter.shouldInclude("AccountPumpSwapGlobalConfig") ||

package/dist/core/account_dispatcher_rpc.js

@@ -9,7 +9,27 @@ const account_fill_raydium_js_1 = require("./account_fill_raydium.js");
 const account_fill_orca_js_1 = require("./account_fill_orca.js");
 const account_fill_raydium_launchlab_js_1 = require("./account_fill_raydium_launchlab.js");
 const account_fill_meteora_js_1 = require("./account_fill_meteora.js");
-function tryFill(programId, programInvokes, message, meta, resolver, fn) {
+function tryFill(programId, programInvokes, message, meta, resolver, fn, anchor, unambiguous = false) {
+    if (anchor || unambiguous) {
+        const hasAnchor = anchor && anchor.pool && anchor.pool !== "11111111111111111111111111111111";
+        if (!hasAnchor && !unambiguous)
+            return;
+        let selected = null;
+        for (const invocation of programInvokes.get(programId) ?? []) {
+            const candidate = (0, rpc_invoke_map_js_1.makeInvokeAccountGetter)(resolver, invocation, message, meta);
+            if (!candidate || (hasAnchor && candidate(anchor.index) !== anchor.pool))
+                continue;
+            // One pool can be traded by multiple users within the same transaction.
+            // Without an invocation position, keep missing context instead of guessing.
+            if (selected &&
+                Array.from({ length: 18 }, (_, i) => i).some((i) => selected(i) !== candidate(i)))
+                return;
+            selected = candidate;
+        }
+        if (selected)
+            fn(selected);
+        return;
+    }
     const invoke = (0, rpc_invoke_map_js_1.findMaxAccountsInvoke)(programId, programInvokes, message, meta);
     if (!invoke)
         return;
@@ -93,7 +113,7 @@ function fillAccountsFromTransactionDataRpc(ev, message, meta, programInvokes, r
         tryFill(program_ids_js_1.RAYDIUM_CPMM_PROGRAM_ID, programInvokes, message, meta, resolver, (g) => (0, account_fill_raydium_js_1.fillRaydiumCpmmInitializeAccounts)(ev.RaydiumCpmmInitialize, g));
     }
     else if ("RaydiumAmmV4Swap" in ev) {
-        tryFill(program_ids_js_1.RAYDIUM_AMM_V4_PROGRAM_ID, programInvokes, message, meta, resolver, (g) => (0, account_fill_raydium_js_1.fillRaydiumAmmV4SwapAccounts)(ev.RaydiumAmmV4Swap, g));
+        tryFill(program_ids_js_1.RAYDIUM_AMM_V4_PROGRAM_ID, programInvokes, message, meta, resolver, (g) => (0, account_fill_raydium_js_1.fillRaydiumAmmV4SwapAccounts)(ev.RaydiumAmmV4Swap, g), { pool: ev.RaydiumAmmV4Swap.amm, index: 1 }, true);
     }
     else if ("RaydiumAmmV4Deposit" in ev) {
         tryFill(program_ids_js_1.RAYDIUM_AMM_V4_PROGRAM_ID, programInvokes, message, meta, resolver, (g) => (0, account_fill_raydium_js_1.fillRaydiumAmmV4DepositAccounts)(ev.RaydiumAmmV4Deposit, g));
@@ -147,9 +167,9 @@ function fillAccountsFromTransactionDataRpc(ev, message, meta, programInvokes, r
         tryFill(program_ids_js_1.METEORA_DLMM_PROGRAM_ID, programInvokes, message, meta, resolver, (g) => (0, account_fill_meteora_js_1.fillMeteoraDlmmRemoveLiquidityAccounts)(ev.MeteoraDlmmRemoveLiquidity, g));
     }
     else if ("RaydiumLaunchlabTrade" in ev) {
-        tryFill(program_ids_js_1.RAYDIUM_LAUNCHLAB_PROGRAM_ID, programInvokes, message, meta, resolver, (g) => (0, account_fill_raydium_launchlab_js_1.fillRaydiumLaunchlabTradeAccounts)(ev.RaydiumLaunchlabTrade, g));
+        tryFill(program_ids_js_1.RAYDIUM_LAUNCHLAB_PROGRAM_ID, programInvokes, message, meta, resolver, (g) => (0, account_fill_raydium_launchlab_js_1.fillRaydiumLaunchlabTradeAccounts)(ev.RaydiumLaunchlabTrade, g), { pool: ev.RaydiumLaunchlabTrade.pool_state, index: 4 });
     }
     else if ("RaydiumLaunchlabPoolCreate" in ev) {
-        tryFill(program_ids_js_1.RAYDIUM_LAUNCHLAB_PROGRAM_ID, programInvokes, message, meta, resolver, (g) => (0, account_fill_raydium_launchlab_js_1.fillRaydiumLaunchlabPoolCreateAccounts)(ev.RaydiumLaunchlabPoolCreate, g));
+        tryFill(program_ids_js_1.RAYDIUM_LAUNCHLAB_PROGRAM_ID, programInvokes, message, meta, resolver, (g) => (0, account_fill_raydium_launchlab_js_1.fillRaydiumLaunchlabPoolCreateAccounts)(ev.RaydiumLaunchlabPoolCreate, g), { pool: ev.RaydiumLaunchlabPoolCreate.pool_state, index: 5 });
     }
 }

package/dist/core/account_fill_raydium.js

@@ -86,9 +86,19 @@ function fillRaydiumCpmmInitializeAccounts(e, get) {
         e.pool = get(3);
 }
 function fillRaydiumAmmV4SwapAccounts(e, get) {
-    const zero = Z();
-    if (!e.amm || e.amm === zero)
+    const empty = (v) => !v || v === Z();
+    if (empty(e.amm))
         e.amm = get(1);
+    const modern = empty(get(8)) && !empty(get(7));
+    if (modern) {
+        for (const [field, index] of [['token_program', 0], ['amm_authority', 2], ['pool_coin_token_account', 3], ['pool_pc_token_account', 4], ['user_source_token_account', 5], ['user_destination_token_account', 6], ['user_source_owner', 7]]) {
+            if (empty(e[field]))
+                e[field] = get(index);
+        }
+    }
+    else if (empty(e.user_source_owner)) {
+        e.user_source_owner = empty(get(17)) ? get(16) : get(17);
+    }
 }
 function fillRaydiumAmmV4DepositAccounts(e, get) {
     const zero = Z();

package/dist/core/account_fill_raydium_launchlab.js

@@ -31,6 +31,12 @@ function fillRaydiumLaunchlabTradeAccounts(e, get) {
         e.base_token_program = get(11);
     if (!e.quote_token_program || e.quote_token_program === zero)
         e.quote_token_program = get(12);
+    if (!e.system_program || e.system_program === zero)
+        e.system_program = get(15);
+    if (!e.platform_associated_account || e.platform_associated_account === zero)
+        e.platform_associated_account = get(16);
+    if (!e.creator_associated_account || e.creator_associated_account === zero)
+        e.creator_associated_account = get(17);
 }
 function fillRaydiumLaunchlabPoolCreateAccounts(e, get) {
     const zero = Z();

package/dist/core/clock.js

@@ -12,7 +12,7 @@ function nowUs() {
 exports.nowMicros = nowUs;
 /** 与 Rust `now_nanos` 同语义：墙钟纳秒（`Date` 精度为毫秒，纳秒位为推算值） */
 function nowNanos() {
-    return BigInt(Math.floor(Date.now() * 1_000_000));
+    return BigInt(Date.now()) * 1000000n;
 }
 /** 与 Rust `elapsed_micros_since` 一致 */
 function elapsedMicrosSince(startUs) {

package/dist/core/dex_event.d.ts

@@ -1,6 +1,11 @@
+import type { RawAccountSnapshotEvent, LiquidityAccountSnapshotEvent } from '../liquidity_snapshot.js';
 import type { EventMetadata } from "./metadata.js";
 /** 统一 DEX 事件：外部标签 JSON（单键对象）；键名清单见 `scripts/dex-event-variant-names.json` */
 export type DexEvent = {
+    RawAccountSnapshot: RawAccountSnapshotEvent;
+} | {
+    LiquidityAccountSnapshot: LiquidityAccountSnapshotEvent;
+} | {
     PumpFunCreate: PumpFunCreateTokenEvent;
 } | {
     PumpFunCreateV2: PumpFunCreateV2TokenEvent;
@@ -1353,6 +1358,21 @@ export interface RaydiumLaunchlabTradeEvent {
     is_buy: boolean;
     trade_direction: TradeDirection;
     exact_in: boolean;
+    total_base_sell?: bigint;
+    virtual_base?: bigint;
+    virtual_quote?: bigint;
+    real_base_before?: bigint;
+    real_quote_before?: bigint;
+    real_base_after?: bigint;
+    real_quote_after?: bigint;
+    protocol_fee?: bigint;
+    platform_fee?: bigint;
+    creator_fee?: bigint;
+    share_fee?: bigint;
+    pool_status?: "Fund" | "Migrate" | "Trade";
+    system_program?: string;
+    platform_associated_account?: string;
+    creator_associated_account?: string;
     global_config?: string;
     platform_config?: string;
     user_base_token?: string;
@@ -1391,6 +1411,11 @@ export interface RaydiumLaunchlabMigrateAmmEvent {
     new_pool: string;
     user: string;
     liquidity_amount: bigint;
+    liquidity_amount_known?: boolean;
+    base_mint?: string;
+    quote_mint?: string;
+    platform_config?: string;
+    destination_program?: string;
 }
 export interface TokenInfoEvent {
     metadata: EventMetadata;
@@ -1840,3 +1865,8 @@ export interface BlockMetaEvent {
 }
 export declare function metadataForDexEvent(ev: DexEvent): EventMetadata | null;
 export declare function defaultPubkey(): string;
+/** Rust platform aliases share the existing LaunchLab event shape. */
+export type LaunchLabPoolCreateEvent = RaydiumLaunchlabPoolCreateEvent;
+export type StonkFunPoolCreateEvent = RaydiumLaunchlabPoolCreateEvent;
+export type LaunchLabTradeEvent = RaydiumLaunchlabTradeEvent;
+export type StonkFunTradeEvent = RaydiumLaunchlabTradeEvent;

package/dist/core/metadata.d.ts

@@ -1,11 +1,11 @@
 /** 事件元数据（signature 为 Base58 字符串） */
 export interface EventMetadata {
     signature: string;
-    slot: number;
+    slot: bigint;
     /** gRPC：与 Yellowstone `SubscribeUpdateTransactionInfo.index` 一致（Rust `info.index`）。Shred 等其它路径含义见各实现说明。 */
-    tx_index: number;
-    block_time_us: number;
-    grpc_recv_us: number;
+    tx_index: bigint;
+    block_time_us: bigint;
+    grpc_recv_us: bigint;
     /** Time waiting in the local pre-parser queue, measured with a monotonic clock. */
     local_queue_latency_us?: number;
     /** Pure local adapter + parser duration. No network or RPC calls are included. */
@@ -16,4 +16,8 @@ export interface EventMetadata {
     source_to_grpc_latency_us?: number;
     recent_blockhash?: string;
 }
-export declare function makeMetadata(signature: string, slot: number, txIndex: number, blockTimeUs: number | undefined, grpcRecvUs: number, recentBlockhash?: string): EventMetadata;
+export declare function makeMetadata(signature: string, slot: number | bigint | string, txIndex: number | bigint | string, blockTimeUs: number | bigint | string | undefined, grpcRecvUs: number | bigint | string, recentBlockhash?: string): EventMetadata;
+export type ExactIntegerInput = bigint | string | number;
+export declare function exactInteger(value: ExactIntegerInput, label?: string): bigint;
+export declare function exactU64(value: ExactIntegerInput, label?: string): bigint;
+export declare function exactI64(value: ExactIntegerInput, label?: string): bigint;

package/dist/core/metadata.js

@@ -1,13 +1,37 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.makeMetadata = makeMetadata;
+exports.exactInteger = exactInteger;
+exports.exactU64 = exactU64;
+exports.exactI64 = exactI64;
 function makeMetadata(signature, slot, txIndex, blockTimeUs, grpcRecvUs, recentBlockhash) {
     return {
         signature,
-        slot,
-        tx_index: txIndex,
-        block_time_us: blockTimeUs ?? 0,
-        grpc_recv_us: grpcRecvUs,
+        slot: exactU64(slot, "slot"),
+        tx_index: exactU64(txIndex, "tx_index"),
+        block_time_us: exactI64(blockTimeUs ?? 0, "block_time_us"),
+        grpc_recv_us: exactI64(grpcRecvUs, "grpc_recv_us"),
         recent_blockhash: recentBlockhash,
     };
 }
+function exactInteger(value, label = "integer") {
+    if (typeof value === "number" && !Number.isSafeInteger(value))
+        throw new RangeError(`Unsafe ${label} integer`);
+    if (typeof value === "string" && !/^-?\d+$/.test(value))
+        throw new TypeError(`Invalid ${label} integer`);
+    if (!["bigint", "number", "string"].includes(typeof value))
+        throw new TypeError(`Invalid ${label} type`);
+    return BigInt(value);
+}
+function exactU64(value, label = "u64") {
+    const n = exactInteger(value, label);
+    if (n < 0n || n > (1n << 64n) - 1n)
+        throw new RangeError(`${label} outside u64`);
+    return n;
+}
+function exactI64(value, label = "i64") {
+    const n = exactInteger(value, label);
+    if (n < -(1n << 63n) || n > (1n << 63n) - 1n)
+        throw new RangeError(`${label} outside i64`);
+    return n;
+}

package/dist/core/unified_parser.d.ts

@@ -8,12 +8,12 @@ export type StreamingEventListener = {
     onDexEventStreaming: (event: DexEvent) => void;
 };
 /** 从交易解析事件；当前主路径为日志解析 */
-export declare function parseTransactionEvents(_instructionData: Uint8Array, _accounts: string[], logs: string[], signature: string, slot: number, _txIndex: number, blockTimeUs: number | undefined, _programId: string): DexEvent[];
-export declare function parseLogsOnly(logs: string[], signature: string, slot: number, blockTimeUs: number | undefined, txIndex?: number): DexEvent[];
-export declare function parseTransactionWithListener(instructionData: Uint8Array, accounts: string[], logs: string[], signature: string, slot: number, txIndex: number, blockTimeUs: number | undefined, programId: string, listener: EventListener): void;
-export declare function parseTransactionEventsStreaming(_instructionData: Uint8Array, _accounts: string[], logs: string[], signature: string, slot: number, _txIndex: number, blockTimeUs: number | undefined, _programId: string, callback: (event: DexEvent) => void): void;
-export declare function parseLogsStreaming(logs: string[], signature: string, slot: number, blockTimeUs: number | undefined, callback: (event: DexEvent) => void, txIndex?: number): void;
-export declare function parseTransactionWithStreamingListener(instructionData: Uint8Array, accounts: string[], logs: string[], signature: string, slot: number, txIndex: number, blockTimeUs: number | undefined, programId: string, listener: StreamingEventListener): void;
+export declare function parseTransactionEvents(_instructionData: Uint8Array, _accounts: string[], logs: string[], signature: string, slot: number | bigint | string, _txIndex: number | bigint | string, blockTimeUs: number | bigint | string | undefined, _programId: string): DexEvent[];
+export declare function parseLogsOnly(logs: string[], signature: string, slot: number | bigint | string, blockTimeUs: number | bigint | string | undefined, txIndex?: number | bigint | string): DexEvent[];
+export declare function parseTransactionWithListener(instructionData: Uint8Array, accounts: string[], logs: string[], signature: string, slot: number | bigint | string, txIndex: number | bigint | string, blockTimeUs: number | bigint | string | undefined, programId: string, listener: EventListener): void;
+export declare function parseTransactionEventsStreaming(_instructionData: Uint8Array, _accounts: string[], logs: string[], signature: string, slot: number | bigint | string, _txIndex: number | bigint | string, blockTimeUs: number | bigint | string | undefined, _programId: string, callback: (event: DexEvent) => void): void;
+export declare function parseLogsStreaming(logs: string[], signature: string, slot: number | bigint | string, blockTimeUs: number | bigint | string | undefined, callback: (event: DexEvent) => void, txIndex?: number | bigint | string): void;
+export declare function parseTransactionWithStreamingListener(instructionData: Uint8Array, accounts: string[], logs: string[], signature: string, slot: number | bigint | string, txIndex: number | bigint | string, blockTimeUs: number | bigint | string | undefined, programId: string, listener: StreamingEventListener): void;
 /** 带完整 gRPC 元数据字段的日志解析 */
-export declare function parseLog(log: string, signature: string, slot: number, txIndex: number, blockTimeUs: number | undefined, grpcRecvUs: number, eventTypeFilter: EventTypeFilter | undefined, isCreatedBuy: boolean, recentBlockhash?: Uint8Array): DexEvent | null;
+export declare function parseLog(log: string, signature: string, slot: number | bigint | string, txIndex: number | bigint | string, blockTimeUs: number | bigint | string | undefined, grpcRecvUs: number | bigint | string, eventTypeFilter: EventTypeFilter | undefined, isCreatedBuy: boolean, recentBlockhash?: Uint8Array): DexEvent | null;
 export { nowUs };

package/dist/grpc/block_meta.d.ts

@@ -0,0 +1,9 @@
+/** Local BlockMeta adapter; never fetches a block or blockhash. */
+import type { DexEvent } from "../core/dex_event.js";
+export declare function parseBlockMetaUpdate(meta: {
+    slot: string | number | bigint;
+    blockhash: string;
+    blockTime?: {
+        timestamp: string | number | bigint;
+    };
+}, grpcRecvUs: number | bigint | string, fallbackBlockUs?: number | bigint | string): DexEvent;

package/dist/grpc/block_meta.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseBlockMetaUpdate = parseBlockMetaUpdate;
+const metadata_js_1 = require("../core/metadata.js");
+function parseBlockMetaUpdate(meta, grpcRecvUs, fallbackBlockUs) {
+    const slot = (0, metadata_js_1.exactInteger)(meta.slot, "slot");
+    (0, metadata_js_1.exactU64)(slot, "slot");
+    const seconds = meta.blockTime?.timestamp;
+    let blockUs = (0, metadata_js_1.exactI64)(fallbackBlockUs ?? 0);
+    if (seconds !== undefined) {
+        const v = (0, metadata_js_1.exactInteger)(seconds, "timestamp") * 1000000n, lo = -(1n << 63n), hi = (1n << 63n) - 1n;
+        blockUs = v < lo ? lo : v > hi ? hi : v;
+    }
+    return {
+        BlockMeta: {
+            metadata: {
+                signature: "1".repeat(64),
+                slot,
+                tx_index: 0n,
+                block_time_us: blockUs,
+                grpc_recv_us: (0, metadata_js_1.exactI64)(grpcRecvUs),
+                recent_blockhash: meta.blockhash || undefined,
+            },
+        },
+    };
+}

package/dist/grpc/client.d.ts

@@ -1,16 +1,24 @@
-/**
- * Yellowstone gRPC 客户端实现 - 基于 @triton-one/yellowstone-grpc
- */
-import { CommitmentLevel } from "@triton-one/yellowstone-grpc";
+import { CommitmentLevel } from "./protocol/geyser.js";
 import { type DexEvent } from "../core/dex_event.js";
 import { type EventQueueOverflowStrategy } from "./async_event_queue.js";
 import { type AccountFilter, type ClientConfig, type EventTypeFilter, type TransactionFilter, type SubscribeCallbacks } from "./types.js";
 export { SubscribeCallbacks };
 export type { EventQueueOverflowStrategy } from "./async_event_queue.js";
+export interface GrpcStreamStatus {
+    readonly state: "connecting" | "connected" | "reconnecting" | "stopped";
+    readonly continuityBroken: boolean;
+    readonly reconnects: number;
+    readonly dropped: number;
+}
 export interface DexEventSubscription extends AsyncIterable<DexEvent> {
     id: string;
     errors: AsyncIterable<Error>;
+    /** Bounded transition stream; inspect status() even if notifications were dropped. */
+    states: AsyncIterable<GrpcStreamStatus>;
+    status(): GrpcStreamStatus;
     cancel(): void;
+    /** Wait until the stream and associated workers exit. */
+    join(): Promise<void>;
     next(): Promise<IteratorResult<DexEvent>>;
     len(): number;
     /** Total drops across ingress and the public event queue. */
@@ -49,6 +57,11 @@ export declare class YellowstoneGrpc {
     private connectPromise?;
     private subscribers;
     private dexSubscribers;
+    private dexLifecycle;
+    private activeDex?;
+    private withDexLifecycle;
+    private stopDexUnlocked;
+    stop(): Promise<void>;
     constructor(endpoint: string, xToken: string, config?: ClientConfig);
     /** 连接到 gRPC 服务器 */
     connect(): Promise<void>;
@@ -86,26 +99,28 @@ export declare class YellowstoneGrpc {
      * 事件队列满时按配置丢弃事件，避免回调阻塞 gRPC 读循环并让丢弃可观测。
      */
     subscribeDexEvents(transactionFilters?: TransactionFilter[], accountFilters?: AccountFilter[], eventTypeFilter?: EventTypeFilter, options?: SubscribeDexEventsOptions): Promise<DexEventSubscription>;
+    private startDexEvents;
     /** 取消订阅 */
     unsubscribe(subId: string): void;
     /** 动态更新当前 DEX 订阅过滤器（与 Rust update_subscription 语义对齐）。 */
     updateSubscription(transactionFilters: TransactionFilter[], accountFilters: AccountFilter[]): Promise<void>;
+    private updateDexUnlocked;
     update_subscription(transactionFilters: TransactionFilter[], accountFilters: AccountFilter[]): Promise<void>;
     /** 获取最新区块哈希 */
     getLatestBlockhash(commitment?: CommitmentLevel): Promise<{
-        slot: number;
+        slot: bigint;
         blockhash: string;
-        lastValidBlockHeight: number;
+        lastValidBlockHeight: bigint;
     }>;
     /** 获取区块高度 */
-    getBlockHeight(commitment?: CommitmentLevel): Promise<number>;
+    getBlockHeight(commitment?: CommitmentLevel): Promise<bigint>;
     /** 获取当前 Slot */
-    getSlot(commitment?: CommitmentLevel): Promise<number>;
+    getSlot(commitment?: CommitmentLevel): Promise<bigint>;
     /** 获取服务器版本 */
     getVersion(): Promise<string>;
     /** 验证区块哈希是否有效 */
     isBlockhashValid(blockhash: string, commitment?: CommitmentLevel): Promise<{
-        slot: number;
+        slot: bigint;
         valid: boolean;
     }>;
     /** 发送 Ping 请求 */