sol-parser-sdk 0.6.1

📦 SDK Versions

This SDK is available in multiple languages:

What This SDK Is For

sol-parser-sdk is the low-level Rust parser core for Solana DEX events. It is designed for trading bots, copy-trading pipelines, sniper bots, indexers, and stream processors that need fast, typed parsing from Yellowstone gRPC transactions, Jito ShredStream entries, RPC transaction payloads, or account subscriptions.

📊 Performance Highlights

⚡ Ultra-Low Latency

• 10-20μs parsing latency in release mode
• Zero-copy parsing with stack-allocated buffers
• SIMD-accelerated pattern matching (memchr)
• Lock-free ArrayQueue for event delivery

🎚️ Flexible Order Modes

🚀 Optimization Highlights

• ✅ Zero heap allocation for hot paths
• ✅ SIMD pattern matching for all protocol detection
• ✅ Static pre-compiled finders for string search
• ✅ Inline functions with aggressive optimization
• ✅ Event type filtering for targeted parsing
• ✅ Conditional Create detection (only when needed)
• ✅ Multiple order modes for latency vs ordering trade-off

🔥 Quick Start

Installation

Clone the repository:

cd your_project_dir
git clone https://github.com/0xfnzero/sol-parser-sdk

Add to your Cargo.toml:

[dependencies]
# Default: Borsh parser
sol-parser-sdk = { path = "../sol-parser-sdk" }

# Or: Zero-copy parser (maximum performance)
sol-parser-sdk = { path = "../sol-parser-sdk", default-features = false, features = ["parse-zero-copy"] }

Use crates.io

# Add to your Cargo.toml
sol-parser-sdk = "0.6.1"

Or with the zero-copy parser (maximum performance):

sol-parser-sdk = { version = "0.6.1", default-features = false, features = ["parse-zero-copy"] }

Release Notes

v0.6.1

• Decodes the complete current PumpSwap Buy/Sell event tail across log and CPI/inner-instruction paths: cashback, buyback fees, signed virtual quote reserves, boost eligibility, and base supply.
• Uses one validated PumpSwap trade decoder for the default and zero-copy feature configurations while preserving historical event layouts.
• Rejects truncated tails, malformed UTF-8, invalid Borsh booleans, and overflowing string bounds instead of emitting partially decoded events.
• Keeps older serialized PumpSwap events compatible by defaulting fields introduced by the buyback and boost upgrades.

v0.5.15

• Fixes Pump.fun create_v2 quote mint parsing for both 16-account and 19-account layouts.
• Uses the appended quote mint only when the 19-account quote-pool tail is present; 16-account create_v2 keeps the SOL sentinel.
• Selects the matching create/create_v2 instruction when filling accounts so later buy/sell instructions cannot overwrite create quote fields.

v0.5.13

• Preserves real Pump.fun WSOL quote mints (So11111111111111111111111111111111111111112) in gRPC and ShredStream create/trade outputs.
• Keeps the Solscan SOL sentinel (So11111111111111111111111111111111111111111) only for legacy or missing Pump.fun quote mint fields.
• Adds merge coverage so a placeholder SOL quote mint can be replaced by a later real WSOL quote mint from logs or instruction/account context.

v0.5.11

• Parses PumpSwap create_pool instruction args, including index, deposit amounts, coin_creator, is_mayhem_mode, and is_cashback_coin.
• Fixes PumpSwap create_pool instruction account mapping to match the IDL (pool, creator, base_mint, quote_mint, LP/user token accounts).
• Preserves is_cashback_coin when instruction-derived CreatePool data is merged with log-derived CreatePool data.
• Clarifies source semantics: the PumpSwap log CreatePoolEvent IDL does not carry is_cashback_coin; ShredStream/outer-instruction parsing can read it from instruction data, and account subscriptions can read the authoritative Pool account field.

v0.5.10

• Aligns PumpSwap CreatePoolEvent with the on-chain IDL: the event exposes is_mayhem_mode but not is_cashback_coin.
• Keeps PumpSwap is_cashback_coin on the AccountPumpSwapPool account event, where the on-chain Pool account stores it.
• Fixes the PumpSwap CreatePool log payload length check to include the final is_mayhem_mode byte.
• Documents that ShredStream CreatePool events cannot recover is_cashback_coin because Shred entries do not include account bodies.

v0.5.9

