chore: release v0.4.0

Major feature release with provider utilities, transport layers, and batch operations.

Highlights:
- Connection pooling and dynamic provider utilities for multi-chain apps
- Tower-based rate limiting, retry with exponential backoff, and logging layers
- EIP-4844 blob gas support with comprehensive utilities
- Batch fetching for transactions, receipts, balances, and token decimals
- WebSocket support for real-time event streaming
- Minimum Rust version updated to 1.92

Author: suchapalaver

CHANGELOG.md

@@ -7,6 +7,96 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-01-03
+
+### Added
+
+#### Provider Utilities
+
+- **Connection Pooling**: Thread-safe provider pooling for efficient connection reuse across concurrent operations
+  - `ProviderPool`: Thread-safe pool using RwLock for concurrent access
+  - `ProviderPoolBuilder`: Builder pattern for easy configuration
+  - `ChainEndpoint`: Configuration struct with chain-specific helpers
+  - `PooledProvider`: Type alias for Arc<RootProvider<AnyNetwork>>
+  - Lazy provider initialization via `get_or_add()`
+  - Per-chain rate limiting support
+  - Compatible with `std::sync::LazyLock` for static pools
+
+- **Dynamic Provider Utilities**: Runtime chain selection without compile-time network constraints
+  - Type aliases: `AnyHttpProvider`, `EthereumHttpProvider`, `OptimismHttpProvider`
+  - `NetworkType` enum with `network_type_for_chain()` for chain categorization
+  - `ChainAwareProvider` wrapper for tracking chain metadata
+  - Factory functions: `create_http_provider`, `create_ws_provider`, `create_typed_http_provider`
+  - `ProviderConfig` with presets for public/private endpoints, Infura, Alchemy
+
+#### Transport Layers
+
+- **Rate Limiting Layer**: Token bucket rate limiter with configurable limits
+  - `RateLimitLayer::per_second(n)` for requests-per-second limiting
+  - `RateLimitLayer::with_min_delay(duration)` for fixed delays between requests
+  - Async-safe with Arc<Mutex<RateLimitState>>
+
+- **Logging Layer**: RPC call tracing with configurable verbosity
+  - Automatic method extraction from RequestPacket
+  - Duration tracking in tracing spans
+  - Optional request/response payload logging via `with_request_logging()` and `verbose()`
+
+- **Retry Layer**: Automatic retry of transient RPC failures with exponential backoff
+  - `RetryLayer::new()` with configurable max retries, base delay, and max delay
+  - Builder pattern for flexible configuration
+  - Preset configurations: `aggressive()` and `conservative()`
+  - Uses Alloy's `is_retry_err()` for smart error classification
+
+#### Gas Calculation
+
+- **EIP-4844 Blob Gas Support**: Comprehensive blob gas tracking and utilities
+  - `BlobGasPrice` type with `from_gwei()` and `cost_for_blobs()` methods
+  - `GasBreakdown` struct separating execution/blob/L1 costs
+  - `GasBreakdownBuilder` for flexible breakdown construction
+  - Enhanced `L1Gas`/`L2Gas` with `blob_count` and `blob_gas_price` fields
+  - `GasCostResult` now includes `breakdown` field for analytics
+  - New `blob` module with utilities:
+    - `get_blob_base_fee()` - fetch from latest block
+    - `get_blob_base_fee_at_block()` - fetch from specific block
+    - `estimate_blob_cost()` - estimate cost for N blobs
+    - `calculate_blob_gas()` - pure blob gas calculation
+    - `max_blob_gas_per_block()` - returns 786,432 max
+    - `estimate_total_tx_cost()` - combines execution + blob costs
+
+#### Batch Operations
+
+- **Batch Fetching for Transactions and Receipts**: Two-pass batch approach for fetching transactions and receipts in parallel via `futures::join_all`
+- **Batch Balance Utilities**: Fetch multiple token/ETH balances efficiently
+  - `batch_fetch_balances()` for ERC-20 token balances
+  - `batch_fetch_eth_balances()` for native ETH balances
+  - New types: `BalanceQuery`, `BalanceResult`, `BalanceError`
+  - Compatible with Alloy's `CallBatchLayer` for automatic Multicall3 batching
+
+- **Batch Token Decimals**: `batch_fetch_decimals()` for fetching multiple token decimals in parallel
+
+#### Real-Time Events
+
+- **WebSocket Support**: Real-time event streaming via WebSocket subscriptions
+  - `RealtimeEventScanner` for WebSocket-based event subscriptions
+  - `subscribe_blocks()` for real-time block headers
+  - `subscribe_logs()` for real-time log events
+  - `subscribe_logs_with_catchup()` for subscriptions with historical catchup
+  - New `SubscriptionFailed` error variant for WebSocket errors
+
+#### Documentation
+
+- **Network Selection Guide** (`docs/NETWORK_SELECTION.md`): Comprehensive guide for choosing between Ethereum, Optimism, and AnyNetwork types
+- **Provider Setup Examples** (`docs/PROVIDER_SETUP.md`): Practical examples covering rate limiting, retry, logging, pooling, and WebSocket providers
+
+### Changed
+
+- **Minimum Rust version**: Updated to 1.92 (from 1.89)
+- **Dependencies**: Updated and upgraded all cargo dependencies
+
+### Fixed
+
+- Fixed doctest imports in blob module to use correct public paths
+
 ## [0.3.0] - 2025-11-16
 
 ### Breaking Changes

