### Run Height Stream Example

Source: https://github.com/enviodev/hypersync-client-rust/blob/main/examples/height_stream/README.md

Execute the height stream example with different logging levels. Use RUST_LOG=debug for detailed logs including keepalive pings, or RUST_LOG=trace for all received SSE bytes.

```bash
cargo run -p height_stream
```

```bash
RUST_LOG=debug cargo run -p height_stream
```

```bash
RUST_LOG=trace cargo run -p height_stream
```

--------------------------------

### tune_stream Example

Source: https://github.com/enviodev/hypersync-client-rust/blob/main/docs/STREAMING.md

A standalone runnable example that allows users to test different streaming configurations against a given query and compare their performance based on summary metrics.

```APIDOC
## Tuning Tool (`examples/tune_stream`)

### Description
A command-line tool to evaluate and compare the performance of various streaming configurations. It runs a specified query with a grid of configurations and outputs a comparison table of summary metrics.

### Usage
1. Provide a query in JSON format.
2. Specify a block range.
3. Provide a grid of configurations (varying `response_bytes_target`, `concurrency`, `max_batch_size`, `max_buffered_bytes`).

### Features
- **Comparison Table**: Displays summary metrics (e.g., throughput, size-vs-target, truncation rate) for each tested configuration.
- **Single-Run Mode**: Prints the report for one specific configuration.
- **Ad-hoc Inspection**: With a debug flag, logs detailed `RequestStats` per request.
```

--------------------------------

### LogFilter Example

Source: https://github.com/enviodev/hypersync-client-rust/blob/main/_autodocs/api-reference/query.md

Demonstrates how to create and configure a LogFilter using its builder methods to specify address and topic filters.

```rust
let filter = LogFilter::all()
    .and_address(["0xA0b86a33E6411b87Fd9D3DF822C8698FC06BBe4c"])
    .and_topic0(["0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"])?;
```

--------------------------------

### tune_stream Example Usage

Source: https://github.com/enviodev/hypersync-client-rust/blob/main/docs/STREAMING.md

A standalone Rust example for tuning Hypersync stream configurations. It runs a given query with a grid of configurations and compares summary metrics to identify optimal settings.

```rust
examples/tune_stream
```

--------------------------------

### Create ClientBuilder with Defaults

Source: https://github.com/enviodev/hypersync-client-rust/blob/main/_autodocs/api-reference/client.md

Creates a new ClientBuilder with default configuration. Use this as a starting point for fluent API configuration.

```rust
pub fn builder() -> ClientBuilder
```

--------------------------------

### Usage Example for StreamMetrics

Source: https://github.com/enviodev/hypersync-client-rust/blob/main/_autodocs/types.md

Demonstrates how to create, use, and retrieve metrics from a `StreamMetrics` collector during an asynchronous stream operation.

```rust
let metrics = Arc::new(StreamMetrics::new());
let mut receiver = client.stream_arrow_with_observer(query, config, metrics.clone()).await?;

// During or after streaming:
let summary = metrics.summary();
println!("Streamed {} blocks in {:.2}s", summary.total_blocks, summary.wall_clock.as_secs_f64());
```

--------------------------------

### Stream Logs with Default Configuration

Source: https://github.com/enviodev/hypersync-client-rust/blob/main/_autodocs/examples.md

Streams logs using the default `StreamConfig`. This example shows how to set up the client, define a query with log filters, and process incoming log batches.

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

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

    let query = Query::new()
        .from_block(0)
        .where_logs(
            LogFilter::all()
                .and_topic0(["0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"])?
        )
        .select_log_fields([LogField::Address, LogField::Data]);

    let mut receiver = client.stream(query, StreamConfig::default()).await?;

    let mut total_logs = 0;
    while let Some(response) = receiver.recv().await {
        let response = response?;
        total_logs += response.data.logs.iter().map(|b| b.len()).sum::<usize>();
        println!("Got batch with {} logs", 
            response.data.logs.iter().map(|b| b.len()).sum::<usize>()
        );
    }

    println!("Total logs: {}", total_logs);
    Ok(())
}
```

--------------------------------

### Execute a Query and Get Native Rust Response

Source: https://github.com/enviodev/hypersync-client-rust/blob/main/_autodocs/api-reference/client.md

Use the `get` method to execute a query and retrieve results in native Rust data structures. This is suitable for general data retrieval needs.

```rust
pub async fn get(&self, query: &Query) -> Result<QueryResponse>
```

```rust
let query = Query::new()
    .from_block(19000000)
    .to_block_excl(19000010)
    .include_all_blocks()
    .select_block_fields([BlockField::Number, BlockField::Hash]);

let response = client.get(&query).await?;
println!("Retrieved {} blocks", response.data.blocks.len());
```

--------------------------------

### Example Usage of Decoder for Log Decoding

Source: https://github.com/enviodev/hypersync-client-rust/blob/main/_autodocs/types.md

Demonstrates how to instantiate a Decoder with event signatures and iterate through logs, decoding them to extract event details. This is useful for processing blockchain event data.

```rust
let decoder = Decoder::from_signatures(&[
    "Transfer(address indexed from, address indexed to, uint amount)",
    "Approve(address indexed owner, address indexed spender, uint amount)",
])?;

for log in logs {
    if let Ok(Some(decoded)) = decoder.decode_log(&log) {
        println!("Event name: {}", decoded.event.name);
        for (i, indexed) in decoded.indexed.iter().enumerate() {
            println!("  indexed {}: {}", i, indexed);
        }
        for (i, body) in decoded.body.iter().enumerate() {
            println!("  body {}: {}", i, body);
        }
    }
}

