Slipstream Rust SDK

The official Rust client for AllenHark Slipstream, the high-performance Solana transaction relay and intelligence network.

Overview

The Slipstream SDK provides a robust, low-latency connection to the Slipstream Global Mesh. It allows Solana applications to:

• Submit Transactions with minimal latency using QUIC and IP-based routing.
• Stream Intelligence such as leader hints, priority fees, and tip instructions in real-time.
• Ensure Reliability through automatic protocol fallback and background health monitoring.

Features

• Multi-Protocol Support: Primary QUIC transport for speed, falling back to gRPC, WebSocket, and HTTP to ensure connectivity in any environment.
• Smart Worker Selection: Automatically pings and selects the lowest-latency worker endpoint in the mesh (IP-based routing).
• Resilience: Integrated HealthMonitor checks connection status and reconnects transparently.
• Real-Time Streams: Subscribe to network insights:
  • LeaderHint: Which region/validator is leading the current slot.
  • PriorityFee: Dynamic compute unit pricing.
  • TipInstruction: Optimal tip amounts and destinations.

Installation

Add the following to your Cargo.toml:

[dependencies]
allenhark-slipstream = "0.1"
tokio = { version = "1.0", features = ["full"] }

Quick Start

Connecting

The SlipstreamClient handles connection logic, authentication, and worker selection automatically.

use allenhark_slipstream::{Config, SlipstreamClient};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Basic connectivity
    let config = Config::builder()
        .api_key("sk_test_12345678") // Your API Key
        .region("us-east")           // Optional: Prefer a specific region
        .build()?;

    let client = SlipstreamClient::connect(config).await?;
    
    println!("Connected via: {}", client.connection_info().protocol);
    
    Ok(())
}

Submitting a Transaction

// Submit a raw signed transaction (serialized as bytes)
let tx_data: Vec<u8> = vec![...]; 

let result = client.submit_transaction(&tx_data).await?;

println!("Transaction ID: {}", result.transaction_id);
println!("Status: {:?}", result.status);

Advanced Submission Options

You can control broadcast behavior and retry logic:

use allenhark_slipstream::SubmitOptions;

let options = SubmitOptions {
    broadcast_mode: true, // Fan-out to multiple regions
    max_retries: 5,
    ..Default::default()
};

let result = client.submit_transaction_with_options(&tx_data, &options).await?;

Streaming Intelligence

Subscribe to real-time data feeds to optimize your trading or transaction strategy.

// 1. Leader Hints
let mut hints = client.subscribe_leader_hints().await?;
while let Some(hint) = hints.recv().await {
    println!("Current Leader Region: {}", hint.preferred_region);
}

// 2. Priority Fees
let mut fee_stream = client.subscribe_priority_fees().await?;
while let Some(fee) = fee_stream.recv().await {
    println!("Recommended Fee: {} micro-lamports", fee.compute_unit_price);
}

Configuration

The Config::builder() provides a fluent interface for configuration:

Option	Description	Default
api_key	Required. Your authentication key.	-
region	Preferred region (e.g., us-east, eu-central).	Auto-detect
endpoint	Explicit URL override (disables worker selection).	None
leader_hints	Enable auto-subscription to leader hints.	true
protocol_timeouts	Custom timeouts for QUIC, gRPC, etc.	Smart defaults
priority_fee	Priority fee configuration (PriorityFeeConfig).	Disabled
retry_backoff	Retry strategy: Linear or Exponential.	Exponential
min_confidence	Min confidence for leader hints (0-100).	70
idle_timeout	Connection idle timeout.	None (no timeout)

Priority Fee Configuration

use allenhark_slipstream::{PriorityFeeConfig, PriorityFeeSpeed};

let config = Config::builder()
    .api_key("sk_test_123")
    .priority_fee(PriorityFeeConfig {
        enabled: true,
        speed: PriorityFeeSpeed::UltraFast,
        max_tip: Some(0.01), // Max 0.01 SOL
    })
    .build()?;

Helper Methods

// Get the latest tip instruction (cached)
if let Some(tip) = client.get_latest_tip().await {
    println!("Tip {} SOL to {}", tip.tip_amount_sol, tip.tip_wallet_address);
}

// Get connection status
let status = client.connection_status().await;
println!("State: {:?}, Protocol: {:?}", status.state, status.protocol);

// Get performance metrics
let metrics = client.metrics();
println!("Submitted: {}, Success Rate: {:.1}%", 
    metrics.transactions_submitted, metrics.success_rate * 100.0);

Architecture

1. Worker Selection: When you call connect(), the SDK queries the mesh for available workers and pings them. It selects the one with the lowest Round-Trip Time (RTT).
2. Protocol Fallback: The client attempts to connect using QUIC. If that fails (e.g., firewall blocked), it tries gRPC, then WebSocket, then HTTP.
3. Authentication: All requests are signed and authenticated using your api_key.

Examples

The examples/ directory contains comprehensive, runnable examples:

Example	Description
basic.rs	Simple connection and disconnection
submit_transaction.rs	Transaction submission with options
priority_fees.rs	Priority fee configuration and streaming
tip_instructions.rs	Tip wallet and amount streaming
leader_hints.rs	Leader region hints for optimal routing
broadcast_tx.rs	Fan-out to multiple regions
signer_integration.rs	Keypair, Ledger, multi-sig, MPC signing
deduplication.rs	Prevent duplicate transaction submissions
streaming_callbacks.rs	All streaming subscriptions (Rust channels)
advanced_config.rs	Full configuration options

Run any example with:

SLIPSTREAM_API_KEY=sk_test_xxx cargo run --example priority_fees

Streaming (Callbacks)

Rust uses async channels instead of JavaScript-style callbacks:

// Subscribe to streams
let mut hints = client.subscribe_leader_hints().await?;
let mut tips = client.subscribe_tip_instructions().await?;
let mut fees = client.subscribe_priority_fees().await?;

// Handle all streams concurrently
loop {
    tokio::select! {
        Some(hint) = hints.recv() => {
            println!("Leader in {}", hint.preferred_region);
        }
        Some(tip) = tips.recv() => {
            println!("Tip {} SOL", tip.tip_amount_sol);
        }
        Some(fee) = fees.recv() => {
            println!("Fee {} µL/CU", fee.compute_unit_price);
        }
    }
}

Deduplication

Prevent duplicate submissions with dedup_id:

let options = SubmitOptions {
    dedup_id: Some("unique-tx-id-12345".to_string()),
    max_retries: 5,
    ..Default::default()
};

// Same dedup_id across retries = safe from double-spend
let result = client.submit_transaction_with_options(&tx, &options).await?;

Error Handling

use allenhark_slipstream::SdkError;

match client.submit_transaction(&tx).await {
    Ok(result) => println!("Signature: {:?}", result.signature),
    Err(SdkError::Connection(msg)) => println!("Connection error: {}", msg),
    Err(SdkError::RateLimited) => println!("Rate limited, back off"),
    Err(e) => println!("Error: {}", e),
}

Governance & Support

This SDK is community supported.

• Issues: Please file bug reports on GitHub.
• Docs: See docs/ARCHITECTURE.md for technical details.
• Enterprise Support: Available at allenhark.com.