• Implements real Yellowstone gRPC stop() behavior by signaling, aborting, and awaiting the active subscription task.
• Serializes gRPC subscription lifecycle transitions so concurrent stop/re-subscribe calls cannot orphan retry loops.
• Uses a per-subscription stop signal so a new subscription cannot accidentally reset the stop state for an older task.
• Labels stream failures as Grpc Stream error to distinguish them from ShredStream logs.
• Makes the warmup test independent from global test execution order.

v0.5.8

• Adds configurable ShredStream event filter examples, including Pump.fun trade, create-trade, buy, sell, and buy-exact-sol-in presets.
• Clarifies Pump.fun IDL instruction names in ix_name: buy, buy_v2, buy_exact_sol_in, buy_exact_quote_in_v2, sell, and sell_v2.
• Keeps Pump.fun filter families aligned with IDL semantics: PumpFunBuy covers all buy instructions, PumpFunSell covers all sell instructions, and PumpFunTrade covers all buy and sell instructions.
• Ensures subscribing only to PumpFunTrade emits unified DexEvent::PumpFunTrade events on the ShredStream hot path.

v0.5.5

• Aligns ShredStream static-account parsing across Rust, Node.js, Python, and Go.
• Keeps V0 ALT-loaded instruction accounts on the hot path with default pubkey placeholders instead of dropping the whole instruction.
• Adds discriminator fallback when a ShredStream outer program id is ALT-loaded and not present in the static account table.
• Improves Pump.fun ShredStream parity for create/create_v2, v2 short-account trades, and event-type filtering.
• Refreshes multi-protocol routing and account-fill documentation for Pump.fun, PumpSwap, Pump Fees, Raydium, Orca, and Meteora paths.

v0.5.4

• Emits Pump.fun create and create_v2 as one canonical PumpFunCreate event.
• Treats PumpFunCreate and PumpFunCreateV2 filters as the same create-family subscription.
• Keeps create_v2 account fields on the canonical create event so bots do not need to handle two event variants.
• Prevents duplicate new-mint callbacks from gRPC log + instruction parsing.

v0.5.3

• Preserves real Pump.fun v2 ix_name values, including buy_v2, sell_v2, and buy_exact_quote_in_v2.
• Improves ShredStream Pump.fun v2 parsing with best-effort short-account handling for buy, sell, and exact-quote instructions.
• Treats Pump.fun buy-family filters symmetrically, so PumpFunBuy and PumpFunBuyExactSolIn subscriptions both match the compatible buy variants.
• Keeps ShredStream ALT/default-account best-effort parsing for outer instructions while preserving the CPI/inner-only limitation.

Performance Testing

Test parsing latency with the optimized examples:

# PumpFun with detailed metrics (per-event + 10s stats)
cargo run --example pumpfun_with_metrics --release

# PumpSwap with detailed metrics (per-event + 10s stats)
cargo run --example pumpswap_with_metrics --release

# PumpSwap ultra-low latency test
cargo run --example pumpswap_low_latency --release

# PumpSwap with MicroBatch ordering
cargo run --example pumpswap_ordered --release

# Expected output:
# gRPC receive time: 1234567890 μs
# Event receive time: 1234567900 μs
# Latency: 10 μs  <-- Ultra-low latency!

Examples

Basic Usage

use sol_parser_sdk::grpc::{
    AccountFilter, ClientConfig, EventType, EventTypeFilter, OrderMode, Protocol,
    TransactionFilter, YellowstoneGrpc,
};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create gRPC client with default config (Unordered mode)
    let grpc = YellowstoneGrpc::new(
        "https://solana-yellowstone-grpc.publicnode.com:443".to_string(),
        None,
    )?;
    
    // Or with custom config for ordered events
    let config = ClientConfig {
        order_mode: OrderMode::MicroBatch,  // Low latency + ordering
        micro_batch_us: 100,                // 100μs batch window
        ..ClientConfig::default()
    };
    let grpc = YellowstoneGrpc::new_with_config(
        "https://solana-yellowstone-grpc.publicnode.com:443".to_string(),
        None,
        config,
    )?;

    let protocols = vec![Protocol::PumpFun, Protocol::PumpSwap, Protocol::RaydiumCpmm];
    let transaction_filter = TransactionFilter::for_protocols(&protocols);
    let account_filter = AccountFilter::for_protocols(&protocols);

    // Filter before parsing for the lowest-latency path.
    let event_filter = EventTypeFilter::include_only(vec![
        EventType::PumpFunBuy,
        EventType::PumpFunSell,
        EventType::PumpSwapBuy,
        EventType::PumpSwapSell,
        EventType::RaydiumCpmmSwap,
    ]);

    // Subscribe and get lock-free queue
    let queue = grpc.subscribe_dex_events(
        vec![transaction_filter],
        vec![account_filter],
        Some(event_filter),
    ).await?;

    // Consume events with minimal latency
    tokio::spawn(async move {
        let mut spin_count = 0;
        loop {
            if let Some(event) = queue.pop() {
                spin_count = 0;
                // Process event (10-20μs latency!)
                println!("{:?}", event);
            } else {
                // Hybrid spin-wait strategy
                spin_count += 1;
                if spin_count < 1000 {
                    std::hint::spin_loop();
                } else {
                    tokio::task::yield_now().await;
                    spin_count = 0;
                }
            }
        }
    });

    Ok(())
}