```

--------------------------------

### Get Client URL

Source: https://github.com/enviodev/hypersync-client-rust/blob/main/_autodocs/api-reference/client.md

Retrieves the configured HyperSync server URL from the client instance.

```rust
pub fn url(&self) -> &Url
```

```rust
println!("Client URL: {}", client.url());
```

--------------------------------

### Set Serialization Format to JSON

Source: https://github.com/enviodev/hypersync-client-rust/blob/main/_autodocs/api-reference/configuration.md

Example of building a client and setting the serialization format to JSON. This is useful for debugging due to its readability.

```rust
let client = Client::builder()
    .chain_id(1)
    .api_token(std::env::var("ENVIO_API_TOKEN")?)
    .serialization_format(SerializationFormat::Json)
    .build()?;

```

--------------------------------

### Event Streaming and Decoding

Source: https://github.com/enviodev/hypersync-client-rust/blob/main/_autodocs/api-reference/decoder.md

Shows how to stream events from a query and decode them in real-time. This example integrates event streaming with the decoding logic to process incoming events as they arrive.

```rust
use hypersync_client::{Client, Decoder, net_types::{Query, LogFilter, LogField}};

let mut receiver = client.stream(query, StreamConfig::default()).await?;

while let Some(response) = receiver.recv().await {
    let response = response?;
    
    for batch in response.data.logs {
        for log in batch {
            if let Ok(Some(decoded)) = decoder.decode_log(&log) {
                println!("Event: {}", decoded.event.name);
            }
        }
    }
}
```

--------------------------------

### Create Custom Stream Configuration

Source: https://github.com/enviodev/hypersync-client-rust/blob/main/_autodocs/api-reference/configuration.md

Example of creating a custom StreamConfig by manually setting fields and using `Default::default()` for unspecified options. This allows fine-grained control over streaming parameters like concurrency, batch size, and hex output format.

```rust
use hypersync_client::{StreamConfig, HexOutput};

let config = StreamConfig {
    concurrency: 15,
    batch_size: 5000,
    min_batch_size: 100,
    response_bytes_target: 600_000,
    max_buffered_bytes: Some(50_000_000),
    reverse: false,
    hex_output: HexOutput::Prefixed,
    ..Default::default()
};

let mut receiver = client.stream(query, config).await?;

```

--------------------------------

### Batch Export to Parquet with Pagination

Source: https://github.com/enviodev/hypersync-client-rust/blob/main/_autodocs/examples.md

This example demonstrates batch exporting data to Parquet files, processing data in chunks of 100,000 blocks. It dynamically generates filenames based on the block range for each batch. The `StreamConfig::archival()` method is used for default archival configuration.

```rust
for block_start in (0..1_000_000).step_by(100_000) {
    let query = Query::new()
        .from_block(block_start)
        .to_block_excl((block_start + 100_000).min(1_000_000))
        .include_all_blocks();
    
    let filename = format!("export_{}.parquet", block_start);
    client.collect_parquet(&filename, query, StreamConfig::archival()).await?;
    println!("Exported {}", filename);
}
```

--------------------------------

### get

Source: https://github.com/enviodev/hypersync-client-rust/blob/main/_autodocs/api-reference/client.md

Executes a query once and returns the response in native Rust format. This method is suitable for retrieving structured data like blocks, transactions, logs, and traces.

```APIDOC
## get

### Description
Executes a query once and returns the response in native Rust format.

### Method
`get`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```rust
let query = Query::new()
    .from_block(19000000)
    .to_block_excl(19000010)
    .include_all_blocks()
    .select_block_fields([BlockField::Number, BlockField::Hash]);

let response = client.get(&query).await?;
println!("Retrieved {} blocks", response.data.blocks.len());
```

### Response
#### Success Response
- `Result<QueryResponse>` - Response with blocks, transactions, logs, and traces

#### Response Example
(Response structure depends on the QueryResponse type)
```

--------------------------------

### Query ERC-20 Transfer Events with Hypersync Client

Source: https://github.com/enviodev/hypersync-client-rust/blob/main/hypersync-client/README.md

This example demonstrates how to query ERC-20 Transfer events from a specific contract address on Ethereum mainnet using the hypersync-client. It shows how to build a query with log filters and select specific log fields. The code includes options for retrieving all data in one response or streaming data for large ranges.

```rust
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 ERC-20 Transfer events from USDC contract
    let query = Query::new()
        .from_block(0)
        .where_logs(
            LogFilter::all()
                // USDC contract address
                .and_address(["0xA0b86a33E6411b87Fd9D3DF822C8698FC06BBe4c"])? 
                // ERC-20 Transfer event signature
                .and_topic0(["0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"])?
        )
        .select_log_fields([
            LogField::Data,
            LogField::Topic0,
            LogField::Topic1,
            LogField::Topic2,
        ]);

    // 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(())
}
```

--------------------------------

### Execute a Query and Get Apache Arrow Response

Source: https://github.com/enviodev/hypersync-client-rust/blob/main/_autodocs/api-reference/client.md

Use the `get_arrow` method to execute a query and retrieve results formatted as Apache Arrow record batches. This is efficient for large datasets and integration with data analysis tools.

```rust
pub async fn get_arrow(&self, query: &Query) -> Result<ArrowResponse>
```

```rust
let query = Query::new()
    .from_block(19000000)
    .to_block_excl(19000100)
    .include_all_blocks();

