sol-parser-sdk-nodejs 0.3.0 → 0.4.0

package/.env.example

@@ -0,0 +1,24 @@
+# 复制本文件为 `.env` 并填写真实值（`.env` 已在 .gitignore，勿提交密钥）
+# Copy to `.env` and fill in real values (`.env` is gitignored)
+
+# --- Yellowstone gRPC（跑 gRPC 示例、npx tsx scripts/test-grpc-ts.ts / debug-grpc-ts.ts 时必填）---
+GRPC_URL=https://your-yellowstone-host:443
+GRPC_TOKEN=your_x_token_here
+
+# --- 可选：仅 npx tsx scripts/test-grpc-ts.ts ---
+# MAX_EVENTS=0
+# TIMEOUT_MS=0
+# JSON_PRETTY=0
+# JSON_MAX_CHARS=
+
+# --- 可选：仅 examples/parse_tx_by_signature.ts（HTTP RPC，非 gRPC）---
+# TX_SIGNATURE=
+# RPC_URL=https://api.mainnet-beta.solana.com
+
+# --- ShredStream 示例（examples/shredstream_*.ts；亦可 CLI：--url / --rpc）---
+# SHREDSTREAM_URL=http://127.0.0.1:10800
+# 别名: SHRED_URL
+# PumpFun ShredStream 示例拉 ALT 时需 HTTP RPC（可与上栏 RPC_URL 共用）:
+# RPC_URL=https://api.mainnet-beta.solana.com
+# MAX_EVENTS=0
+# SHREDSTREAM_STATS_SEC=0

package/README.md

@@ -4,23 +4,8 @@
 </div>
 
 <p align="center">
-    <strong>High-performance Node.js/TypeScript library for parsing Solana DEX events in real-time via Yellowstone gRPC</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,152 +18,74 @@
 
 ---
 
-## 📦 SDK Versions
-
-This SDK is available in multiple languages:
+## Other language SDKs
 
