sol-parser-sdk-nodejs 0.3.0 → 0.4.0

package/README_CN.md

@@ -1,26 +1,11 @@
 <div align="center">
     <h1>⚡ Sol Parser SDK - Node.js</h1>
-    <h3><em>高性能 Solana DEX 事件解析器，专为 Node.js/TypeScript 设计</em></h3>
+    <h3><em>高性能 Solana DEX 事件解析（Node.js / TypeScript）</em></h3>
 </div>
 
 <p align="center">
-    <strong>通过 Yellowstone gRPC 实时解析 Solana DEX 事件的 Node.js/TypeScript 库</strong>
-</p>
-
-<p align="center">
-    <a href="https://www.npmjs.com/package/sol-parser-sdk-nodejs">
-        <img src="https://img.shields.io/badge/npm-sol--parser--sdk--nodejs-red.svg" alt="npm">
-    </a>
-    <a href="https://github.com/0xfnzero/sol-parser-sdk-nodejs/blob/main/LICENSE">
-        <img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License">
-    </a>
-</p>
-
-<p align="center">
-    <img src="https://img.shields.io/badge/Node.js-339933?style=for-the-badge&logo=node.js&logoColor=white" alt="Node.js">
-    <img src="https://img.shields.io/badge/TypeScript-3178C6?style=for-the-badge&logo=typescript&logoColor=white" alt="TypeScript">
-    <img src="https://img.shields.io/badge/Solana-9945FF?style=for-the-badge&logo=solana&logoColor=white" alt="Solana">
-    <img src="https://img.shields.io/badge/gRPC-4285F4?style=for-the-badge&logo=grpc&logoColor=white" alt="gRPC">
+    <a href="https://www.npmjs.com/package/sol-parser-sdk-nodejs"><img src="https://img.shields.io/badge/npm-sol--parser--sdk--nodejs-red.svg" alt="npm"></a>
+    <a href="https://github.com/0xfnzero/sol-parser-sdk-nodejs/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License"></a>
 </p>
 
 <p align="center">
@@ -33,140 +18,74 @@
 
 ---
 
-## 📦 SDK 版本
-
-本 SDK 提供多种语言版本：
+## 其他语言 SDK
 