let response = client.get_arrow(&query).await?;
```

--------------------------------

### Get All Transactions for an Address

Source: https://github.com/enviodev/hypersync-client-rust/blob/main/_autodocs/examples.md

Retrieve all transactions associated with a specific address, filtering for transactions where the address is either the sender or receiver. This example selects specific transaction fields for display.

```rust
use hypersync_client::net_types::{Query, TransactionFilter, TransactionField};

let address = "0x1234567890123456789012345678901234567890";

let query = Query::new()
    .from_block(0)
    .where_transactions(
        TransactionFilter::all()
            .and_from([address])?.
or(TransactionFilter::all().and_to([address])?)
    )
    .select_transaction_fields([
        TransactionField::Hash,
        TransactionField::From,
        TransactionField::To,
        TransactionField::Value,
        TransactionField::BlockNumber,
    ]);

let response = client.collect(query, StreamConfig::sparse()).await?;

for batch in response.data.transactions {
    for tx in batch {
        println!("{:?} {} -> {} ({})",
            tx.hash,
            tx.from,
            tx.to,
            tx.value.unwrap_or_default()
        );
    }
}
```

--------------------------------

### Create Client with Config

Source: https://github.com/enviodev/hypersync-client-rust/blob/main/_autodocs/README.md

Instantiate the Client directly using a configuration object. This method is an alternative to the builder pattern.

```rust
let client = Client::new(config);
```

--------------------------------

### ClientBuilder Usage

Source: https://github.com/enviodev/hypersync-client-rust/blob/main/_autodocs/api-reference/client.md

Demonstrates how to create and configure a ClientBuilder to instantiate a Hypersync client.

```APIDOC
## Client::builder()

### Description
Creates a new `ClientBuilder` with default configuration using a fluent API.

### Method
Rust function call

### Signature
`pub fn builder() -> ClientBuilder`

### Returns
- `ClientBuilder` - A builder for configuring the client.

### Example
```rust
let client = Client::builder()
    .chain_id(1)
    .api_token(std::env::var("ENVIO_API_TOKEN")?)
    .build()?;
```
```

--------------------------------

### Create a New HyperSync Client

Source: https://github.com/enviodev/hypersync-client-rust/blob/main/_autodocs/api-reference/client.md

Instantiate a new HyperSync client using the `Client::new` function. Ensure your `ClientConfig` includes a valid URL and API token. The `api_token` is typically retrieved from environment variables.

```rust
use hypersync_client::{Client, ClientConfig};

let config = ClientConfig {
    url: "https://eth.hypersync.xyz".to_string(),
    api_token: std::env::var("ENVIO_API_TOKEN")?,
    ..Default::default()
};
let client = Client::new(config)?;
```

--------------------------------

### Get Current Block Height

Source: https://github.com/enviodev/hypersync-client-rust/blob/main/_autodocs/api-reference/client.md

Fetches the current block height from the server. This operation is designed with retries.

```rust
pub async fn get_height(&self) -> Result<u64>
```

```rust
let height = client.get_height().await?;
println!("Current block height: {}", height);
```

--------------------------------

### Get Chain ID from Server

Source: https://github.com/enviodev/hypersync-client-rust/blob/main/_autodocs/api-reference/client.md

Retrieves the chain ID from the server. This method includes retries for robustness.

```rust
pub async fn get_chain_id(&self) -> Result<u64>
```

```rust
let chain_id = client.get_chain_id().await?;
println!("Connected to chain ID: {}", chain_id);
```

--------------------------------

### Create Hypersync Client Configuration

Source: https://github.com/enviodev/hypersync-client-rust/blob/main/_autodocs/api-reference/configuration.md

Instantiate `ClientConfig` with custom settings for URL, API token, timeouts, retries, and serialization format. Ensure all required fields are provided and values meet validation criteria.

```rust
use hypersync_client::{Client, ClientConfig, SerializationFormat};

let config = ClientConfig {
    url: "https://eth.hypersync.xyz".to_string(),
    api_token: "00000000-0000-0000-0000-000000000000".to_string(),
    http_req_timeout_millis: 60_000,
    max_num_retries: 5,
    retry_backoff_ms: 1000,
    retry_base_ms: 500,
    retry_ceiling_ms: 10_000,
    serialization_format: SerializationFormat::Json,
    proactive_rate_limit_sleep: true,
};

let client = Client::new(config)?;
```

--------------------------------

### Connect to Different Networks with HyperSync Client

Source: https://github.com/enviodev/hypersync-client-rust/blob/main/hypersync-client/README.md

Demonstrates how to build a HyperSync client instance for different networks using `chain_id` or a direct `url`. Requires an API token to be set as an environment variable.

```rust
use hypersync_client::Client;

# fn main() -> anyhow::Result<()> {
let api_token = std::env::var("ENVIO_API_TOKEN")?;

// Arbitrum
Client::builder().chain_id(42161).api_token(&api_token).build()?;

// Base
Client::builder().chain_id(8453).api_token(&api_token).build()?;

// Or use the URL directly
Client::builder().url("https://eth.hypersync.xyz").api_token(&api_token).build()?;
# Ok(())
# }
```

--------------------------------

### Initialize HyperSync Client with API Token

Source: https://github.com/enviodev/hypersync-client-rust/blob/main/_autodocs/api-reference/configuration.md

Build the HyperSync client in Rust, reading the API token from the environment variable. Ensure the `ENVIO_API_TOKEN` is set before running.

```rust
let client = Client::builder()
    .chain_id(1)
    .api_token(std::env::var("ENVIO_API_TOKEN")?)
    .build()?;
