Crate hypersync_client 

HyperSync Client

A high-performance Rust client for the HyperSync protocol, enabling efficient retrieval of blockchain data including blocks, transactions, logs, and traces.

Features

• High-performance streaming: Parallel data fetching with automatic retries
• Flexible querying: Rich query builder API for precise data selection
• Multiple data formats: Support for Arrow, Parquet, and simple Rust types
• Event decoding: Automatic ABI decoding for smart contract events
• Real-time updates: Live height streaming via Server-Sent Events
• Production ready: Built-in rate limiting, retries, and error handling

Quick Start

use hypersync_client::{Client, net_types::{Query, LogFilter, LogField}, StreamConfig};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // Create a client for Ethereum mainnet
    let client = Client::builder()
        .chain_id(1)
        .api_token(std::env::var("ENVIO_API_TOKEN")?)
        .build()?;

    // Query ERC20 transfer events from USDC contract
    let query = Query::new()
        .from_block(19000000)
        .to_block_excl(19001000)
        .where_logs(
            LogFilter::all()
                .and_address(["0xA0b86a33E6411b87Fd9D3DF822C8698FC06BBe4c"])?
                .and_topic0(["0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"])?
        )
        .select_log_fields([LogField::Address, LogField::Topic1, LogField::Topic2, LogField::Data]);

    // Get all data in one response
    let response = client.get(&query).await?;
    println!("Retrieved {} blocks", response.data.blocks.len());

    // Or stream data for large ranges
    let mut receiver = client.stream(query, StreamConfig::default()).await?;
    while let Some(response) = receiver.recv().await {
        let response = response?;
        println!("Streaming: got blocks up to {}", response.next_block);
    }

    Ok(())
}

Main Types

• Client - Main client for interacting with HyperSync servers
• net_types::Query - Query builder for specifying what data to fetch
• StreamConfig - Configuration for streaming operations
• QueryResponse - Response containing blocks, transactions, logs, and traces
• ArrowResponse - Response in Apache Arrow format for high-performance processing

Authentication

You’ll need a HyperSync API token to access the service. Get one from https://envio.dev/app/api-tokens.

Examples

See the examples/ directory for more detailed usage patterns including:

• ERC20 token transfers
• Wallet transaction history
• Event decoding and filtering
• Real-time data streaming

Re-exports

pub use hypersync_format as format;

pub use hypersync_net_types as net_types;

pub use hypersync_schema as schema;

Modules

arrow_reader

Reader types for reading Arrow record batch data as native Rust types.

preset_query

Preset queries for common use cases.

simple_types

Base object types for the Hypersync client.

Structs

ArrowResponseData

Query response in Arrow format

CallDecoder

Decode input data parsing input data.

Client

Client to handle http requests and retries.

ClientBuilder

Builder for creating a hypersync client with configuration options.

ClientConfig

Configuration for the hypersync client.

ColumnMapping

Column mapping for stream function output. It lets you map columns you want into the DataTypes you want.

Decoder

Decode logs parsing topics and log data.

QueryResponse

Query response from hypersync instance. Contain next_block field in case query didn’t process all the block range

StreamConfig

Config for hypersync event streaming.

Enums

DataType

DataType is an enumeration representing the different data types that can be used in the column mapping. Each variant corresponds to a specific data type.

HeightStreamEvent

Events emitted by the height stream.

HexOutput

Determines format of Binary column

SerializationFormat

Determines query serialization format for HTTP requests.

Type Aliases

ArrowResponse

Alias for Arrow Query response