-| 语言 | 仓库 | 描述 |
-|------|------|------|
-| **Rust** | [sol-parser-sdk](https://github.com/0xfnzero/sol-parser-sdk) | 超低延迟，SIMD 优化 |
-| **Node.js** | [sol-parser-sdk-nodejs](https://github.com/0xfnzero/sol-parser-sdk-nodejs) | TypeScript/JavaScript，Node.js 支持 |
-| **Python** | [sol-parser-sdk-python](https://github.com/0xfnzero/sol-parser-sdk-python) | 原生 async/await 支持 |
-| **Go** | [sol-parser-sdk-golang](https://github.com/0xfnzero/sol-parser-sdk-golang) | 并发安全，goroutine 支持 |
+| 语言 | 仓库 |
+|------|------|
+| Rust | [sol-parser-sdk](https://github.com/0xfnzero/sol-parser-sdk) |
+| Node.js | [sol-parser-sdk-nodejs](https://github.com/0xfnzero/sol-parser-sdk-nodejs) |
+| Python | [sol-parser-sdk-python](https://github.com/0xfnzero/sol-parser-sdk-python) |
+| Go | [sol-parser-sdk-golang](https://github.com/0xfnzero/sol-parser-sdk-golang) |
 
 ---
 
-## 📊 性能亮点
-
-### ⚡ 实时解析
-- **零延迟** 基于日志的事件解析
-- **gRPC 流式传输** 支持 Yellowstone/Geyser 协议
-- **多协议** 单次订阅同时监听多个 DEX
-- **事件类型过滤** 精准解析所需事件
-
-### 🏗️ 支持的协议
-- ✅ **PumpFun** - Meme 代币交易
-- ✅ **PumpSwap** - PumpFun 交换协议
-- ✅ **Raydium AMM V4** - 自动做市商
-- ✅ **Raydium CLMM** - 集中流动性
-- ✅ **Raydium CPMM** - 集中池
-- ✅ **Orca Whirlpool** - 集中流动性 AMM
-- ✅ **Meteora DAMM V2** - 动态 AMM
-- ✅ **Meteora DLMM** - 动态流动性做市商
-- ✅ **Bonk Launchpad** - 代币发射平台
+## 怎么用
 
----
+### 1. 安装
 
-## 🔥 快速开始
+**npm**
 
-### 安装
+```bash
+npm install sol-parser-sdk-nodejs
+```
+
+**源码**（monorepo 里目录可能是 `sol-parser-sdk-ts`）
 
 ```bash
 git clone https://github.com/0xfnzero/sol-parser-sdk-nodejs
 cd sol-parser-sdk-nodejs
-npm install --ignore-scripts
-npm run build
+npm install
+# npm run build   # 若从 dist 引用而非 tsx 跑 examples，再执行
 ```
 
-### 性能测试
+### 2. 环境变量（Yellowstone gRPC 示例）
 
-在**本包根目录**（`sol-parser-sdk-ts/`）执行，需先 `npm run build`：
+在**包根目录**（与 `package.json` 同级）：
 
 ```bash
-# 集成测试：PumpFun + PumpSwap，含账户填充的 DexEvent（与 Rust gRPC 路径一致）
-GRPC_URL=https://solana-yellowstone-grpc.publicnode.com:443 GRPC_TOKEN=你的token npm run test:grpc
-
-# PumpFun 详细性能指标（单事件明细 + 每 10 秒统计）
-GRPC_TOKEN=你的token node examples/pumpfun_with_metrics.mjs
-
-# PumpSwap 详细性能指标（单事件明细 + 每 10 秒统计）
-GRPC_TOKEN=你的token node examples/pumpswap_with_metrics.mjs
-
-# PumpSwap 超低延迟测试
-GRPC_TOKEN=你的token node examples/pumpswap_low_latency.mjs
+cp .env.example .env
+# 填写 GRPC_URL、GRPC_TOKEN
 ```
 
-### 环境变量（gRPC 示例）
-
-| 变量 | 说明 |
-|------|------|
-| **`GRPC_URL`** | Yellowstone gRPC 端点（优先使用）。例：`https://solana-yellowstone-grpc.publicnode.com:443` |
-| **`GRPC_TOKEN`** | 对应端点的 `x-token`（优先使用） |
-| **`GEYSER_ENDPOINT`** | 与 `GRPC_URL` 同义，兼容旧配置 |
-| **`GEYSER_API_TOKEN`** | 与 `GRPC_TOKEN` 同义，兼容旧配置 |
-| **`MAX_EVENTS`** | `*_grpc_json.mjs` 与 `npm run test:grpc`：解析满 N 条事件后退出；`0` 表示持续运行直到 Ctrl+C |
-| **`TIMEOUT_MS`** | 仅 `npm run test:grpc`：运行 N 毫秒后自动退出；`0` 表示不超时（可与 `MAX_EVENTS` 同时设，先满足任一条件即退出） |
-| **`JSON_PRETTY`** | `npm run test:grpc`：设为 `1` 或 `true` 时多行缩进打印（默认单行紧凑 JSON） |
-| **`JSON_MAX_CHARS`** | `npm run test:grpc`：每条事件 JSON 最大字符数；不设或 `0` 表示不截断 |
-
-部分脚本对公共节点带默认 token；生产环境请显式设置 `GRPC_TOKEN`。
-
-### 示例列表
-
-以下命令均在**本包根目录**执行，且已 `npm run build`。
+在该目录下执行下面的 `npx tsx`，以便加载 `.env`。
 
-| 描述 | 运行命令 | 源码 |
-|------|----------|------|
-| **本包脚本** | | |
-| gRPC 集成测试（PumpFun + PumpSwap，账户填充后的 DexEvent） | `npm run test:grpc` | [scripts/test-grpc-ts.mjs](https://github.com/0xfnzero/sol-parser-sdk-nodejs/blob/main/scripts/test-grpc-ts.mjs) |
-| 调试：打印 meta / 日志结构 | `npm run debug:grpc` | [scripts/debug-grpc-ts.mjs](https://github.com/0xfnzero/sol-parser-sdk-nodejs/blob/main/scripts/debug-grpc-ts.mjs) |
-| **PumpFun** | | |
-| gRPC 订阅并输出**完整 JSON** DexEvent（字段与 Rust 对齐） | `node examples/pumpfun_grpc_json.mjs` | [examples/pumpfun_grpc_json.mjs](https://github.com/0xfnzero/sol-parser-sdk-nodejs/blob/main/examples/pumpfun_grpc_json.mjs) |
-| PumpFun 事件解析 + 性能指标 | `node examples/pumpfun_with_metrics.mjs` | [examples/pumpfun_with_metrics.mjs](https://github.com/0xfnzero/sol-parser-sdk-nodejs/blob/main/examples/pumpfun_with_metrics.mjs) |
-| PumpFun 交易类型过滤 | `node examples/pumpfun_trade_filter.mjs` | [examples/pumpfun_trade_filter.mjs](https://github.com/0xfnzero/sol-parser-sdk-nodejs/blob/main/examples/pumpfun_trade_filter.mjs) |
-| PumpFun 快速连接测试 | `node examples/pumpfun_quick_test.mjs` | [examples/pumpfun_quick_test.mjs](https://github.com/0xfnzero/sol-parser-sdk-nodejs/blob/main/examples/pumpfun_quick_test.mjs) |
-| **PumpSwap** | | |
-| gRPC 订阅并输出**完整 JSON** DexEvent（字段与 Rust 对齐） | `node examples/pumpswap_grpc_json.mjs` | [examples/pumpswap_grpc_json.mjs](https://github.com/0xfnzero/sol-parser-sdk-nodejs/blob/main/examples/pumpswap_grpc_json.mjs) |
-| PumpSwap 事件 + 性能统计 | `node examples/pumpswap_with_metrics.mjs` | [examples/pumpswap_with_metrics.mjs](https://github.com/0xfnzero/sol-parser-sdk-nodejs/blob/main/examples/pumpswap_with_metrics.mjs) |
-| PumpSwap 超低延迟 | `node examples/pumpswap_low_latency.mjs` | [examples/pumpswap_low_latency.mjs](https://github.com/0xfnzero/sol-parser-sdk-nodejs/blob/main/examples/pumpswap_low_latency.mjs) |
-| **Meteora DAMM** | | |
-| Meteora DAMM V2 事件 | `node examples/meteora_damm_grpc.mjs` | [examples/meteora_damm_grpc.mjs](https://github.com/0xfnzero/sol-parser-sdk-nodejs/blob/main/examples/meteora_damm_grpc.mjs) |
-| **多协议** | | |
-| 同时订阅所有 DEX 协议 | `node examples/multi_protocol_grpc.mjs` | [examples/multi_protocol_grpc.mjs](https://github.com/0xfnzero/sol-parser-sdk-nodejs/blob/main/examples/multi_protocol_grpc.mjs) |
-| **工具 / 测试** | | |
-| 验证 onUpdate 同步抛错不会打断 gRPC 流 | `node examples/grpc_onupdate_error_test.mjs` | [examples/grpc_onupdate_error_test.mjs](https://github.com/0xfnzero/sol-parser-sdk-nodejs/blob/main/examples/grpc_onupdate_error_test.mjs) |
-| 通过签名解析交易（RPC，非 gRPC） | `TX_SIGNATURE=<sig> node examples/parse_tx_by_signature.mjs` | [examples/parse_tx_by_signature.mjs](https://github.com/0xfnzero/sol-parser-sdk-nodejs/blob/main/examples/parse_tx_by_signature.mjs) |
+### 3. 冒烟
 
-### 基本用法
+```bash
+npx tsx scripts/test-grpc-ts.ts
+```
 
-**推荐（与 Rust gRPC `parse_logs` 一致）：** 在解析 `Program data` 日志后，用订阅里的 **`transactionRaw` + `metaRaw`** 做账户填充，得到完整 `DexEvent`（如 PumpSwap 的 `base_mint`、池子 ATA 等）：
+需要 `GRPC_URL`、`GRPC_TOKEN`。更多变量见 `.env.example`（如 `MAX_EVENTS`、`TIMEOUT_MS`）。
 
-```javascript
-import { createRequire } from "module";
-import { fileURLToPath } from "url";
-import path from "path";
+### 4. 最小 gRPC 订阅示例
 
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const require = createRequire(import.meta.url);
-const {
+```typescript
+import {
   YellowstoneGrpc,
   parseDexEventsFromGrpcTransactionInfo,
   dexEventToJsonString,
-} = require(path.join(__dirname, "../dist/index.js"));
+} from "sol-parser-sdk-nodejs";
 
-const ENDPOINT =
-  process.env.GRPC_URL ||
-  process.env.GEYSER_ENDPOINT ||
-  "https://solana-yellowstone-grpc.publicnode.com:443";
-const X_TOKEN =
-  process.env.GRPC_TOKEN || process.env.GEYSER_API_TOKEN || "";
+const ENDPOINT = process.env.GRPC_URL?.trim() ?? "";
+const X_TOKEN = process.env.GRPC_TOKEN?.trim() ?? "";
+if (!ENDPOINT || !X_TOKEN) throw new Error("GRPC_URL and GRPC_TOKEN are required");
 
 const client = new YellowstoneGrpc(ENDPOINT, X_TOKEN);
 
 const filter = {
   account_include: [
     "6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P", // PumpFun
-    "pAMMBay6oceH9fJKBRHGP5D4bD4sWpmSwMn52FMfXEA", // PumpSwap（Pump AMM）
+    "pAMMBay6oceH9fJKBRHGP5D4bD4sWpmSwMn52FMfXEA", // PumpSwap
   ],
   account_exclude: [],
   account_required: [],
@@ -176,168 +95,97 @@ const filter = {
 
 const sub = await client.subscribeTransactions(filter, {
   onUpdate: (update) => {
-    if (!update.transaction?.transaction) return;
-    const txInfo = update.transaction.transaction;
-    const slot = update.transaction.slot;
-    if (!txInfo.transactionRaw || !txInfo.metaRaw) return;
-
+    const txInfo = update.transaction?.transaction;
+    if (!txInfo?.transactionRaw || !txInfo.metaRaw) return;
+    const slot = update.transaction!.slot;
     const events = parseDexEventsFromGrpcTransactionInfo(txInfo, slot, undefined);
-    for (const ev of events) {
-      console.log(dexEventToJsonString(ev, 2));
-    }
+    for (const ev of events) console.log(dexEventToJsonString(ev, 2));
   },
-  onError: (err) => console.error("错误:", err.message),
-  onEnd: () => console.log("流已结束"),
+  onError: (err) => console.error(err.message),
+  onEnd: () => {},
 });
 
-console.log(`已订阅: ${sub.id}`);
+console.log("subscribed", sub.id);
 ```
 
-**仅日志（更轻）：** `parseLogsOnly(logs, signature, slot, blockTimeUs)` 不需要 `transactionRaw`；部分账户字段可能仍为占位零地址，除非自行对 `VersionedTransaction.message` + `meta` 调用 `applyAccountFillsToLogEvents`。
+更轻量：仅用日志用 `parseLogsOnly`；要补账户可再配合 `applyAccountFillsToLogEvents`。
 
----
+### 5. ShredStream（HTTP，不是 Yellowstone gRPC）
 
-## 🏗️ 支持的协议与事件
-
-### 事件类型
-每个协议均支持：
-- 📈 **交易/兑换事件** - 买入/卖出交易
-- 💧 **流动性事件** - 存入/提取
-- 🏊 **池子事件** - 池子创建/初始化
-- 🎯 **仓位事件** - 开仓/平仓（CLMM）
-
-### PumpFun 事件
-- `PumpFunBuy` - 买入代币
-- `PumpFunSell` - 卖出代币
-- `PumpFunBuyExactSolIn` - 指定 SOL 数量买入
-- `PumpFunCreate` - 创建新代币
-- `PumpFunTrade` - 通用交易（兜底）
-
-### PumpSwap 事件
-- `PumpSwapBuy` - 通过池子买入代币
-- `PumpSwapSell` - 通过池子卖出代币
-- `PumpSwapCreatePool` - 创建流动性池
-- `PumpSwapLiquidityAdded` - 添加流动性
-- `PumpSwapLiquidityRemoved` - 移除流动性
-
-### Raydium 事件
-- `RaydiumAmmV4Swap` - AMM V4 兑换
-- `RaydiumClmmSwap` - CLMM 兑换
-- `RaydiumCpmmSwap` - CPMM 兑换
-
-### Orca 事件
-- `OrcaWhirlpoolSwap` - Whirlpool 兑换
-
-### Meteora 事件
-- `MeteoraDammV2Swap` - DAMM V2 兑换
-- `MeteoraDammV2AddLiquidity` - 添加流动性
-- `MeteoraDammV2RemoveLiquidity` - 移除流动性
-- `MeteoraDammV2CreatePosition` - 创建仓位
-- `MeteoraDammV2ClosePosition` - 关闭仓位
-
-### Bonk 事件
-- `BonkTrade` - Bonk Launchpad 交易
+使用 **`SHREDSTREAM_URL`** / **`SHRED_URL`**（默认 `http://127.0.0.1:10800`）或命令行 **`--url`**，**不用** `GRPC_URL`。
 
----
-
-## 📁 项目结构
+客户端在 **TypeScript** 中解码 gRPC `entries` 负载（布局与 Go `shredstream/entries_decode` 一致），并用 `@solana/web3.js` 反序列化线格式交易，**无需 WebAssembly / wasm-pack**。
 
-```
-sol-parser-sdk-ts/   （npm 包名：sol-parser-sdk-nodejs）
-├── src/
-│   ├── core/
-│   │   ├── unified_parser.ts   # parseLogsOnly 等
-│   │   ├── dex_event.ts        # DexEvent 类型定义
-│   │   ├── rpc_invoke_map.ts   # 程序 invoke 映射、accountKeyToBase58
-│   │   └── json_utils.ts       # dexEventToJsonString
-│   ├── grpc/
-│   │   ├── client.ts           # YellowstoneGrpc 客户端
-│   │   ├── yellowstone_parse.ts # parseDexEventsFromGrpcTransactionInfo
-│   │   └── types.ts            # ClientConfig、TransactionFilter 等
-│   ├── rpc_transaction.ts      # parseRpcTransaction、applyAccountFillsToLogEvents
-│   ├── logs/
-│   │   └── optimized_matcher.ts  # 日志解析（所有协议）
-│   ├── instr/
-│   │   └── *.ts                  # 指令解析器
-│   └── index.ts                  # 公共 API 导出
-├── dist/                         # 编译后的 JavaScript
-├── scripts/
-│   ├── test-grpc-ts.mjs          # npm run test:grpc
-│   └── debug-grpc-ts.mjs         # npm run debug:grpc
-├── examples/
-│   ├── pumpfun_grpc_json.mjs
-│   ├── pumpswap_grpc_json.mjs
-│   ├── grpc_onupdate_error_test.mjs
-│   ├── pumpfun_with_metrics.mjs
-│   ├── pumpfun_trade_filter.mjs
-│   ├── pumpfun_quick_test.mjs
-│   ├── pumpswap_with_metrics.mjs
-│   ├── pumpswap_low_latency.mjs
-│   ├── meteora_damm_grpc.mjs
-│   ├── multi_protocol_grpc.mjs
-│   └── parse_tx_by_signature.mjs
-└── package.json
+```bash
+npx tsx examples/shredstream_example.ts -- --url=http://127.0.0.1:10800
 ```
 
----
+`shredstream_pumpfun_json.ts` 另需 Solana **`RPC_URL`**（或 `--rpc`）解析 ALT。
 
-## 🔧 高级用法
+---
 
-### 自定义 gRPC 端点
+## 示例列表
 
-```javascript
-const ENDPOINT =
-  process.env.GRPC_URL ||
-  process.env.GEYSER_ENDPOINT ||
-  "https://solana-yellowstone-grpc.publicnode.com:443";
-const TOKEN =
-  process.env.GRPC_TOKEN || process.env.GEYSER_API_TOKEN || "";
-const client = new YellowstoneGrpc(ENDPOINT, TOKEN);
-```
+在**包根目录**执行，`npm install` 后即可。示例用 `npx tsx` 直接加载 **`src/`**，**不必先 `npm run build`**。**源码**列每个文件单独一行，链接指向 GitHub 上的对应源码（GitHub / npm 均可点击）。
 
-### gRPC 辅助 API（与 Rust 对齐）
+| 描述 | 运行命令 | 源码 |
+|------|----------|------|
+| **本包脚本** | | |
+| gRPC 集成测试（PumpFun + PumpSwap，账户填充后的 `DexEvent`） | `npx tsx scripts/test-grpc-ts.ts` | [test-grpc-ts.ts](https://github.com/0xfnzero/sol-parser-sdk-nodejs/blob/main/scripts/test-grpc-ts.ts) |
+| 调试：打印 `metaRaw` / 日志结构 | `npx tsx scripts/debug-grpc-ts.ts` | [debug-grpc-ts.ts](https://github.com/0xfnzero/sol-parser-sdk-nodejs/blob/main/scripts/debug-grpc-ts.ts) |
+| **PumpFun** | | |
+| gRPC 输出完整 JSON `DexEvent` | `npx tsx examples/pumpfun_grpc_json.ts` | [pumpfun_grpc_json.ts](https://github.com/0xfnzero/sol-parser-sdk-nodejs/blob/main/examples/pumpfun_grpc_json.ts) |
+| PumpFun 事件 + 性能指标 | `npx tsx examples/pumpfun_with_metrics.ts` | [pumpfun_with_metrics.ts](https://github.com/0xfnzero/sol-parser-sdk-nodejs/blob/main/examples/pumpfun_with_metrics.ts) |
+| PumpFun 交易类型过滤 | `npx tsx examples/pumpfun_trade_filter.ts` | [pumpfun_trade_filter.ts](https://github.com/0xfnzero/sol-parser-sdk-nodejs/blob/main/examples/pumpfun_trade_filter.ts) |
+| PumpFun 快速连接测试 | `npx tsx examples/pumpfun_quick_test.ts` | [pumpfun_quick_test.ts](https://github.com/0xfnzero/sol-parser-sdk-nodejs/blob/main/examples/pumpfun_quick_test.ts) |
+| **PumpSwap** | | |
+| gRPC 输出完整 JSON `DexEvent` | `npx tsx examples/pumpswap_grpc_json.ts` | [pumpswap_grpc_json.ts](https://github.com/0xfnzero/sol-parser-sdk-nodejs/blob/main/examples/pumpswap_grpc_json.ts) |
+| PumpSwap 事件 + 性能指标 | `npx tsx examples/pumpswap_with_metrics.ts` | [pumpswap_with_metrics.ts](https://github.com/0xfnzero/sol-parser-sdk-nodejs/blob/main/examples/pumpswap_with_metrics.ts) |
+| PumpSwap 超低延迟 | `npx tsx examples/pumpswap_low_latency.ts` | [pumpswap_low_latency.ts](https://github.com/0xfnzero/sol-parser-sdk-nodejs/blob/main/examples/pumpswap_low_latency.ts) |
+| **Meteora DAMM** | | |
+| Meteora DAMM V2 事件 | `npx tsx examples/meteora_damm_grpc.ts` | [meteora_damm_grpc.ts](https://github.com/0xfnzero/sol-parser-sdk-nodejs/blob/main/examples/meteora_damm_grpc.ts) |
+| **ShredStream**（HTTP，**非** Yellowstone gRPC；端点见上文步骤 5） | | |
+| 超低延迟订阅、队列与延迟统计。端点：`--url` / `SHREDSTREAM_URL` / `.env`（默认 `http://127.0.0.1:10800`）。 | `npx tsx examples/shredstream_example.ts` | [shredstream_example.ts](https://github.com/0xfnzero/sol-parser-sdk-nodejs/blob/main/examples/shredstream_example.ts) |
+| ShredStream → PumpFun `DexEvent` JSON；需 Solana **RPC** 解析 ALT（`RPC_URL` 或 `--rpc`）。 | `npx tsx examples/shredstream_pumpfun_json.ts` | [shredstream_pumpfun_json.ts](https://github.com/0xfnzero/sol-parser-sdk-nodejs/blob/main/examples/shredstream_pumpfun_json.ts) |
+| **多协议** | | |
+| 同时订阅所有 DEX 协议 | `npx tsx examples/multi_protocol_grpc.ts` | [multi_protocol_grpc.ts](https://github.com/0xfnzero/sol-parser-sdk-nodejs/blob/main/examples/multi_protocol_grpc.ts) |
+| **工具** | | |
+| 验证 onUpdate 同步错误不会打断 gRPC 流 | `npx tsx examples/grpc_onupdate_error_test.ts` | [grpc_onupdate_error_test.ts](https://github.com/0xfnzero/sol-parser-sdk-nodejs/blob/main/examples/grpc_onupdate_error_test.ts) |
+| 按签名解析交易（`parseTransactionFromRpc`；非 gRPC）。在 `.env` 或环境中设置 `TX_SIGNATURE`。 | `npx tsx examples/parse_tx_by_signature.ts` | [parse_tx_by_signature.ts](https://github.com/0xfnzero/sol-parser-sdk-nodejs/blob/main/examples/parse_tx_by_signature.ts) |
 
-- **`parseDexEventsFromGrpcTransactionInfo(txInfo, slot, options?)`** — 先解析日志，再执行与 Rust gRPC 相同的账户/数据填充。需要 `txInfo.transactionRaw` 与 `txInfo.metaRaw`。
-- **`applyAccountFillsToLogEvents(events, message, meta)`** — 若你已有日志解析结果，用手里的 message + meta 补全字段。
-- **`parseRpcTransaction` / `parseTransactionFromRpc`** — 完整 RPC 交易解析（指令 + 日志 + 填充）。
+**`npm run` 别名**（与上表 ShredStream 行同一源码文件，每行一条）：
 
-### 取消订阅
+- `npm run example:shredstream` → [shredstream_example.ts](https://github.com/0xfnzero/sol-parser-sdk-nodejs/blob/main/examples/shredstream_example.ts)
+- `npm run example:shredstream:subscribe` → [shredstream_example.ts](https://github.com/0xfnzero/sol-parser-sdk-nodejs/blob/main/examples/shredstream_example.ts)
+- `npm run example:shredstream:pumpfun-json` → [shredstream_pumpfun_json.ts](https://github.com/0xfnzero/sol-parser-sdk-nodejs/blob/main/examples/shredstream_pumpfun_json.ts)
 
-```javascript
-const sub = await client.subscribeTransactions(filter, callbacks);
+**环境变量：** gRPC 示例需要 **`GRPC_URL`**、**`GRPC_TOKEN`**。ShredStream 使用 **`SHREDSTREAM_URL`** / **`SHRED_URL`** 或 **`--url`**；**`shredstream_pumpfun_json`** 另需 **`RPC_URL`** / **`--rpc`**。详见 **`.env.example`**。
 
-// 稍后取消：
-client.unsubscribe(sub.id);
-```
+---
 
-### JSON 序列化
+## 协议
 
-```javascript
-const { dexEventToJsonString } = require("./dist/index.js");
+PumpFun、PumpSwap、Raydium AMM V4 / CLMM / CPMM、Orca Whirlpool、Meteora DAMM V2 / DLMM、Bonk Launchpad（见 `src/instr/`）。
 
-for (const ev of events) {
-  // 正确处理 BigInt 序列化
-  console.log(dexEventToJsonString(ev));
-}
-```
+---
 
-### 性能建议
+## 常用 API
 
-1. **使用事件过滤** — 按程序 ID 过滤可获得 60-80% 性能提升
-2. **gRPC 场景优先 `parseDexEventsFromGrpcTransactionInfo`** — 在提供 `transactionRaw` + `metaRaw` 时，`DexEvent` 字段与 Rust SDK 一致（mint、池子账户等）
-3. **仅解析一次日志** — `parseLogsOnly` 热路径无堆分配
-4. **避免对 BigInt 使用 JSON.stringify** — 请使用 `dexEventToJsonString`
-5. **监控延迟** — 生产环境检查 `metadata.grpc_recv_us`
+- `parseDexEventsFromGrpcTransactionInfo` — 需要 `transactionRaw` + `metaRaw`（与 Rust gRPC 对齐）。
+- `parseRpcTransaction` / `parseTransactionFromRpc` — HTTP RPC 全量解析。
+- `dexEventToJsonString` — 含 BigInt 的安全 JSON 输出。
 
 ---
 
-## 📄 许可证
+## 开发
+
+```bash
+npm run build
+npm run check:migration   # 对齐与校验，需先 build
+```
 
-MIT License
+---
 
-## 📞 联系我们
+## 许可证
 
-- **仓库**: https://github.com/0xfnzero/sol-parser-sdk-nodejs
-- **官网**: https://fnzero.dev/
-- **Telegram**: https://t.me/fnzero_group
-- **Discord**: https://discord.gg/vuazbGkqQE
+MIT — https://github.com/0xfnzero/sol-parser-sdk-nodejs

package/dist/accounts/mod.d.ts

@@ -7,5 +7,7 @@ export { parseNonceAccount, isNonceAccount } from "./nonce.js";
 export { parseTokenAccount } from "./token.js";
 export { parsePumpswapGlobalConfig, parsePumpswapPool, parsePumpswapAccount, isGlobalConfigAccount, isPoolAccount, } from "./pumpswap.js";
 export { hasDiscriminator } from "./utils.js";
+export { userWalletPubkeyForOnchainAccount } from "./wallet_resolve.js";
+export { rpcResolveUserWalletPubkey } from "./rpc_wallet.js";
 /** 账户数据统一解析入口 */
 export declare function parseAccountUnified(account: AccountData, metadata: EventMetadata, eventTypeFilter?: EventTypeFilter): DexEvent | null;

package/dist/accounts/mod.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.hasDiscriminator = exports.isPoolAccount = exports.isGlobalConfigAccount = exports.parsePumpswapAccount = exports.parsePumpswapPool = exports.parsePumpswapGlobalConfig = exports.parseTokenAccount = exports.isNonceAccount = exports.parseNonceAccount = void 0;
+exports.rpcResolveUserWalletPubkey = exports.userWalletPubkeyForOnchainAccount = exports.hasDiscriminator = exports.isPoolAccount = exports.isGlobalConfigAccount = exports.parsePumpswapAccount = exports.parsePumpswapPool = exports.parsePumpswapGlobalConfig = exports.parseTokenAccount = exports.isNonceAccount = exports.parseNonceAccount = void 0;
 exports.parseAccountUnified = parseAccountUnified;
 const program_ids_js_1 = require("../instr/program_ids.js");
 const nonce_js_1 = require("./nonce.js");
@@ -19,6 +19,10 @@ Object.defineProperty(exports, "isGlobalConfigAccount", { enumerable: true, get:
 Object.defineProperty(exports, "isPoolAccount", { enumerable: true, get: function () { return pumpswap_js_2.isPoolAccount; } });
 var utils_js_1 = require("./utils.js");
 Object.defineProperty(exports, "hasDiscriminator", { enumerable: true, get: function () { return utils_js_1.hasDiscriminator; } });
+var wallet_resolve_js_1 = require("./wallet_resolve.js");
+Object.defineProperty(exports, "userWalletPubkeyForOnchainAccount", { enumerable: true, get: function () { return wallet_resolve_js_1.userWalletPubkeyForOnchainAccount; } });
+var rpc_wallet_js_1 = require("./rpc_wallet.js");
+Object.defineProperty(exports, "rpcResolveUserWalletPubkey", { enumerable: true, get: function () { return rpc_wallet_js_1.rpcResolveUserWalletPubkey; } });
 const ACCOUNT_EVENT_TYPES = [
     "TokenAccount",
     "NonceAccount",

package/dist/accounts/rpc_wallet.d.ts

@@ -0,0 +1,5 @@
+/**
+ * 与 Rust `accounts::rpc_resolve_user_wallet_pubkey` 对齐（异步 RPC）。
+ */
+import type { Connection } from "@solana/web3.js";
+export declare function rpcResolveUserWalletPubkey(connection: Connection, addressBs58: string): Promise<string | null>;

package/dist/accounts/rpc_wallet.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rpcResolveUserWalletPubkey = rpcResolveUserWalletPubkey;
+const web3_js_1 = require("@solana/web3.js");
+const wallet_resolve_js_1 = require("./wallet_resolve.js");
+async function rpcResolveUserWalletPubkey(connection, addressBs58) {
+    let pk;
+    try {
+        pk = new web3_js_1.PublicKey(addressBs58);
+    }
+    catch {
+        return null;
+    }
+    const acc = await connection.getAccountInfo(pk);
+    if (!acc)
+        return null;
+    return (0, wallet_resolve_js_1.userWalletPubkeyForOnchainAccount)(addressBs58, acc.owner.toBase58(), acc.data, acc.executable);
+}

package/dist/accounts/rust_aliases.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Rust `accounts` 模块蛇形命名别名（与 `parse_nonce_account` 等对应）。
+ */
+export { parseAccountUnified as parse_account_unified } from "./mod.js";
+export { parseNonceAccount as parse_nonce_account } from "./nonce.js";
+export { parseTokenAccount as parse_token_account } from "./token.js";
+export { parsePumpswapGlobalConfig as parse_pumpswap_global_config, parsePumpswapPool as parse_pumpswap_pool, } from "./pumpswap.js";
+export { rpcResolveUserWalletPubkey as rpc_resolve_user_wallet_pubkey } from "./rpc_wallet.js";
+export { userWalletPubkeyForOnchainAccount as user_wallet_pubkey_for_onchain_account } from "./wallet_resolve.js";

package/dist/accounts/rust_aliases.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.user_wallet_pubkey_for_onchain_account = exports.rpc_resolve_user_wallet_pubkey = exports.parse_pumpswap_pool = exports.parse_pumpswap_global_config = exports.parse_token_account = exports.parse_nonce_account = exports.parse_account_unified = void 0;
+/**
+ * Rust `accounts` 模块蛇形命名别名（与 `parse_nonce_account` 等对应）。
+ */
+var mod_js_1 = require("./mod.js");
+Object.defineProperty(exports, "parse_account_unified", { enumerable: true, get: function () { return mod_js_1.parseAccountUnified; } });
+var nonce_js_1 = require("./nonce.js");
+Object.defineProperty(exports, "parse_nonce_account", { enumerable: true, get: function () { return nonce_js_1.parseNonceAccount; } });
+var token_js_1 = require("./token.js");
+Object.defineProperty(exports, "parse_token_account", { enumerable: true, get: function () { return token_js_1.parseTokenAccount; } });
+var pumpswap_js_1 = require("./pumpswap.js");
+Object.defineProperty(exports, "parse_pumpswap_global_config", { enumerable: true, get: function () { return pumpswap_js_1.parsePumpswapGlobalConfig; } });
+Object.defineProperty(exports, "parse_pumpswap_pool", { enumerable: true, get: function () { return pumpswap_js_1.parsePumpswapPool; } });
+var rpc_wallet_js_1 = require("./rpc_wallet.js");
+Object.defineProperty(exports, "rpc_resolve_user_wallet_pubkey", { enumerable: true, get: function () { return rpc_wallet_js_1.rpcResolveUserWalletPubkey; } });
+var wallet_resolve_js_1 = require("./wallet_resolve.js");
+Object.defineProperty(exports, "user_wallet_pubkey_for_onchain_account", { enumerable: true, get: function () { return wallet_resolve_js_1.userWalletPubkeyForOnchainAccount; } });

package/dist/accounts/wallet_resolve.d.ts

@@ -0,0 +1 @@
+export declare function userWalletPubkeyForOnchainAccount(address: string, owner: string, data: Uint8Array, executable: boolean): string | null;

package/dist/accounts/wallet_resolve.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.userWalletPubkeyForOnchainAccount = userWalletPubkeyForOnchainAccount;
+/**
+ * 与 Rust `accounts/utils::user_wallet_pubkey_for_onchain_account` 对齐：
+ * 由链上账户 owner / data / executable 推断「用户钱包」公钥（Base58）。
+ */
+const web3_js_1 = require("@solana/web3.js");
+const binary_js_1 = require("../util/binary.js");
+const TOKEN_PROGRAM = new web3_js_1.PublicKey("TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA").toBase58();
+const TOKEN_2022 = new web3_js_1.PublicKey("TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb").toBase58();
+const SYSTEM = web3_js_1.SystemProgram.programId.toBase58();
+/** SPL Token `Account` 布局长度（与 `spl_token::state::Account::LEN` 一致） */
+const SPL_TOKEN_ACCOUNT_LEN = 165;
+function isTokenProgramOwner(owner) {
+    return owner === TOKEN_PROGRAM || owner === TOKEN_2022;
+}
+function userWalletPubkeyForOnchainAccount(address, owner, data, executable) {
+    if (executable)
+        return null;
+    if (owner === SYSTEM) {
+        return data.length === 0 ? address : null;
+    }
+    if (isTokenProgramOwner(owner) && data.length === SPL_TOKEN_ACCOUNT_LEN) {
+        return (0, binary_js_1.readPubkey)(data, 32);
+    }
+    return null;
+}

package/dist/common/constants.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 与 Rust `sol-parser-sdk/src/common/constants.rs` 对齐的流处理默认值。
+ */
+export declare const DEFAULT_CONNECT_TIMEOUT = 10;
+export declare const DEFAULT_REQUEST_TIMEOUT = 60;
+export declare const DEFAULT_CHANNEL_SIZE = 1000;
+export declare const DEFAULT_MAX_DECODING_MESSAGE_SIZE: number;
+export declare const DEFAULT_METRICS_WINDOW_SECONDS = 5;
+export declare const DEFAULT_METRICS_PRINT_INTERVAL_SECONDS = 10;
+export declare const SLOW_PROCESSING_THRESHOLD_US = 3000;

package/dist/common/constants.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SLOW_PROCESSING_THRESHOLD_US = exports.DEFAULT_METRICS_PRINT_INTERVAL_SECONDS = exports.DEFAULT_METRICS_WINDOW_SECONDS = exports.DEFAULT_MAX_DECODING_MESSAGE_SIZE = exports.DEFAULT_CHANNEL_SIZE = exports.DEFAULT_REQUEST_TIMEOUT = exports.DEFAULT_CONNECT_TIMEOUT = void 0;
+/**
+ * 与 Rust `sol-parser-sdk/src/common/constants.rs` 对齐的流处理默认值。
+ */
+exports.DEFAULT_CONNECT_TIMEOUT = 10;
+exports.DEFAULT_REQUEST_TIMEOUT = 60;
+exports.DEFAULT_CHANNEL_SIZE = 1000;
+exports.DEFAULT_MAX_DECODING_MESSAGE_SIZE = 1024 * 1024 * 10;
+exports.DEFAULT_METRICS_WINDOW_SECONDS = 5;
+exports.DEFAULT_METRICS_PRINT_INTERVAL_SECONDS = 10;
+exports.SLOW_PROCESSING_THRESHOLD_US = 3000;