```

--------------------------------

### get_height

Source: https://github.com/enviodev/hypersync-client-rust/blob/main/_autodocs/api-reference/client.md

Gets the current block height from the server with retries. This method is essential for monitoring the latest state of the blockchain.

```APIDOC
## get_height

### Description
Gets the current block height from the server with retries.

### Method
Rust SDK method

### Signature
`get_height(&self) -> Result<u64>`

### Returns
`Result<u64>` - The current block height

### Example
```rust
let height = client.get_height().await?;
println!("Current block height: {}", height);
```
```

--------------------------------

### Block Range Methods

Source: https://github.com/enviodev/hypersync-client-rust/blob/main/_autodocs/api-reference/query.md

Methods for setting the block range for the query. You can specify a start block and an exclusive end block.

```APIDOC
## Query::from_block(block: u64)

### Description
Sets the starting block (inclusive) for the query.

### Method
`from_block(block: u64) -> Self`

### Parameters
#### Path Parameters
- **block** (u64) - Required - Block number to start from (inclusive)

### Example
```rust
let query = Query::new().from_block(19000000);
```
```

```APIDOC
## Query::to_block(block: u64)

### Description
Sets the ending block (exclusive) for the query.

### Method
`to_block(block: u64) -> Self`

### Parameters
#### Path Parameters
- **block** (u64) - Required - Block number to end at (exclusive)

### Example
```rust
let query = Query::new().to_block(19001000);
```
```

```APIDOC
## Query::to_block_excl(block: u64)

### Description
Sets the ending block (exclusive) for the query. This is equivalent to `to_block()`.

### Method
`to_block_excl(block: u64) -> Self`

### Parameters
#### Path Parameters
- **block** (u64) - Required - Block number to end at (exclusive)

### Example
```rust
let query = Query::new().to_block_excl(19001000);
```
```

--------------------------------

### Set Block Range

Source: https://github.com/enviodev/hypersync-client-rust/blob/main/_autodocs/api-reference/query.md

Defines the start (inclusive) and end (exclusive) block numbers for the query. `to_block_excl` is equivalent to `to_block`.

```rust
pub fn from_block(mut self, from_block: u64) -> Self
```

```rust
pub fn to_block(mut self, to_block: u64) -> Self
```

```rust
pub fn to_block_excl(mut self, to_block: u64) -> Self
```

--------------------------------

### Create Client with Builder

Source: https://github.com/enviodev/hypersync-client-rust/blob/main/_autodocs/README.md

Instantiate the Client using its builder pattern. This is a common entry point for managing HTTP connections, retries, and rate limiting.

```rust
let client = Client::builder().build();
```

--------------------------------

### Configuration - ClientConfig

Source: https://github.com/enviodev/hypersync-client-rust/blob/main/_autodocs/README.md

Configuration settings for initializing the HyperSync client, including connection details and timeouts.

```APIDOC
## Client Configuration (`ClientConfig`)

### Description
Defines the settings used to initialize and configure the `Client` instance, controlling aspects like connection parameters and request timeouts.

### Settings
- Client initialization settings.
```

--------------------------------

### Block Struct Definition

Source: https://github.com/enviodev/hypersync-client-rust/blob/main/_autodocs/README.md

Defines the structure of a Block object, including its number, hash, and timestamp. This is an example of the type system documentation.

```rust
pub struct Block {
    pub number: Option<u64>,
    pub hash: Option<Hash>,
    pub timestamp: Option<u64>,
    // ...
}
```

--------------------------------

### Initialize New Query

Source: https://github.com/enviodev/hypersync-client-rust/blob/main/_autodocs/api-reference/query.md

Creates a new query with default settings. Use methods like `from_block` and `to_block_excl` to set the block range.

```rust
pub fn new() -> Self
```

```rust
let query = Query::new()
    .from_block(19000000)
    .to_block_excl(19001000);
```

--------------------------------

### get_chain_id

Source: https://github.com/enviodev/hypersync-client-rust/blob/main/_autodocs/api-reference/client.md

Gets the chain ID from the server with retries. This method is useful for verifying the connected chain and ensuring proper client configuration.

```APIDOC
## get_chain_id

### Description
Gets the chain ID from the server with retries.

### Method
Rust SDK method

### Signature
`get_chain_id(&self) -> Result<u64>`

### Returns
`Result<u64>` - The chain ID

### Example
```rust
let chain_id = client.get_chain_id().await?;
println!("Connected to chain ID: {}", chain_id);
```
```

--------------------------------

### Client::new

Source: https://github.com/enviodev/hypersync-client-rust/blob/main/_autodocs/api-reference/client.md

Initializes a new HyperSync client with the provided configuration. This client is the primary interface for interacting with HyperSync servers, managing connections, retries, and rate limiting.

```APIDOC
## Client::new

### Description
Creates a new client with the given configuration. This client manages HTTP connections, retries, rate limiting, and provides methods for querying HyperSync servers.

### Method Signature
`Client::new(config: ClientConfig) -> Result<Client>`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters Table
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `config` | `ClientConfig` | Yes | Configuration with URL and API token |

### Returns
`Result<Client>` - The configured client or validation error.

### Errors
- `invalid ClientConfig` if config validation fails (empty URL, malformed URL, missing/invalid API token, zero timeout)

### Example
```rust
use hypersync_client::{Client, ClientConfig};

let config = ClientConfig {
    url: "https://eth.hypersync.xyz".to_string(),
    api_token: std::env::var("ENVIO_API_TOKEN")?,
    ..Default::default()
};
let client = Client::new(config)?;
```
```

--------------------------------

### Paginate Large Block Ranges Manually

Source: https://github.com/enviodev/hypersync-client-rust/blob/main/_autodocs/examples.md

Use `next_block` to paginate through large block ranges when fetching data. This example fetches data in chunks of 100,000 blocks.

```rust
let mut from_block = 0;
let to_block = 1_000_000;
let mut all_response = Vec::new();