ShredStream Usage (Jito)

ShredStream provides ultra-low latency (~50-100ms faster than gRPC) by directly subscribing to Jito's ShredStream service:

use sol_parser_sdk::grpc::{EventType, EventTypeFilter};
use sol_parser_sdk::shredstream::{ShredStreamClient, ShredStreamConfig};
use sol_parser_sdk::DexEvent;
use std::sync::Arc;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create ShredStream client
    let client = ShredStreamClient::new("http://127.0.0.1:10800").await?;

    // Or with custom config
    let config = ShredStreamConfig {
        connection_timeout_ms: 5000,
        request_timeout_ms: 30000,
        max_decoding_message_size: 1024 * 1024 * 1024,
        reconnect_delay_ms: 1000,
        max_reconnect_attempts: 0, // 0 = infinite reconnect
    };
    let client = ShredStreamClient::new_with_config("http://127.0.0.1:10800", config).await?;

    // Subscribe with SDK-side filtering before event conversion.
    // Use `client.subscribe().await?` to receive every supported event.
    let event_filter = EventTypeFilter::include_only(vec![
        EventType::PumpFunBuy,
        EventType::PumpSwapBuy,
        EventType::RaydiumCpmmSwap,
    ]);
    let queue = client.subscribe_with_filter(Some(event_filter)).await?;

    // Consume events
    loop {
        if let Some(event) = queue.pop() {
            match &event {
                DexEvent::PumpFunTrade(e) => {
                    println!("PumpFun Trade: mint={}, is_buy={}", e.mint, e.is_buy);
                }
                DexEvent::PumpSwapBuy(e) => {
                    println!("PumpSwap Buy: pool={}", e.pool);
                }
                _ => {}
            }
        } else {
            std::hint::spin_loop();
        }
    }
}

ShredStream Limitations:

• Only static_account_keys() - ALT-loaded instruction accounts use default placeholders, while outer instructions are parsed best-effort from data/discriminators
• No Inner Instructions - CPI/inner-only events cannot be recovered from ShredStream entries
• No block_time - always 0
• tx_index is entry-level, not slot-level

🏗️ Supported Protocols

DEX Protocols

• ✅ PumpFun - Meme coin trading (ultra-fast zero-copy path, incl. v2 instructions)
• ✅ Pump Fees - Pump fee-sharing configuration events
• ✅ PumpSwap - PumpFun swap protocol
• ✅ Raydium LaunchLab - Token launch platform
• ✅ Raydium AMM V4 - Automated Market Maker
• ✅ Raydium CLMM - Concentrated Liquidity
• ✅ Raydium CPMM - Concentrated Pool
• ✅ Orca Whirlpool - Concentrated liquidity AMM
• ✅ Meteora Pools - Dynamic AMM
• ✅ Meteora DAMM v2 - Dynamic AMM V2
• ✅ Meteora DLMM - Dynamic Liquidity Market Maker
• 🚧 Meteora DBC - Program id and filters added; transaction/account parser pass pending

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)

Non-Pump DEX Support Matrix

The canonical cross-language baseline is tracked in protocols/canonical.json. The current audit and remaining parser work are documented in docs/non-pump-dex-gap-analysis.md.

⚡ Performance Features

Zero-Copy Parsing