-| Language | Repository | Description |
-|----------|------------|-------------|
-| **Rust** | [sol-parser-sdk](https://github.com/0xfnzero/sol-parser-sdk) | Ultra-low latency with SIMD optimization |
-| **Node.js** | [sol-parser-sdk-nodejs](https://github.com/0xfnzero/sol-parser-sdk-nodejs) | TypeScript/JavaScript for Node.js |
-| **Python** | [sol-parser-sdk-python](https://github.com/0xfnzero/sol-parser-sdk-python) | Async/await native support |
-| **Go** | [sol-parser-sdk-golang](https://github.com/0xfnzero/sol-parser-sdk-golang) | Concurrent-safe with goroutine support |
+| Language | Repository |
+|----------|------------|
+| 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) |
 
 ---
 
-## 📊 Performance Highlights
-
-### ⚡ Real-Time Parsing
-- **Sub-millisecond** log-based event parsing
-- **gRPC streaming** with Yellowstone/Geyser protocol
-- **Optimized pattern matching** with compiled regex
-- **Event type filtering** for targeted parsing
-- **Zero-allocation** on hot paths where possible
-
-### 🎚️ Flexible Order Modes
-| Mode | Latency | Description |
-|------|---------|-------------|
-| **Unordered** | <1ms | Immediate output, ultra-low latency |
-| **MicroBatch** | 1-5ms | Micro-batch ordering with time window |
-| **StreamingOrdered** | 5-20ms | Stream ordering with continuous sequence release |
-| **Ordered** | 10-100ms | Full slot ordering, wait for complete slot |
-
-### 🚀 Optimization Highlights
-- ✅ **Optimized log parsing** with minimal allocations
-- ✅ **Compiled pattern matchers** for all protocol detection
-- ✅ **Event type filtering** for targeted parsing
-- ✅ **Conditional Create detection** (only when needed)
-- ✅ **Multiple order modes** for latency vs ordering trade-off
-- ✅ **BigInt-safe JSON serialization** for correct number handling
+## How to use
 
----
+### 1. Install
 
-## 🔥 Quick Start
-
-### Installation
+**From npm**
 
 ```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 sol-parser-sdk-nodejs
 ```
 
-### Use npm
+**From source** (folder may be named `sol-parser-sdk-ts` in a monorepo)
 
 ```bash
-npm install sol-parser-sdk-nodejs
+git clone https://github.com/0xfnzero/sol-parser-sdk-nodejs
+cd sol-parser-sdk-nodejs
+npm install
+# npm run build   # only if you import from dist/ instead of examples/tsx → src
 ```
 
-### Performance Testing
+### 2. Environment (Yellowstone gRPC examples)
 
-From the **package root** (`sol-parser-sdk-ts/`), after `npm run build`:
+At the **package root** (next to `package.json`):
 
 ```bash
-# Integration test: PumpFun + PumpSwap, parsed events with account fills (same path as Rust gRPC)
-GRPC_URL=https://solana-yellowstone-grpc.publicnode.com:443 GRPC_TOKEN=your_token npm run test:grpc
-
-# PumpFun with detailed metrics (per-event + 10s stats)
-GRPC_TOKEN=your_token node examples/pumpfun_with_metrics.mjs
-
-# PumpSwap with detailed metrics (per-event + 10s stats)
-GRPC_TOKEN=your_token node examples/pumpswap_with_metrics.mjs
-
-# PumpSwap ultra-low latency test
-GRPC_TOKEN=your_token node examples/pumpswap_low_latency.mjs
+cp .env.example .env
+# Set GRPC_URL and GRPC_TOKEN
 ```
 
-### Environment variables (gRPC examples)
-
-| Variable | Description |
-|----------|-------------|
-| **`GRPC_URL`** | Yellowstone gRPC endpoint (preferred). Example: `https://solana-yellowstone-grpc.publicnode.com:443` |
-| **`GRPC_TOKEN`** | `x-token` for the endpoint (preferred) |
-| **`GEYSER_ENDPOINT`** | Alias for `GRPC_URL` (backward compatible) |
-| **`GEYSER_API_TOKEN`** | Alias for `GRPC_TOKEN` (backward compatible) |
-| **`MAX_EVENTS`** | In `*_grpc_json.mjs` and `npm run test:grpc`: stop after N parsed events; `0` = run until Ctrl+C |
-| **`TIMEOUT_MS`** | `npm run test:grpc` only: auto-exit after N ms; `0` = no timeout (can combine with `MAX_EVENTS`, whichever first) |
-| **`JSON_PRETTY`** | `npm run test:grpc`: set to `1` or `true` for indented JSON (default is compact one-line) |
-| **`JSON_MAX_CHARS`** | `npm run test:grpc`: max characters per event line; unset or `0` = no truncation |
+Run examples from that directory so `.env` is picked up.
 
-Some scripts ship a default public token for public endpoints; for production, set `GRPC_TOKEN` explicitly.
+### 3. Smoke test
 
-### Examples
-
-All commands assume the **package root** and `npm run build` already run.
-
-| Description | Run Command | Source Code |
-|-------------|-------------|-------------|
-| **Scripts (package)** | | |
-| gRPC integration test (PumpFun + PumpSwap, account-filled `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) |
-| Debug: print `metaRaw` / log structure | `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** | | |
-| Pretty-print **full JSON** `DexEvent` over gRPC (Rust-compatible fields) | `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 event parsing with metrics | `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 trade type filtering | `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) |
-| Quick PumpFun connection test | `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** | | |
-| Pretty-print **full JSON** `DexEvent` over gRPC (Rust-compatible fields) | `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 events with metrics | `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 ultra-low latency | `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 events | `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) |
-| **Multi-Protocol** | | |
-| Subscribe to all DEX protocols | `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) |
-| **Utility / QA** | | |
-| Verify `onUpdate` sync errors do not kill the gRPC stream | `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) |
-| Parse tx by signature (RPC, not 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) |
-
-### Basic Usage
+```bash
+npx tsx scripts/test-grpc-ts.ts
+```
 
-**Recommended (aligned with Rust gRPC `parse_logs`):** parse log lines **and** fill mint / pool token accounts from the compiled transaction using `transactionRaw` + `metaRaw` from the subscription:
+Requires `GRPC_URL` and `GRPC_TOKEN`. See `.env.example` for optional vars (`MAX_EVENTS`, `TIMEOUT_MS`, etc.).
 
-```javascript
-import { createRequire } from "module";
-import { fileURLToPath } from "url";
-import path from "path";
+### 4. Minimal gRPC subscribe + parse
 
-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: [],
@@ -188,262 +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("Error:", err.message),
-  onEnd: () => console.log("Stream ended"),
+  onError: (err) => console.error(err.message),
+  onEnd: () => {},
 });
 
-console.log(`Subscribed: ${sub.id}`);
+console.log("subscribed", sub.id);
 ```
 
-**Logs-only (lighter):** `parseLogsOnly(logs, signature, slot, blockTimeUs)` does not require `transactionRaw`; some account fields (e.g. PumpSwap `base_mint`) may stay as the default zero pubkey until you call `applyAccountFillsToLogEvents` yourself with a deserialized message + meta.
-
----
-
-## 🏗️ Supported Protocols
-
-### DEX Protocols
-- ✅ **PumpFun** - Meme coin trading
-- ✅ **PumpSwap** - PumpFun swap protocol
-- ✅ **Raydium AMM V4** - Automated Market Maker
-- ✅ **Raydium CLMM** - Concentrated Liquidity
-- ✅ **Raydium CPMM** - Concentrated Pool
-- ✅ **Orca Whirlpool** - Concentrated liquidity AMM
-- ✅ **Meteora DAMM V2** - Dynamic AMM
-- ✅ **Meteora DLMM** - Dynamic Liquidity Market Maker
-- ✅ **Bonk Launchpad** - Token launch platform
-
-### Event Types
-Each protocol supports:
-- 📈 **Trade/Swap Events** - Buy/sell transactions
-- 💧 **Liquidity Events** - Deposits/withdrawals
-- 🏊 **Pool Events** - Pool creation/initialization
-- 🎯 **Position Events** - Open/close positions (CLMM)
-
----
-
-## ⚡ Performance Features
+**Lighter path:** `parseLogsOnly(logs, signature, slot, …)` — no `transactionRaw`; use `applyAccountFillsToLogEvents` if you need filled accounts without full gRPC meta.
 
-### Optimized Pattern Matching
-```javascript
-// Pre-compiled regex patterns for fast protocol detection
-const PUMPFUN_PATTERN = /Program 6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P/;
+### 5. ShredStream (HTTP — not Yellowstone gRPC)
 
-// Fast check before full parsing
-if (PUMPFUN_PATTERN.test(logString)) {
-  return parsePumpFunEvent(logs, signature, slot);
-}
-```
+Uses **`SHREDSTREAM_URL`** or **`SHRED_URL`** (default `http://127.0.0.1:10800`), or CLI **`--url`**. Not `GRPC_URL`.
 
-### Event Type Filtering
-```javascript
-// Filter specific event types for targeted parsing
-const eventFilter = {
-  include_only: ["PumpFunTrade", "PumpSwapBuy", "PumpSwapSell"]
-};
-```
+The client decodes gRPC `entries` bytes in **TypeScript** (same layout as the Go `shredstream/entries_decode` path) and deserializes wire transactions with `@solana/web3.js` — **no WebAssembly or wasm-pack build**.
 
-### JSON Serialization
-```javascript
-const { dexEventToJsonString } = require("./dist/index.js");
-
-for (const ev of events) {
-  // Handles BigInt serialization correctly
-  console.log(dexEventToJsonString(ev));
-}
-```
-
----
-
-## 🎯 Event Filtering
-
-Reduce processing overhead by filtering specific events:
-
-### Example: Trading Bot
-```javascript
-const eventFilter = {
-  include_only: [
-    "PumpFunTrade",
-    "RaydiumAmmV4Swap",
-    "RaydiumClmmSwap",
-    "OrcaWhirlpoolSwap",
-  ]
-};
-```
-
-### Example: Pool Monitor
-```javascript
-const eventFilter = {
-  include_only: [
-    "PumpFunCreate",
-    "PumpSwapCreatePool",
-  ]
-};
+```bash
+npx tsx examples/shredstream_example.ts -- --url=http://127.0.0.1:10800
 ```
 
-**Performance Impact:**
-- 60-80% reduction in processing
-- Lower memory usage
-- Reduced network bandwidth
+`shredstream_pumpfun_json.ts` also needs a Solana **`RPC_URL`** (or `--rpc`) for ALTs.
 
 ---
 
-## 🔧 Advanced Features
-
-### Create+Buy Detection
-Automatically detects when a token is created and immediately bought in the same transaction:
-
-```javascript
-// Automatically detects "Program data: GB7IKAUcB3c..." pattern
-const events = parseLogsOnly(logs, signature, slot, undefined);
-
-// Sets is_created_buy flag on Trade events
-for (const ev of events) {
-  if (ev.PumpFunTrade && ev.PumpFunTrade.is_created_buy) {
-    console.log("Create+Buy detected!");
-  }
-}
-```
-
-### Custom gRPC Endpoint
-
-```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);
-```
-
-### gRPC helpers (Rust parity)
-
-- **`parseDexEventsFromGrpcTransactionInfo(txInfo, slot, options?)`** — Decode logs, then apply the same account / data filling as the Rust SDK’s gRPC path (`fill_accounts` + `fill_data`). Requires `txInfo.transactionRaw` and `txInfo.metaRaw`.
-- **`applyAccountFillsToLogEvents(events, message, meta)`** — If you already parsed events from logs, apply fills using a `VersionedTransaction` message and `ConfirmedTransactionMeta`.
-- **`parseRpcTransaction`** / **`parseTransactionFromRpc`** — Full RPC transaction parsing (instructions + logs + fills).
-
-### Unsubscribe
+## Examples
 
-```javascript
-const sub = await client.subscribeTransactions(filter, callbacks);
+From the **package root** after `npm install`. Examples use `npx tsx` and load `src/` directly — **no `npm run build` required** for examples. **Source** is one file per row (click to open on GitHub or npm).
 
-// Later, cancel:
-client.unsubscribe(sub.id);
-```
+| Description | Run command | Source |
+|-------------|-------------|--------|
+| **Scripts** | | |
+| gRPC integration test (PumpFun + PumpSwap, account-filled `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) |
+| Debug: print `metaRaw` / log structure | `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** | | |
+| Pretty-print full JSON `DexEvent` over gRPC | `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 events + metrics | `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 trade filter | `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) |
+| Quick PumpFun connection test | `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** | | |
+| Pretty-print full JSON `DexEvent` over gRPC | `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 events + metrics | `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 ultra-low latency | `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 events | `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, not Yellowstone gRPC; see **step 5** above) | | |
+| Ultra-low-latency subscribe + queue / latency stats. URL: `--url` / `SHREDSTREAM_URL` / `.env` (default `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) |
+| PumpFun `DexEvent` JSON from ShredStream; needs Solana **RPC** for ALTs (`RPC_URL` or `--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) |
+| **Multi-protocol** | | |
+| Subscribe to all DEX protocols | `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) |
+| **Utility** | | |
+| Verify `onUpdate` sync errors do not kill the gRPC stream | `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) |
+| Parse tx by signature (`parseTransactionFromRpc`; not gRPC). Set `TX_SIGNATURE` in `.env` or env. | `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) |
 
