sol-parser-sdk-nodejs 0.3.0 → 0.4.4

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">
@@ -31,154 +16,82 @@
     <a href="https://discord.gg/vuazbGkqQE">Discord</a>
 </p>
 
----
+> ☕ **Support This Project**
+>
+> This SDK is completely free and open source. However, maintaining and continuously updating it requires significant AI computing resources and token consumption. If this SDK helps with your development, consider making a monthly SOL donation — any amount is appreciated and helps keep this project alive!
+>
+> **Donation Wallet:** `6oW7AXz1yRb57pYSxysuXnMs2aR1ha5rzGzReZ1MjPV8`
 
-## 📦 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
 
-## 🔥 Quick Start
+### 1. Install
 
-### 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)
+Run examples from that directory so `.env` is picked up.
 
-| 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 |
+### 3. Smoke test
 
-Some scripts ship a default public token for public endpoints; for production, set `GRPC_TOKEN` explicitly.
-
-### 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 +101,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}`);
-```
-
-**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
-
-### Optimized Pattern Matching
-```javascript
-// Pre-compiled regex patterns for fast protocol detection
-const PUMPFUN_PATTERN = /Program 6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P/;
-
-// Fast check before full parsing
-if (PUMPFUN_PATTERN.test(logString)) {
-  return parsePumpFunEvent(logs, signature, slot);
-}
+console.log("subscribed", sub.id);
 ```
 
-### Event Type Filtering
-```javascript
-// Filter specific event types for targeted parsing
-const eventFilter = {
-  include_only: ["PumpFunTrade", "PumpSwapBuy", "PumpSwapSell"]
-};
-```
-
-### JSON Serialization
-```javascript
-const { dexEventToJsonString } = require("./dist/index.js");
-
-for (const ev of events) {
-  // Handles BigInt serialization correctly
-  console.log(dexEventToJsonString(ev));
-}
-```
+**Lighter path:** `parseLogsOnly(logs, signature, slot, …)` — no `transactionRaw`; use `applyAccountFillsToLogEvents` if you need filled accounts without full gRPC meta.
 
----
+### 5. ShredStream (HTTP — not Yellowstone gRPC)
 
-## 🎯 Event Filtering
+Uses **`SHREDSTREAM_URL`** or **`SHRED_URL`** (default `http://127.0.0.1:10800`), or CLI **`--url`**. Not `GRPC_URL`.
 
-Reduce processing overhead by filtering specific events:
+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**.
 
-### 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).
+## Examples
 
-### Unsubscribe
+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).
 
-```javascript
-const sub = await client.subscribeTransactions(filter, callbacks);
-
-// 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
+## Protocols
 
-### 3. **BigInt-Safe Serialization**
-- Custom JSON serializer for BigInt values
-- Avoids JSON.stringify overflow
-- Preserves numeric precision
-
-### 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
+## Useful exports
 
-## 📞 Contact
-
-- **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
+---
 
-# Type check
-npm run typecheck
-```
+## License
+
+MIT — https://github.com/0xfnzero/sol-parser-sdk-nodejs