quicknode-cascade

Stream Solana data at insane speed. One crate. Parallel. Consistent. Crash-safe.

Powered by QuickNode Cascade — edge-cached block archive, 300+ PoPs, sub-50ms latency worldwide.

Try It Now

Clone and run — fetches real Solana blocks, prints every non-vote transaction:

git clone https://github.com/quiknode-labs/quicknode-cascade && cd quicknode-cascade
cargo run --release --example solana_backfill

You'll see:

slot=300000000 txs=2541 time=Some(1730981797)
  tx=24Bx6JCtMat... fee=5000 success=true
  tx=5RrkdQfeNNW... fee=5000 success=true
  ...
slot=300000001 txs=1907 time=Some(1730981798)
  ...

Try the other examples:

cargo run --release --example custom_extraction     # inner instructions + program stats
cargo run --release --example crash_recovery_test   # proves cursor resume works

Use in Your Project

cargo add quicknode-cascade

Two Approaches to Data

1. Custom Extraction — parse raw JSON yourself

Use on_raw to get the full JSON-RPC response. Extract whatever you need — inner instructions, program-specific data, rewards, address lookups, anything.

on_raw is the same hook name across all chains (Solana, Ethereum, etc.).

use quicknode_cascade::{CascadeRunner, solana};

struct MyParser;

impl solana::Plugin for MyParser {
    fn name(&self) -> &'static str { "my-parser" }

    fn on_raw<'a>(&'a self, slot: u64, raw: &'a serde_json::Value) -> solana::PluginFuture<'a> {
        Box::pin(async move {
            let txs = raw.get("transactions").and_then(|v| v.as_array());
            let rewards = raw.get("rewards").and_then(|v| v.as_array());
            println!("slot {} — {} txs, {} rewards",
                slot, txs.map_or(0, |t| t.len()), rewards.map_or(0, |r| r.len()));
            Ok(())
        })
    }
}

fn main() {
    CascadeRunner::solana_mainnet()
        .backfill(300_000_000, 300_000_010)
        .concurrency(10)
        .with_plugin(Box::new(MyParser))
        .run()
        .expect("done");
}

2. Built-in Extraction — let the framework do it

Implement on_block, on_transaction, etc. The framework extracts structured data and calls your hooks.

use quicknode_cascade::{CascadeRunner, solana};

struct MyIndexer;

impl solana::Plugin for MyIndexer {
    fn name(&self) -> &'static str { "my-indexer" }

    fn on_block<'a>(&'a self, block: &'a solana::BlockData) -> solana::PluginFuture<'a> {
        Box::pin(async move {
            println!("slot {} — {} txs", block.slot, block.transaction_count);
            Ok(())
        })
    }

    fn on_transaction<'a>(&'a self, tx: &'a solana::TransactionData) -> solana::PluginFuture<'a> {
        Box::pin(async move {
            if !tx.is_vote {
                println!("  {} fee={}", tx.signature, tx.fee);
            }
            Ok(())
        })
    }
}

fn main() {
    CascadeRunner::solana_mainnet()
        .auth_token("your-jwt-token")
        .backfill(300_000_000, 300_001_000)
        .concurrency(50)
        .with_plugin(Box::new(MyIndexer))
        .run()
        .expect("done");
}

3. Both together

on_raw fires first with raw JSON. Then extraction fires on_block, on_transaction, etc.

Use solana::extract_block() inside on_raw if you want the framework's structured data as a starting point alongside your own parsing.

How It Works

┌──────────────────────────────────────────────────────┐
│  CascadeRunner                                       │
│                                                      │
│  Fetch (parallel) ──▶ on_raw(slot, &raw_json)        │
│       + retry           ↓ your custom extraction     │
│       forever       ────────────────────────────     │
│                     Built-in extraction (optional)    │
│                         ↓ on_block()                 │
│                         ↓ on_transaction()           │
│                         ↓ on_token_transfer()        │
│                         ↓ on_account_activity()      │
│                              ↓                       │
│                     Cursor (atomic, crash-safe)       │
└──────────────────────────────────────────────────────┘

Slots always arrive in order. Kill the process, restart, picks up where it left off.

Examples

Running Modes

// Backfill a slot range
CascadeRunner::solana_mainnet()
    .backfill(300_000_000, 300_001_000)
    .concurrency(50)
    .with_plugin(Box::new(my_plugin))
    .run()

// Follow the chain tip in real-time
CascadeRunner::solana_mainnet()
    .live()
    .with_plugin(Box::new(my_plugin))
    .run()

// Follow from a specific slot
CascadeRunner::solana_mainnet()
    .live_from(300_000_000)
    .with_plugin(Box::new(my_plugin))
    .run()

All Options

CascadeRunner::solana_mainnet()        // or ::solana_devnet() or ::chain("name")
    .auth_token("jwt")                 // JWT for Cascade API
    .concurrency(50)                   // parallel workers (default: 10)
    .encoding("json")                  // "json" (structured) or raw
    .cursor_file("cursor.json")        // resume support (default: cursor.json)
    .tip_buffer(100)                   // slots behind tip for live mode
    .source_url("http://custom:8899")  // override endpoint
    .with_plugin(Box::new(my_plugin))  // register 1+ plugins
    .run()                             // blocks until done or Ctrl-C

Plugin Hooks

impl solana::Plugin for MyPlugin {
    fn name(&self) -> &'static str;

    // Lifecycle
    fn on_load(&self) -> PluginFuture<'_>  { /* open connections */ }
    fn on_exit(&self) -> PluginFuture<'_>  { /* flush, close */ }

    // Raw — fires for EVERY slot, ALL encodings
    fn on_raw(&self, slot: u64, raw: &Value) -> PluginFuture<'_> { ... }

    // Structured — fires after extraction (json encoding only)
    fn on_block(&self, block: &BlockData) -> PluginFuture<'_> { ... }
    fn on_transaction(&self, tx: &TransactionData) -> PluginFuture<'_> { ... }
    fn on_token_transfer(&self, t: &TokenTransferData) -> PluginFuture<'_> { ... }
    fn on_account_activity(&self, a: &AccountActivityData) -> PluginFuture<'_> { ... }
    fn on_skipped_slot(&self, slot: u64) -> PluginFuture<'_> { ... }
}

All hooks default to no-op. Override only what you need.

Convenience import: use quicknode_cascade::solana::prelude::*;

Data Types

Types with raw carry the full JSON so you can parse anything the framework doesn't extract.

Reliability

Delivery guarantee: at-least-once. Design your plugins for idempotent writes.

Multi-Chain

Solana types live under quicknode_cascade::solana. When new chains ship, they get their own modules with chain-specific types — same on_raw hook everywhere:

use quicknode_cascade::solana::{Plugin, BlockData};         // now
// use quicknode_cascade::ethereum::{Plugin, BlockData};    // future

License

Apache-2.0