// Stack-allocated 512-byte buffer for PumpFun Trade
const MAX_DECODE_SIZE: usize = 512;
let mut decode_buf: [u8; MAX_DECODE_SIZE] = [0u8; MAX_DECODE_SIZE];

// Decode directly to stack, no heap allocation
general_purpose::STANDARD
    .decode_slice(data_part.as_bytes(), &mut decode_buf)
    .ok()?;

SIMD Pattern Matching

// Pre-compiled SIMD finders (initialized once)
static PUMPFUN_FINDER: Lazy<memmem::Finder> =
    Lazy::new(|| memmem::Finder::new(b"6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P"));

// 3-10x faster than .contains()
if PUMPFUN_FINDER.find(log_bytes).is_some() {
    return LogType::PumpFun;
}

Event Type Filtering

// Ultra-fast path for single event type
if include_only.len() == 1 && include_only[0] == EventType::PumpFunTrade {
    if log_type == LogType::PumpFun {
        return parse_pumpfun_trade(  // Zero-copy path
            log, signature, slot, block_time, grpc_recv_us, is_created_buy
        );
    }
}

Lock-Free Queue

// ArrayQueue with 100,000 capacity
let queue = Arc::new(ArrayQueue::<DexEvent>::new(100_000));

// Non-blocking push/pop (no mutex overhead)
let _ = queue.push(event);
if let Some(event) = queue.pop() {
    // Process event
}

🎯 Event Filtering

Reduce processing overhead by filtering specific events:

Example: Trading Bot

let event_filter = EventTypeFilter::include_only(vec![
    EventType::PumpFunBuy,
    EventType::PumpFunSell,
    EventType::PumpFunBuyExactSolIn,
    EventType::PumpSwapBuy,
    EventType::PumpSwapSell,
    EventType::RaydiumLaunchlabTrade,
    EventType::RaydiumCpmmSwap,
    EventType::RaydiumAmmV4Swap,
    EventType::RaydiumClmmSwap,
    EventType::OrcaWhirlpoolSwap,
    EventType::MeteoraPoolsSwap,
    EventType::MeteoraDammV2Swap,
    EventType::MeteoraDlmmSwap,
]);

Example: Pool Monitor

let event_filter = EventTypeFilter::include_only(vec![
    EventType::PumpFunCreate,
    EventType::PumpFeesUpdateFeeShares,
    EventType::PumpSwapCreatePool,
    EventType::AccountPumpSwapPool,
    EventType::RaydiumCpmmInitialize,
    EventType::RaydiumClmmCreatePool,
    EventType::OrcaWhirlpoolPoolInitialized,
    EventType::MeteoraPoolsPoolCreated,
    EventType::MeteoraDammV2CreatePosition,
    EventType::MeteoraDlmmInitializePool,
]);

PumpSwapCreatePool includes is_mayhem_mode. For is_cashback_coin, ShredStream/outer-instruction parsing reads the flag from the create_pool instruction args, while log-only CreatePoolEvent payloads keep the default false because the log event IDL does not carry this field. The authoritative account value is also available from PumpSwapPoolAccountEvent.pool.is_cashback_coin.

Performance Impact:

• 60-80% reduction in processing
• Lower memory usage
• Reduced network bandwidth

🔧 Advanced Features

Create+Buy Detection

Automatically detects when a token is created and immediately bought in the same transaction:

// Detects "Program data: GB7IKAUcB3c..." pattern
let has_create = detect_pumpfun_create(logs);

// Sets is_created_buy flag on Trade events
if has_create {
    trade_event.is_created_buy = true;
}

Pump.fun Bonding Curve v2 (buy_v2 / sell_v2 / buy_exact_quote_in_v2)

The SDK recognizes Pump.fun's new v2 trading instructions introduced in the Bonding Curve upgrade. Event logs from buy_v2, sell_v2, and buy_exact_quote_in_v2 are parsed with the same zero-copy path and mapped to the existing event types:

No changes are required in your event handling code — v2 events arrive through the same PumpFunTradeEvent struct with the correct ix_name field populated. Instruction discriminators for buy_v2 ([184, 23, 238, 97, 103, 197, 211, 61]), sell_v2 ([93, 246, 130, 60, 231, 233, 64, 178]), and buy_exact_quote_in_v2 ([194, 171, 28, 70, 104, 77, 91, 47]) are recognized at the instruction parser level.