loop {
    let query = Query::new()
        .from_block(from_block)
        .to_block_excl((from_block + 100_000).min(to_block));
    
    let response = client.get(&query).await?;
    
    println!("Got {} logs from {} to {}", 
        response.data.logs.iter().map(|b| b.len()).sum::<usize>(),
        from_block,
        response.next_block
    );
    
    all_response.extend(response.data.logs);
    from_block = response.next_block;
    
    if from_block >= to_block {
        break;
    }
}
```

--------------------------------

### Build Client Instance

Source: https://github.com/enviodev/hypersync-client-rust/blob/main/_autodocs/api-reference/client.md

Finalizes the client configuration and attempts to build a `Client` instance. This method returns a `Result` which may contain an error if configuration is invalid (e.g., missing URL or API token).

```rust
pub fn build(self) -> Result<Client>
```

--------------------------------

### Using StreamMetrics with a Streaming Query

Source: https://github.com/enviodev/hypersync-client-rust/blob/main/_autodocs/api-reference/streaming-metrics.md

Demonstrates how to instantiate StreamMetrics, pass it to a streaming client method, and periodically check progress and final summary.

```rust
use std::sync::Arc;
use hypersync_client::{Client, StreamMetrics};

let metrics = Arc::new(StreamMetrics::new());
let mut receiver = client.stream_arrow_with_observer(
    query,
    config,
    metrics.clone()
).await?;

while let Some(response) = receiver.recv().await {
    // Process response
    let summary = metrics.summary();
    println!("Progress: {} blocks in {:.2}s", 
        summary.total_blocks, 
        summary.wall_clock.as_secs_f64()
    );
}

let final_summary = metrics.summary();
println!("Total: {} blocks, {} bytes, {} requests", 
    final_summary.total_blocks, 
    final_summary.total_bytes, 
    final_summary.num_requests
);
```

--------------------------------

### Get Rate Limit Info

Source: https://github.com/enviodev/hypersync-client-rust/blob/main/_autodocs/api-reference/client.md

Retrieves the most recent rate limit information observed from any request. This is useful for monitoring API usage and understanding current rate limit status.

```rust
pub fn rate_limit_info(&self) -> Option<RateLimitInfo>
```

--------------------------------

### Client Constructor and Builder

Source: https://github.com/enviodev/hypersync-client-rust/blob/main/_autodocs/INDEX.md

Methods for creating and configuring a new HyperSync client instance using either a direct constructor or a fluent builder pattern.

```APIDOC
## Client Constructor & Builder

### Description
Instantiate the HyperSync client. You can either create a client directly using `Client::new(config)` with a `ClientConfig` struct, or use the more flexible `Client::builder()` to configure the client fluently.

### Methods
- `Client::new(config: ClientConfig)`: Creates a new client instance with the provided configuration.
- `Client::builder()`: Returns a new `ClientBuilder` to configure the client step-by-step.

### Builder Methods
- `chain_id(id: u64)`: Sets the chain ID for the client.
- `url(url: &str)`: Sets the HyperSync server URL.
- `api_token(token: &str)`: Sets the API token for authentication.
- `timeouts(connect: Duration, read: Duration)`: Configures connection and read timeouts.
- `retries(max_attempts: u32, initial_interval: Duration)`: Sets the retry strategy for requests.
- `serialization(format: SerializationFormat)`: Specifies the serialization format for requests and responses.
```

--------------------------------

### health_check

Source: https://github.com/enviodev/hypersync-client-rust/blob/main/_autodocs/api-reference/client.md

Performs a health check by getting the height without retries, allowing for a quick and direct status verification. An optional timeout can be provided to override the default HTTP request duration.

```APIDOC
## health_check

### Description
Performs a health check by getting the height without retries.

### Method
Rust SDK method

### Signature
`health_check(&self, http_req_timeout: Option<Duration>) -> Result<u64>`

### Parameters
#### Path Parameters
- `http_req_timeout` (Option<Duration>) - Optional - Override the default HTTP timeout

### Returns
`Result<u64>` - The current block height

### Example
```rust
let height = client.health_check(Some(Duration::from_secs(5))).await?;
```
```

--------------------------------

### Get Arrow Response with Hypersync Client

Source: https://github.com/enviodev/hypersync-client-rust/blob/main/_autodocs/examples.md

Retrieves data in Arrow format for direct columnar processing with Arrow libraries. This is efficient for large datasets and integration with data analysis tools.

```rust
use hypersync_client::Client;

let response = client.get_arrow(&query).await?;

// Work with Arrow RecordBatches directly
for batch in &response.data.logs {
    println!("Batch has {} rows", batch.num_rows());
    // Process with Arrow/Polars/etc
}
```

--------------------------------

### Custom StreamObserver Implementation

Source: https://github.com/enviodev/hypersync-client-rust/blob/main/_autodocs/api-reference/streaming-metrics.md

Implement the `StreamObserver` trait to create custom metric collection logic. This example tracks total requests, the slowest request duration, and logs truncated requests and in-flight/buffered data.

```rust
use hypersync_client::{StreamObserver, RequestStats, StreamSummary};
use std::sync::atomic::{AtomicU64, Ordering};

struct MyMetrics {
    total_requests: AtomicU64,
    slowest_request_ms: AtomicU64,
}