----
+**`npm run` aliases** (same source files as the ShredStream rows above):
 
-## 📁 Project Structure
+- `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)
 
-```
-sol-parser-sdk-ts/   (npm: sol-parser-sdk-nodejs)
-├── src/
-│   ├── core/
-│   │   ├── unified_parser.ts   # parseLogsOnly, etc.
-│   │   ├── dex_event.ts        # DexEvent type definition
-│   │   ├── rpc_invoke_map.ts   # Program invoke map, accountKeyToBase58
-│   │   └── json_utils.ts       # dexEventToJsonString
-│   ├── grpc/
-│   │   ├── client.ts           # YellowstoneGrpc client
-│   │   ├── yellowstone_parse.ts # parseDexEventsFromGrpcTransactionInfo
-│   │   └── types.ts            # ClientConfig, TransactionFilter, etc.
-│   ├── rpc_transaction.ts      # parseRpcTransaction, applyAccountFillsToLogEvents
-│   ├── logs/
-│   │   └── optimized_matcher.ts  # Log parsing (all protocols)
-│   ├── instr/
-│   │   └── *.ts                  # Instruction parsers
-│   └── index.ts                  # Public API exports
-├── dist/                         # Compiled 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
-```
+**Env:** gRPC examples need **`GRPC_URL`** + **`GRPC_TOKEN`**. ShredStream uses **`SHREDSTREAM_URL`** / **`SHRED_URL`** or **`--url`**; `shredstream_pumpfun_json` also needs **`RPC_URL`** / **`--rpc`**. See **`.env.example`**.
 
 ---
 
-## 🚀 Optimization Techniques
-
-### 1. **Optimized Pattern Matching**
-- Pre-compiled regex patterns for protocol detection
-- Fast path for single-protocol filtering
-- Minimal string allocations
-
-### 2. **Event Type Filtering**
-- Early filtering at protocol level
-- Conditional Create detection
-- Single-type ultra-fast path
-
-### 3. **BigInt-Safe Serialization**
-- Custom JSON serializer for BigInt values
-- Avoids JSON.stringify overflow
-- Preserves numeric precision
+## Protocols
 
-### 4. **Efficient Buffer Handling**
-- Direct Buffer operations for hex encoding
-- Minimal conversions between formats
-- Reusable buffers where possible
-
-### 5. **Callback-Based Streaming**
-- Direct event delivery via callbacks
-- No intermediate queue overhead
-- Immediate processing on receipt
+PumpFun, PumpSwap, Raydium AMM V4 / CLMM / CPMM, Orca Whirlpool, Meteora DAMM V2 / DLMM, Bonk Launchpad (see `src/instr/`).
 
 ---
 
-## 📄 License
-
-MIT License
-
-## 📞 Contact
+## Useful exports
 
-- **Repository**: https://github.com/0xfnzero/sol-parser-sdk-nodejs
-- **Website**: https://fnzero.dev/
-- **Telegram**: https://t.me/fnzero_group
-- **Discord**: https://discord.gg/vuazbGkqQE
+- `parseDexEventsFromGrpcTransactionInfo` — needs `transactionRaw` + `metaRaw` (Rust gRPC parity).
+- `parseRpcTransaction` / `parseTransactionFromRpc` — HTTP RPC path.
+- `dexEventToJsonString` — BigInt-safe JSON.
 
 ---
 
-## ⚠️ Performance Tips
-
-1. **Use Event Filtering** — Filter by program ID for 60-80% performance gain
-2. **Prefer `parseDexEventsFromGrpcTransactionInfo` for gRPC** — Full `DexEvent` fields (mints, pool ATAs) match the Rust SDK when `transactionRaw` + `metaRaw` are present
-3. **Read logs only once** — `parseLogsOnly` is optimized for hot path
-4. **Avoid JSON.stringify on BigInt** — Use `dexEventToJsonString` instead
-5. **Monitor latency** — Check `metadata.grpc_recv_us` in production
-6. **Use latest Node.js** — Newer versions have better optimization
-
-## 🔬 Development
+## Development
 
 ```bash
-# Build
 npm run build
+npm run check:migration   # parity checks; needs build
+```
+
+---
 
-# Watch mode
-npm run dev
+## License
 
-# Type check
-npm run typecheck
-```
+MIT — https://github.com/0xfnzero/sol-parser-sdk-nodejs