semioscan 0.10.0

Production-grade Rust library for blockchain analytics: gas calculation, price extraction, and block window calculations for EVM chains
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122

// SPDX-FileCopyrightText: 2025 Semiotic AI, Inc.
//
// SPDX-License-Identifier: Apache-2.0

//! Semioscan: Blockchain analytics library for EVM chains
//!
//! Semioscan provides production-grade tools for:
//! - Gas cost calculation (L1 and L2 chains)
//! - Price extraction from DEX events
//! - Block window calculations
//! - Token event processing
//!
//! # Domain Organization
//!
//! - `types` - Strong types for type safety
//! - `config` - Configuration system
//! - `gas` - Gas calculation domain
//! - `price` - Price extraction domain
//! - `blocks` - Block window calculations
//! - `events` - Event processing
//! - `provider` - Dynamic provider utilities for runtime chain selection
//! - `transport` - Transport layer utilities (rate limiting, etc.)
//! - `cache` - Caching infrastructure (internal)
//! - `retrieval` - Data orchestration (internal)
//! - `tracing` - Observability (internal)

// === Module Declarations ===
mod blocks;
mod cache;
pub mod config;
pub mod errors;
mod events;
mod gas;
pub mod price;
pub mod provider;
mod retrieval;
mod tracing;
pub mod transport;
mod types;

// === Core Types (from types/) ===
pub use types::config::{BlockCount, MaxBlockRange, TransactionCount};
pub use types::fees::{L1DataFee, Percentage};
pub use types::gas::{
    BlobCount, BlobGasAmount, BlobGasPrice, GasAmount, GasBreakdown, GasBreakdownBuilder, GasPrice,
};
pub use types::tokens::{
    NormalizedAmount, TokenAmount, TokenDecimals, TokenPrice, TokenSet, UsdValue, UsdValueError,
};
pub use types::wei::WeiAmount;

// === Configuration (from config/) ===
pub use config::constants;
pub use config::{ChainConfig, SemioscanConfig, SemioscanConfigBuilder};

// === Error Types (from errors/) ===
pub use errors::{
    BlockWindowError, EventProcessingError, GasCalculationError, PriceCalculationError,
    RetrievalError, RpcError, SemioscanError,
};

// === Gas Calculation (from gas/) ===
pub use gas::adapter::{EthereumReceiptAdapter, OptimismReceiptAdapter, ReceiptAdapter};
pub use gas::blob;
pub use gas::cache::GasCache;
pub use gas::{EventType, GasCostCalculator, GasCostResult, GasForTx};

// === Price Extraction (from price/) ===
// Core trait and types are always available
pub use price::{PriceSource, PriceSourceError, SwapData};
// Calculator is feature-gated
#[cfg(feature = "odos-example")]
pub use price::odos::OdosPriceSource;
#[cfg(feature = "odos-example")]
pub use price::{PriceCalculator, RawSwapResult, TokenPriceResult};

// === Block Windows (from blocks/) ===
pub use blocks::{
    BlockWindowCache, BlockWindowCalculator, CacheKey, CacheStats, DailyBlockWindow, DiskCache,
    MemoryCache, NoOpCache, UnixTimestamp,
};

// === Cache Types (from blocks/cache/types, re-exported via types/cache) ===
pub use types::cache::{AccessSequence, TimestampMillis};

// === Events (from events/) ===
pub use events::fetch_logs_chunked;
pub use events::EventScanner;
pub use events::{extract_transferred_to_tokens, extract_transferred_to_tokens_with_config};
pub use events::{AmountCalculator, AmountResult};
pub use events::{Approval, Transfer};

// === Retrieval (Data Orchestration) ===
pub use retrieval::{
    batch_fetch_balances, batch_fetch_eth_balances, get_token_decimal_precision,
    u256_to_bigdecimal, BalanceError, BalanceQuery, BalanceResult, CombinedCalculator,
    CombinedDataLookupAttempt, CombinedDataLookupFailure, CombinedDataLookupPass,
    CombinedDataLookupStage, CombinedDataResult, CombinedDataRetrievalMetadata, DecimalPrecision,
    GasAndAmountForTx,
};

// === Transport Layers ===
pub use transport::{
    RateLimitLayer, RateLimitService, RetryConfig, RetryLayer, RetryLayerBuilder, RetryService,
};

// === Provider Utilities ===
#[cfg(feature = "ws")]
pub use provider::create_ws_provider;
pub use provider::{
    create_http_provider, create_typed_http_provider, network_type_for_chain,
    rate_limited_http_provider, simple_http_provider, AnyHttpProvider, ChainAwareProvider,
    ChainEndpoint, DynProviderBuilder, EthereumHttpProvider, NetworkType, OptimismHttpProvider,
    PooledProvider, ProviderConfig, ProviderPool, ProviderPoolBuilder, SharedProvider,
};

// Re-export RouterType from odos-sdk for convenience
#[cfg(feature = "odos-example")]
pub use odos_sdk::RouterType;

// Note: Cache internals (cache::BlockRangeCache) and tracing spans are NOT re-exported
// as they are implementation details. Users can access them via fully-qualified paths if needed.