impl StreamObserver for MyMetrics {
    fn on_request(&self, stats: &RequestStats) {
        self.total_requests.fetch_add(1, Ordering::Relaxed);
        
        let duration_ms = stats.duration.as_millis() as u64;
        self.slowest_request_ms
            .fetch_max(duration_ms, Ordering::Relaxed);
        
        if stats.truncated {
            println!("Request truncated: {} -> {} blocks", 
                stats.requested_blocks, 
                stats.actual_blocks
            );
        }
    }

    fn on_progress(&self, in_flight: u64, buffered_bytes: u64) {
        if in_flight > 0 {
            println!("In-flight: {}, Buffered: {} MB", 
                in_flight, 
                buffered_bytes / 1_000_000
            );
        }
    }

    fn on_finish(&self, summary: &StreamSummary) {
        println!("Stream finished: {} requests in {:.2}s",
            summary.num_requests,
            summary.wall_clock.as_secs_f64()
        );
    }
}

let observer = MyMetrics {
    total_requests: AtomicU64::new(0),
    slowest_request_ms: AtomicU64::new(0),
};

let metrics = Arc::new(observer);
let mut receiver = client.stream_arrow_with_observer(query, config, metrics).await?;

while let Some(response) = receiver.recv().await {
    // Process response
}

```

--------------------------------

### StreamConfig Workload Presets

Source: https://github.com/enviodev/hypersync-client-rust/blob/main/docs/STREAMING.md

Demonstrates the constructors for common streaming workload configurations, each utilizing the adaptive default for max_buffered_bytes.

```rust
StreamConfig::dense() // busy contracts / all-logs; higher concurrency (20), default target.
StreamConfig::sparse() // rare events over wide ranges; moderate concurrency with a larger batch_size (high concurrency just fragments sparse regions into more requests).
StreamConfig::archival() // full block+tx pulls; modest concurrency, leaning on the adaptive buffer (the real lever for byte-heavy streams).
```

--------------------------------

### Create Default Stream Configuration

Source: https://github.com/enviodev/hypersync-client-rust/blob/main/_autodocs/api-reference/configuration.md

Demonstrates creating a default StreamConfig for basic streaming operations. This configuration uses default values for all fields.

```rust
use hypersync_client::StreamConfig;

let config = StreamConfig::default();
let mut receiver = client.stream(query, config).await?;

while let Some(response) = receiver.recv().await {
    // Handle response
}

```

--------------------------------

### Query with Exclusions

Source: https://github.com/enviodev/hypersync-client-rust/blob/main/_autodocs/api-reference/query.md

Demonstrates how to construct a query that includes specific log filters while excluding logs from a particular contract address. Requires importing `Query`, `LogFilter`, and `Selection`.

```rust
use hypersync_client::net_types::{Query, LogFilter, Selection};

let query = Query::new()
    .from_block(18000000)
    .to_block_excl(18001000)
    .where_logs(
        Selection::new(
            LogFilter::all()
                .and_topic0(["0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"])
        )
        .and_not(
            LogFilter::all()
                .and_address(["0xproblematic_contract"])
        )
    );
```

--------------------------------

### Execute a Query and Get Joined Events

Source: https://github.com/enviodev/hypersync-client-rust/blob/main/_autodocs/api-reference/client.md

Use the `get_events` method to execute a query and retrieve joined events, including associated blocks, transactions, and logs. This method is useful for analyzing event data across different blockchain entities.

```rust
pub async fn get_events(&self, mut query: Query) -> Result<EventResponse>
```

```rust
let query = Query::new()
    .from_block(19000000)
    .to_block_excl(19000010)
    .where_logs(LogFilter::all()
        .and_topic0(["0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"])?)
    .select_log_fields([LogField::Address, LogField::Data])
    .select_transaction_fields([TransactionField::Hash, TransactionField::From]);

let response = client.get_events(query).await?;
```

--------------------------------

### Connect to Base Network

Source: https://github.com/enviodev/hypersync-client-rust/blob/main/_autodocs/examples.md

Configure the Hypersync client to connect to the Base network by setting the chain ID. Ensure your API token is set in the environment.

```rust
let client = Client::builder()
    .chain_id(8453)  // Base
    .api_token(std::env::var("ENVIO_API_TOKEN")?)
    .build()?;
```

--------------------------------

### Get Joined Events with Hypersync Client

Source: https://github.com/enviodev/hypersync-client-rust/blob/main/_autodocs/examples.md

Fetches joined event data within a specified block range. Requires setting up a Query with filters and selected fields. The response contains event logs, transaction details, and block information.

```rust
use hypersync_client::{Client, net_types::{Query, LogFilter, LogField, TransactionField}};

let query = Query::new()
    .from_block(19000000)
    .to_block_excl(19000010)
    .where_logs(
        LogFilter::all()
            .and_topic0(["0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"])?
    )
    .select_log_fields([LogField::Address, LogField::Data])
    .select_transaction_fields([TransactionField::Hash, TransactionField::From]);

let response = client.get_events(query).await?;

for event in &response.data {
    println!("Log at: {:?}", event.log.address);
    println!("Transaction: {:?}", event.transaction.as_ref().map(|t| &t.hash));
    println!("Block: {:?}", event.block.as_ref().map(|b| b.number));
}
```

--------------------------------

### Query Constructor

Source: https://github.com/enviodev/hypersync-client-rust/blob/main/_autodocs/api-reference/query.md

Creates a new query with default settings. You can then chain methods to configure the query.

```APIDOC
## Query::new()

### Description
Creates a new query with defaults (from_block = 0, all other fields default).

### Method
`Query::new()`

### Parameters
None