CreateEvent also exposes quote_mint and virtual_quote_reserves, so USDC quote pools can be distinguished from native SOL pools and initialized with the correct quote-side reserve.

Dynamic Subscription

Update filters without reconnecting:

grpc.update_subscription(
    vec![new_transaction_filter],
    vec![new_account_filter],
).await?;

Order Modes

Choose the right balance between latency and ordering:

use sol_parser_sdk::grpc::{ClientConfig, OrderMode};

// Ultra-low latency (no ordering guarantee)
let config = ClientConfig {
    order_mode: OrderMode::Unordered,
    ..ClientConfig::default()
};

// Low latency with micro-batch ordering (50-200μs)
let config = ClientConfig {
    order_mode: OrderMode::MicroBatch,
    micro_batch_us: 100,  // 100μs batch window
    ..ClientConfig::default()
};

// Stream ordering with continuous sequence release (0.1-5ms)
let config = ClientConfig {
    order_mode: OrderMode::StreamingOrdered,
    order_timeout_ms: 50,  // Timeout for incomplete sequences
    ..ClientConfig::default()
};

// Full slot ordering (1-50ms, wait for complete slot)
let config = ClientConfig {
    order_mode: OrderMode::Ordered,
    order_timeout_ms: 100,
    ..ClientConfig::default()
};

Performance Metrics

let config = ClientConfig {
    enable_metrics: true,
    ..ClientConfig::default()
};

let grpc = YellowstoneGrpc::new_with_config(endpoint, token, config)?;

📁 Project Structure

src/
├── core/
│   └── events.rs          # Event definitions
├── grpc/
│   ├── client.rs          # Yellowstone gRPC client
│   ├── buffers.rs         # SlotBuffer & MicroBatchBuffer
│   └── types.rs           # OrderMode, ClientConfig, filters
├── shredstream/
│   ├── client.rs          # Jito ShredStream client
│   ├── config.rs          # ShredStreamConfig
│   └── proto/             # Protobuf definitions
├── logs/
│   ├── optimized_matcher.rs  # SIMD log detection
│   ├── zero_copy_parser.rs   # Zero-copy parsing
│   ├── pumpfun.rs         # PumpFun parser
│   ├── raydium_*.rs       # Raydium parsers
│   ├── orca_*.rs          # Orca parsers
│   └── meteora_*.rs       # Meteora parsers
├── instr/
│   └── *.rs               # Instruction parsers
├── warmup/
│   └── mod.rs             # Parser warmup (auto-called)
└── lib.rs

🚀 Optimization Techniques

1. SIMD String Matching

• Replaced all .contains() with memmem::Finder
• 3-10x performance improvement
• Pre-compiled static finders

2. Zero-Copy Parsing

• Stack-allocated buffers (512 bytes)
• No heap allocation in hot path
• Inline helper functions

3. Event Type Filtering

• Early filtering at protocol level
• Conditional Create detection
• Single-type ultra-fast path

4. Lock-Free Queue

• ArrayQueue (100K capacity)
• Spin-wait hybrid strategy
• No mutex overhead

5. Aggressive Inlining

#[inline(always)]
fn read_u64_le_inline(data: &[u8], offset: usize) -> Option<u64> {
    if offset + 8 <= data.len() {
        let mut bytes = [0u8; 8];
        bytes.copy_from_slice(&data[offset..offset + 8]);
        Some(u64::from_le_bytes(bytes))
    } else {
        None
    }
}

📊 Benchmarks

Parsing Latency (Release Mode)

SIMD Pattern Matching

📄 License

MIT License

📞 Contact

• Repository: https://github.com/0xfnzero/sol-parser-sdk
• Telegram: https://t.me/fnzero_group
• Discord: https://discord.gg/vuazbGkqQE

⚠️ Performance Tips

1. Use Event Filtering - Filter at the source for 60-80% performance gain
2. Run in Release Mode - cargo build --release for full optimization
3. Test with sudo - sudo cargo run --example basic --release for accurate timing
4. Monitor Latency - Check grpc_recv_us and queue latency in production
5. Tune Queue Size - Adjust ArrayQueue capacity based on your throughput
6. Spin-Wait Strategy - Tune spin count (default: 1000) for your use case

🔬 Development

# Run tests
cargo test

# Build release binary
cargo build --release

# Generate docs
cargo doc --open