From 9fba33073ee4daa20612d06b0434c7d82abea46d Mon Sep 17 00:00:00 2001 From: Jono Prest Date: Thu, 26 Mar 2026 15:05:47 +0000 Subject: [PATCH 1/7] Use include_str! to source lib.rs docs from README.md Replace the inline doc comment in lib.rs with `#![doc = include_str!("../../README.md")]` so the crate documentation is sourced directly from the README. Also update the README with information that was previously only in the lib.rs doc comment: - Added Parquet format support to features - Added real-time updates (SSE) and production-ready features - Added Main Types section with links to key structs Co-authored-by: claude --- README.md | 12 +++++- hypersync-client/src/lib.rs | 74 +------------------------------------ 2 files changed, 12 insertions(+), 74 deletions(-) diff --git a/README.md b/README.md index 7a9d0ae..41c169a 100644 --- a/README.md +++ b/README.md @@ -15,12 +15,14 @@ If you need a full indexing framework on top of HyperSync with GraphQL APIs and ## Features - **Maximum performance**: Direct Rust implementation with no FFI overhead -- **Arrow format support**: Stream blockchain data as Apache Arrow record batches for in-memory analytics +- **Arrow and Parquet format support**: Stream blockchain data as Apache Arrow record batches for in-memory analytics, or write directly to Parquet files - **Binary transport**: Uses CapnProto serialization to minimize bandwidth and maximize throughput - **Flexible queries**: Filter logs, transactions, blocks, and traces with granular control - **Field selection**: Choose exactly which fields to return, reducing unnecessary data transfer - **Automatic pagination**: Handles large datasets with built-in pagination - **Event decoding**: Decode ABI-encoded event data directly in the stream +- **Real-time updates**: Live height streaming via Server-Sent Events +- **Production ready**: Built-in rate limiting, automatic retries, and error handling - **Async/await**: Built on Tokio for fully asynchronous operation - **70+ networks**: Access any [HyperSync-supported network](https://docs.envio.dev/docs/HyperSync/hypersync-supported-networks) @@ -91,6 +93,14 @@ async fn main() -> anyhow::Result<()> { See the [examples directory](./examples) for more usage patterns including wallet transactions, block streaming, and decoded event output. +## Main Types + +- [`Client`](https://docs.rs/hypersync-client/latest/hypersync_client/struct.Client.html) - Main client for interacting with HyperSync servers +- [`net_types::Query`](https://docs.rs/hypersync-client/latest/hypersync_net_types/struct.Query.html) - Query builder for specifying what data to fetch +- [`StreamConfig`](https://docs.rs/hypersync-client/latest/hypersync_client/struct.StreamConfig.html) - Configuration for streaming operations +- [`QueryResponse`](https://docs.rs/hypersync-client/latest/hypersync_client/struct.QueryResponse.html) - Response containing blocks, transactions, logs, and traces +- [`ArrowResponse`](https://docs.rs/hypersync-client/latest/hypersync_client/struct.ArrowResponse.html) - Response in Apache Arrow format for high-performance processing + ## Connecting to Different Networks Change the `chain_id` (or use `url`) to connect to any supported network: diff --git a/hypersync-client/src/lib.rs b/hypersync-client/src/lib.rs index 4302a7b..ef32485 100644 --- a/hypersync-client/src/lib.rs +++ b/hypersync-client/src/lib.rs @@ -1,77 +1,5 @@ #![deny(missing_docs)] -//! # 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 -//! -//! ```no_run -//! 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](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 +#![doc = include_str!("../../README.md")] use std::time::Instant; use std::{sync::Arc, time::Duration}; From 0b23e09cbca9fba034b3fd608429f3d9cdb5dbb0 Mon Sep 17 00:00:00 2001 From: Jono Prest Date: Thu, 26 Mar 2026 15:54:49 +0000 Subject: [PATCH 2/7] Use simpler Quick Start example from original lib.rs docs Replace the stream_arrow example with the original get/stream example that shows both one-shot and streaming usage without SerializationFormat config. Add explanatory comments for the USDC address and Transfer topic. Co-authored-by: claude --- README.md | 47 ++++++++++++++++++++++------------------------- 1 file changed, 22 insertions(+), 25 deletions(-) diff --git a/README.md b/README.md index 41c169a..31db450 100644 --- a/README.md +++ b/README.md @@ -47,44 +47,41 @@ export ENVIO_API_TOKEN="your-token-here" ## Quick Start -Stream all ERC-20 Transfer events from Ethereum mainnet: +Query ERC-20 Transfer events from USDC on Ethereum mainnet: ```rust -use hypersync_client::{ - net_types::{LogField, LogFilter, Query}, - Client, SerializationFormat, StreamConfig, -}; +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) // Ethereum mainnet + .chain_id(1) .api_token(std::env::var("ENVIO_API_TOKEN")?) - .serialization_format(SerializationFormat::CapnProto { - should_cache_queries: true, - }) .build()?; + // Query ERC-20 Transfer events from USDC contract let query = Query::new() - .from_block(0) + .from_block(19000000) + .to_block_excl(19001000) .where_logs( - LogFilter::all().and_topic0([ + LogFilter::all() + // USDC contract address + .and_address(["0xA0b86a33E6411b87Fd9D3DF822C8698FC06BBe4c"])? // ERC-20 Transfer event signature - "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef", - ])?, + .and_topic0(["0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"])? ) - .select_log_fields([ - LogField::Data, - LogField::Topic0, - LogField::Topic1, - LogField::Topic2, - ]); - - let mut receiver = client.stream_arrow(query, StreamConfig::default()).await?; - - while let Some(batch) = receiver.recv().await { - let batch = batch?; - println!("Received {} logs", batch.data.logs.len()); + .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(()) From 360c01506c40bd2b14352d2ff9ba6d074985678e Mon Sep 17 00:00:00 2001 From: Jono Prest Date: Thu, 26 Mar 2026 15:56:06 +0000 Subject: [PATCH 3/7] Format select_log_fields on multiple lines in Quick Start example Co-authored-by: claude --- README.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 31db450..12447ba 100644 --- a/README.md +++ b/README.md @@ -71,7 +71,12 @@ async fn main() -> anyhow::Result<()> { // ERC-20 Transfer event signature .and_topic0(["0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"])? ) - .select_log_fields([LogField::Address, LogField::Topic1, LogField::Topic2, LogField::Data]); + .select_log_fields([ + LogField::Address, + LogField::Topic1, + LogField::Topic2, + LogField::Data, + ]); // Get all data in one response let response = client.get(&query).await?; From a14f78423bd4706eb62100b1ed6282aef6c5a3f6 Mon Sep 17 00:00:00 2001 From: Jono Prest Date: Thu, 26 Mar 2026 15:57:44 +0000 Subject: [PATCH 4/7] Use Data and Topic0-2 fields in Quick Start example Co-authored-by: claude --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 12447ba..c038313 100644 --- a/README.md +++ b/README.md @@ -72,10 +72,10 @@ async fn main() -> anyhow::Result<()> { .and_topic0(["0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"])? ) .select_log_fields([ - LogField::Address, + LogField::Data, + LogField::Topic0, LogField::Topic1, LogField::Topic2, - LogField::Data, ]); // Get all data in one response From 7b8a208f03ddfb9e0e9cacd3e4fefa3470acf1ff Mon Sep 17 00:00:00 2001 From: Jono Prest Date: Thu, 26 Mar 2026 15:59:44 +0000 Subject: [PATCH 5/7] Query from block 0 with no upper bound in Quick Start example Co-authored-by: claude --- README.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/README.md b/README.md index c038313..7ee2365 100644 --- a/README.md +++ b/README.md @@ -62,8 +62,7 @@ async fn main() -> anyhow::Result<()> { // Query ERC-20 Transfer events from USDC contract let query = Query::new() - .from_block(19000000) - .to_block_excl(19001000) + .from_block(0) .where_logs( LogFilter::all() // USDC contract address From 03cc4b281a2fbce47c00c214b140cce1b3bfe61a Mon Sep 17 00:00:00 2001 From: Jono Prest Date: Thu, 26 Mar 2026 16:01:00 +0000 Subject: [PATCH 6/7] Fix broken intra-doc links in QueryResponseWithRateLimit Use crate::Client path so rustdoc can resolve the links from types.rs. Co-authored-by: claude --- hypersync-client/src/types.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/hypersync-client/src/types.rs b/hypersync-client/src/types.rs index ca3b376..a9b5cc9 100644 --- a/hypersync-client/src/types.rs +++ b/hypersync-client/src/types.rs @@ -127,7 +127,7 @@ pub type EventResponse = QueryResponse>; /// Response that includes rate limit information from the server. /// -/// Returned by [`Client::get_with_rate_limit`] and [`Client::get_arrow_with_rate_limit`]. +/// Returned by [`crate::Client::get_with_rate_limit`] and [`crate::Client::get_arrow_with_rate_limit`]. /// Use this when you need to inspect rate limit headers for external monitoring or /// coordination across systems. #[derive(Debug, Clone)] From 19bfc0e22f92c4bb0d2385433f6fffbfbd370e74 Mon Sep 17 00:00:00 2001 From: Jono Prest Date: Thu, 26 Mar 2026 16:03:15 +0000 Subject: [PATCH 7/7] Add prominent docs.rs link below intro in README Co-authored-by: claude --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index 7ee2365..55974e5 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,8 @@ Rust crate for [Envio's](https://envio.dev) HyperSync client. The most performant way to access HyperSync, with direct access to the underlying Rust implementation and no FFI overhead. +[Full API documentation on docs.rs](https://docs.rs/hypersync-client) + ## What is HyperSync? [HyperSync](https://docs.envio.dev/docs/HyperSync/overview) is Envio's high-performance blockchain data retrieval layer. It is a purpose-built alternative to JSON-RPC endpoints, offering up to 2000x faster data access across 70+ EVM-compatible networks and Fuel.