### Response
- `Self`: A new `Query` instance with default values.

### Example
```rust
let query = Query::new()
    .from_block(19000000)
    .to_block_excl(19001000);
```
```

--------------------------------

### Add Hypersync Client to Cargo.toml

Source: https://github.com/enviodev/hypersync-client-rust/blob/main/hypersync-client/README.md

Include the hypersync-client and tokio dependencies in your Cargo.toml file. Ensure tokio is configured with the 'full' feature for comprehensive async support.

```toml
[dependencies]
hypersync-client = "1"
tokio = { version = "1", features = ["full"] }
anyhow = "1"
```

--------------------------------

### Decoder - Initialization and Usage

Source: https://github.com/enviodev/hypersync-client-rust/blob/main/_autodocs/README.md

Methods for initializing the decoder from event signatures and decoding event logs with type parsing.

```APIDOC
## Event Log Decoder

### Description
Enables the decoding of event logs by initializing with event signatures and parsing typed event parameters.

### Methods
- Initialize from event signatures.
- Decode logs with type parsing.
- Extracting typed event parameters.
```

--------------------------------

### Configure Sparse Streaming

Source: https://github.com/enviodev/hypersync-client-rust/blob/main/_autodocs/README.md

Set up streaming behavior with moderate concurrency, suitable for scenarios where events are less frequent.

```rust
let config = StreamConfig::sparse();
```

--------------------------------

### Build a Query

Source: https://github.com/enviodev/hypersync-client-rust/blob/main/_autodocs/README.md

Construct a query to fetch specific data. This involves defining the block range, filters, selected fields, and response limits.

```rust
let query = Query::new()
    .from_block(100)
    .to_block(200)
    .where_logs("0x...")
    .select_log_fields(vec!["field1", "field2"])
    .max_num_logs(100);
```

--------------------------------

### Rust Scheduler Algorithm Pseudocode

Source: https://github.com/enviodev/hypersync-client-rust/blob/main/docs/STREAMING.md

Outlines the scheduler's main loop for filling the pipeline, handling completions, and draining contiguous deliveries, including logic for backpressure and dynamic upper bounds.

```text
seed:
  open_ended  = query.to_block.is_none()
  upper_bound = query.to_block, else archive height (fast-track resp / initial get_height())
  delivered_up_to = frontier = fast_track.next_block
  holes = { frontier : upper_bound }         # one frontier hole
  last_density = None                        # → first wave uses config.batch_size

loop:
  # (a) fill the pipeline
  while in_flight.len() < concurrency:
      H = holes.first()                      # lowest start first → critical path before look-ahead
      if H is None: break
      # consumer backpressure: once the undelivered buffer is full, pause *look-ahead* fetches.
      # The hole at the watermark (H.start == delivered_up_to) is always allowed — it is the
      # data delivery is waiting on, so exempting it serves the consumer AND avoids deadlock.
      if H.start != delivered_up_to and buffered_bytes >= max_buffered_bytes:
          break
      blocks  = project_blocks(anchor_below(H.start))   # §7
      req_end = min(H.start + blocks, H.end) # cap at next chunk's start / upper_bound
      move [H.start, req_end) : holes → in_flight ; shrink/remove H ; bump frontier
      spawn fetch(H.start, req_end)          # ONE get_arrow_with_size, then map_responses

  if in_flight.is_empty() and holes.is_empty():
      break                                  # done (bounded: hit to_block; open-ended: caught up)

  # (b) take one completion
  r = in_flight.join_next().await
  completed.insert(r.start, CompletedChunk { r.next_block, r.size_bytes, r.resp })
  buffered_bytes += r.size_bytes
  if r.next_block < r.req_end:               # truncated → residual gap
      insert/merge hole [r.next_block, r.req_end)
  last_density = r.size_bytes / (r.next_block - r.start)
  update_warning_counter(truncated = r.next_block < r.req_end, size = r.size_bytes)   # §9
  if open_ended and r.archive_height = Some(h) and h > upper_bound:   # chain advanced mid-stream
      upper_bound = h
      extend/open the frontier hole so the top hole reaches upper_bound

  # (c) drain contiguous deliveries
  while let Some(c) = completed.first() where c.start == delivered_up_to:
      c = completed.pop_first()
      buffered_bytes -= c.size_bytes         # leaves the reorder buffer (enters the channel)
      tx.send(Ok(c.resp)).await              # consumer backpressure pauses the whole loop here
      delivered_up_to = c.next_block
      accumulate entity counts
      if any max_num_* exceeded: return      # close the stream
```

--------------------------------

### Basic Metrics Collection with StreamMetrics

Source: https://github.com/enviodev/hypersync-client-rust/blob/main/_autodocs/api-reference/streaming-metrics.md

Collects and prints detailed streaming metrics like block progress, throughput, and request statistics. Requires setting up a client with chain ID and API token, and defining a query range.

```rust
use std::sync::Arc;
use hypersync_client::{Client, StreamMetrics, net_types::Query};

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

    let query = Query::new()
        .from_block(0)
        .to_block_excl(1_000_000)
        .include_all_blocks();

    let metrics = Arc::new(StreamMetrics::new());
    let mut receiver = client.stream_arrow_with_observer(
        query,
        Default::default(),
        metrics.clone(),
    ).await?;

    while let Some(_response) = receiver.recv().await {
        let summary = metrics.summary();
        println!(
            "Progress: {} blocks ({:.2} blocks/sec)",
            summary.total_blocks,
            summary.blocks_per_sec
        );
    }

    let summary = metrics.summary();
    println!("\nFinal Summary:");
    println!("  Total Blocks: {}", summary.total_blocks);
    println!("  Total Bytes: {}", summary.total_bytes);
    println!("  Total Requests: {}", summary.num_requests);
    println!("  Truncated Requests: {} ({:.1}%)", 
        summary.num_truncated, 
        summary.truncation_rate * 100.0
    );
    println!("  Throughput: {:.2} blocks/sec, {:.2} MB/sec",
        summary.blocks_per_sec,
        summary.bytes_per_sec / 1_000_000.0
    );
    println!("  Density: {:.0} bytes/block", summary.mean_bytes_per_block);
    println!("  Block Range: {} - {} blocks", 
        summary.min_blocks, 
        summary.max_blocks
    );
    println!("  Max Buffer: {} MB", 
        summary.max_buffered_bytes_observed / 1_000_000
    );

    Ok(())
}

