Struct CascadeRunner 

pub struct CascadeRunner { /* private fields */ }

Builder-pattern runner for the streaming engine.

Handles all parallel fetching, retry-forever logic, plugin dispatch, cursor management, and graceful shutdown.

Example

use quicknode_cascade::{CascadeRunner, solana};

struct Logger;
impl solana::Plugin for Logger {
    fn name(&self) -> &'static str { "logger" }
    fn on_block<'a>(&'a self, block: &'a solana::BlockData) -> solana::PluginFuture<'a> {
        Box::pin(async move {
            println!("slot {}", block.slot);
            Ok(())
        })
    }
}

CascadeRunner::solana_mainnet()
    .auth_token("your-jwt-token")
    .backfill(400_000_000, 400_000_010)
    .with_plugin(Box::new(Logger))
    .run()
    .expect("done");

Implementations

impl CascadeRunner

pub fn solana_mainnet() -> Self

Create a runner for Solana mainnet via QuickNode Cascade.

pub fn solana_devnet() -> Self

Create a runner for Solana devnet via QuickNode Cascade.

pub fn chain(name: &str) -> Self

Create a runner for a named chain.

The chain name maps to the Cascade endpoint: https://{chain}-cascade.quiknode.io

Examples

use quicknode_cascade::CascadeRunner;

// These are equivalent:
let a = CascadeRunner::solana_mainnet();
let b = CascadeRunner::chain("solana-mainnet");

pub fn auth_token(self, token: &str) -> Self

Set the authentication token (JWT) for the Cascade endpoint.

The token is sent as Authorization: Bearer <token> on every request.

pub fn source_url(self, url: &str) -> Self

Override the source URL directly (for custom RPC endpoints).

Use this when pointing at your own Solana validator or a non-Cascade RPC.

pub fn with_plugin(self, plugin: Box<dyn Plugin>) -> Self

Register a plugin. Multiple plugins can be registered; each sees all events.

pub fn concurrency(self, n: usize) -> Self

Set parallel fetch concurrency (default: 10).

pub fn encoding(self, encoding: &str) -> Self

Set the encoding for fetching blocks (default: “json”).

on_slot fires for ALL encodings with the raw JSON.

In "json" mode, the runner additionally extracts structured data and calls on_block/on_transaction/on_token_transfer/on_account_activity.

In any other mode ("jsonParsed", "base64", etc.), only on_slot fires.

pub fn backfill(self, start: u64, end: u64) -> Self

Set the runner to backfill a specific slot range.

pub fn live(self) -> Self

Set the runner to follow the chain tip in real-time.

pub fn live_from(self, slot: u64) -> Self

Set the runner to follow the chain tip, starting from a specific slot.

pub fn cursor_file(self, path: &str) -> Self

Set the cursor file path for resume support (default: “cursor.json”).

pub fn tip_buffer(self, slots: u64) -> Self

Set the tip buffer for live mode (default: 100 slots).

Keeps the client N slots behind the chain tip to ensure data availability on Cascade. Set to 0 for direct RPC endpoints.

pub fn run(self) -> Result<()>

Run the engine. Blocks until completion (backfill) or shutdown signal (live).

Creates a tokio runtime internally. If called from within an async context, use run_async instead.

pub async fn run_async(self) -> Result<()>

Async version of run.

Use this from within an existing tokio runtime.