Cargo.toml

@@ -1,9 +1,9 @@
 [package]
 name = "semioscan"
-version = "0.3.0"
+version = "0.4.0"
 edition = "2021"
 authors = ["Joseph Livesey <joseph@semiotic.ai>"]
-rust-version = "1.89"
+rust-version = "1.92"
 description = "Production-grade Rust library for blockchain analytics: gas calculation, price extraction, and block window calculations for EVM chains"
 license = "Apache-2.0"
 repository = "https://github.com/semiotic-ai/semioscan"
@@ -46,7 +46,10 @@ alloy-transport-http = { version = "1.2", default-features = false, features = [
 ] }
 async-trait = "0.1"
 # futures with std enables join_all for batch RPC calls and StreamExt for WebSocket subscriptions
-futures = { version = "0.3", default-features = false, features = ["alloc", "std"] }
+futures = { version = "0.3", default-features = false, features = [
+    "alloc",
+    "std",
+] }
 bigdecimal = { version = "0.4", features = ["serde"] }
 chrono = { version = "0.4", features = ["serde"] }
 op-alloy-network = "0.22"

README.md

@@ -61,11 +61,13 @@ Built on [Alloy](https://github.com/alloy-rs/alloy), the modern Ethereum library
 
 ## Features
 
-- **Gas Cost Calculation**: Accurately calculate transaction gas costs for both L1 (Ethereum) and L2 (Optimism Stack) chains, including L1 data fees
+- **Gas Cost Calculation**: Accurately calculate transaction gas costs for both L1 (Ethereum) and L2 (Optimism Stack) chains, including L1 data fees and EIP-4844 blob gas
 - **Block Window Calculations**: Map UTC dates to blockchain block ranges with intelligent caching
 - **DEX Price Extraction**: Extensible trait-based system for extracting price data from on-chain swap events
 - **Multi-Chain Support**: Works with 12+ EVM chains including Ethereum, Arbitrum, Base, Optimism, Polygon, and more
-- **Event Scanning**: Extract transfer amounts and events from blockchain transaction logs
+- **Event Scanning**: Extract transfer amounts and events from blockchain transaction logs with real-time WebSocket subscriptions
+- **Provider Utilities**: Connection pooling, rate limiting, retry with exponential backoff, and logging layers
+- **Batch Operations**: Efficient batch fetching for transactions, receipts, balances, and token decimals
 - **Production-Ready**: Battle-tested in production for automated trading and DeFi applications processing millions of dollars in swaps
 
 ## Use Cases
@@ -87,10 +89,10 @@ Add semioscan to your `Cargo.toml`:
 ```toml
 [dependencies]
 # Core library (gas, block windows, events)
-semioscan = "0.3"
+semioscan = "0.4"
 
 # With Odos DEX reference implementation (optional)
-semioscan = { version = "0.3", features = ["odos-example"] }
+semioscan = { version = "0.4", features = ["odos-example"] }
 ```
 
 ### Feature Flags
@@ -611,13 +613,13 @@ cargo run --package semioscan --example router_token_discovery -- arbitrum
 
 Semioscan may not be the best choice for:
 
-- **Real-time price feeds**: Use WebSocket-based oracles (Chainlink, Pyth, etc.) for sub-second price updates
+- **Real-time price feeds**: Use WebSocket-based oracles (Chainlink, Pyth, etc.) for sub-second price updates (though Semioscan now supports WebSocket subscriptions for event streaming)
 - **Non-EVM chains**: Semioscan is EVM-specific (Solana, Cosmos, etc. are not supported)
-- **Simple balance queries**: Use lighter libraries like `ethers-rs` for basic token balances
+- **Simple balance queries**: Use lighter libraries for basic token balances (though Semioscan provides efficient batch balance queries)
 - **Indexing entire chains**: Use The Graph or custom indexers for comprehensive blockchain indexing
-- **High-frequency trading**: RPC-based queries have latency; use WebSocket streams or MEV infrastructure
+- **High-frequency trading**: For ultra-low latency, use dedicated MEV infrastructure
 
-Semioscan excels at **batch analytics**, **historical queries**, and **multi-chain operations** where accurate gas cost calculation and flexible price extraction are required.
+Semioscan excels at **batch analytics**, **historical queries**, **real-time event streaming**, and **multi-chain operations** where accurate gas cost calculation and flexible price extraction are required.
 
 ## Production Usage