```

--------------------------------

### RateLimitInfo Methods

Source: https://github.com/enviodev/hypersync-client-rust/blob/main/_autodocs/types.md

Provides methods to check if rate limited and determine suggested wait time based on rate limit information.

```rust
impl RateLimitInfo {
    pub fn is_rate_limited(&self) -> bool
    pub fn suggested_wait_secs(&self) -> Option<u64>
}
```

--------------------------------

### Handling Client Construction Errors

Source: https://github.com/enviodev/hypersync-client-rust/blob/main/_autodocs/errors.md

Demonstrates how to catch and inspect errors during client construction, providing specific advice based on error messages.

```rust
match Client::new(config) {
    Ok(client) => { /* use client */ } 
    Err(e) => {
        eprintln!("Failed to create client: {}", e);
        if e.to_string().contains("url") {
            eprintln!("Check your HyperSync server URL");
        }
        if e.to_string().contains("api_token") {
            eprintln!("Check your API token at https://envio.dev/app/api-tokens");
        }
    }
}
```

--------------------------------

### Decoder::from_signatures

Source: https://github.com/enviodev/hypersync-client-rust/blob/main/_autodocs/api-reference/decoder.md

Initializes a decoder instance from an array of event signature strings. This is the primary way to set up the decoder with the events it should recognize.

```APIDOC
## Decoder::from_signatures<S: AsRef<str>>(signatures: &[S]) -> Result<Self>

### Description
Initializes a decoder from an array of event signature strings.

### Method
`from_signatures`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **signatures** (`&[S]`) - Required - Event signatures as strings (e.g., `"Transfer(address indexed from, address indexed to, uint256 value)"`) 

### Returns
`Result<Decoder>` - Decoder instance or parsing error

### Errors
- If a signature fails to parse
- If a signature cannot be resolved to a type

### Example
```rust
use hypersync_client::Decoder;

let decoder = Decoder::from_signatures(&[
    "Transfer(address indexed from, address indexed to, uint256 value)",
    "Approval(address indexed owner, address indexed spender, uint256 value)",
])?;
```
```

--------------------------------

### Connect to Custom Endpoint

Source: https://github.com/enviodev/hypersync-client-rust/blob/main/_autodocs/examples.md

Configure the Hypersync client to connect to a custom endpoint URL. Ensure your API token is set in the environment.

```rust
let client = Client::builder()
    .url("https://custom-hypersync.example.com")
    .api_token(std::env::var("ENVIO_API_TOKEN")?)
    .build()?;
```

--------------------------------

### Configure Dense Streaming

Source: https://github.com/enviodev/hypersync-client-rust/blob/main/_autodocs/README.md

Set up streaming behavior for high parallelism when dealing with a large volume of data within blocks.

```rust
let config = StreamConfig::dense();
```

--------------------------------

### Collection Methods

Source: https://github.com/enviodev/hypersync-client-rust/blob/main/_autodocs/INDEX.md

Methods for fetching all data for a query and loading it into memory or directly into a Parquet file.

```APIDOC
## Collection Methods

### Description
Fetch all data matching a query and load it entirely into memory or directly into a Parquet file. Use these methods when the entire dataset can fit into available memory.

### Methods
- `collect<T: DeserializeOwned>(&self, query: &Query) -> Result<Vec<T>>`: Collects all query results into a vector of native Rust types.
- `collect_arrow(&self, query: &Query) -> Result<ArrowResponse>`: Collects all query results into an Apache Arrow format.
- `collect_events(&self, query: &Query) -> Result<EventsResponse>`: Collects all query results as joined events.
- `collect_parquet(&self, query: &Query, path: &str) -> Result<()>`: Collects all query results and writes them directly to a Parquet file at the specified path.
```

--------------------------------

### Live Progress Monitoring during Streaming

Source: https://github.com/enviodev/hypersync-client-rust/blob/main/_autodocs/api-reference/streaming-metrics.md

Periodically prints live streaming progress updates every 10 seconds. This snippet demonstrates how to access metrics within the streaming loop for real-time feedback.

```rust
use std::sync::Arc;
use std::time::Instant;

let metrics = Arc::new(StreamMetrics::new());
let start = Instant::now();

let mut receiver = client.stream_arrow_with_observer(
    query,
    config,
    metrics.clone(),
).await?;

while let Some(response) = receiver.recv().await {
    let response = response?;
    
    if start.elapsed().as_secs() % 10 == 0 {
        let summary = metrics.summary();
        let elapsed = summary.wall_clock.as_secs_f64();
        println!(
            "[{:.0}s] {} blocks, {} requests, {:.0} blocks/sec",
            elapsed,
            summary.total_blocks,
            summary.num_requests,
            summary.blocks_per_sec
        );
    }
}

```