Crate semioscan 

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)

Preferred imports

The most commonly used types are re-exported at the crate root, so use semioscan::{GasCostCalculator, PriceCalculator, BlockWindowCalculator}; covers typical usage. Domain-specific items that aren’t part of that facade live under their public modules — for example a custom price source pulls PriceSource and PriceSourceError from semioscan::price, and transport layers come from semioscan::transport.

Feature flags

Every domain is a Cargo feature, and the default feature enables all of them — so a default semioscan dependency behaves exactly as before. Downstream crates that only need part of the library can opt out and pull in just the domains they use:

# Just block-window calculations, nothing else:
semioscan = { version = "0.14", default-features = false, features = ["blocks"] }

Feature dependencies follow the real module dependencies:

• blocks, events, transport — standalone domains
• gas enables events (it decodes Transfer/Approval logs)
• price — DEX price extraction (reads on-chain token decimals)
• provider enables transport
• retrieval enables events and gas (combined gas/price/balance lookups)
• ws enables provider and adds WebSocket transport (create_ws_provider)

A --no-default-features build with no domains selected compiles the core configuration, error, and type machinery only.

Re-exports

pub use config::constants;

pub use config::policy::LookupConfig;

pub use config::policy::LookupPolicy;

pub use config::policy::RpcConfig;

pub use config::policy::RpcPolicy;

pub use config::policy::ScanConfig;

pub use config::policy::ScanPolicy;

pub use config::ChainConfig;

pub use config::SemioscanConfig;

pub use config::SemioscanConfigBuilder;

pub use errors::BlockWindowError;

pub use errors::EventProcessingError;

pub use errors::GasCalculationError;

pub use errors::PriceCalculationError;

pub use errors::RetrievalError;

pub use errors::RpcError;

pub use errors::SemioscanError;

pub use price::PriceCalculator;

pub use price::PriceSource;

pub use price::PriceSourceError;

pub use price::RawSwapResult;

pub use price::SwapData;

pub use price::TokenPriceResult;

pub use transport::RateLimitLayer;

pub use transport::RateLimitService;

pub use transport::RetryConfig;

pub use transport::RetryLayer;

pub use transport::RetryLayerBuilder;

pub use transport::RetryService;

pub use provider::create_http_provider;

pub use provider::create_typed_http_provider;

pub use provider::network_type_for_chain;

pub use provider::rate_limited_http_provider;

pub use provider::simple_http_provider;

pub use provider::AnyHttpProvider;

pub use provider::ChainAwareProvider;

pub use provider::ChainEndpoint;

pub use provider::DynProviderBuilder;

pub use provider::EthereumHttpProvider;

pub use provider::NetworkType;

pub use provider::OptimismHttpProvider;

pub use provider::PooledProvider;

pub use provider::ProviderConfig;

pub use provider::ProviderPool;

pub use provider::ProviderPoolBuilder;

pub use provider::SharedProvider;

Modules

blob

EIP-4844 Blob Gas Utilities

config

Configuration for semioscan operations

errors

Error types for the semioscan library.

price

Price extraction from DEX swap events

provider

Dynamic provider utilities for runtime chain selection

transport

Transport layer utilities for Alloy providers.

Structs

AccessSequence

Monotonic sequence number for deterministic LRU ordering

AmountCalculator

Calculator for ERC-20 token transfer amounts

AmountResult

Result of transfer amount calculation

Approval

ERC-20 Approval event

BlobCount

Represents the number of EIP-4844 blobs in a transaction

BlobGasAmount

Represents the amount of blob gas consumed by EIP-4844 transactions

BlobGasPrice

Blob gas price in wei per unit of blob gas (EIP-4844)

BlockCount

Represents a count of blocks (not a block number)

BlockWindowCalculator

Calculates and caches daily block windows for blockchain queries

CacheKey

Key for caching daily block windows

CacheStats

Statistics about cache performance

CombinedCalculator

CombinedDataLookupAttempt

Diagnostic details for one failed tx/receipt lookup attempt.

CombinedDataLookupFailure

Structured metadata describing a decoded transfer that could not be fully enriched.

CombinedDataResult

Aggregated result for combined data retrieval over a block range.

CombinedDataRetrievalMetadata

Retrieval metadata for combined data calculations.

DailyBlockWindow

Represents an inclusive block range for a specific UTC day on a blockchain

DiskCache

Disk-based cache with file locking, versioning, and TTL support

EthereumReceiptAdapter

Receipt adapter for Ethereum and Ethereum-like chains

EventScanner

Event scanner that fetches logs over a block range with chunking and rate limiting, skipping any chunk whose eth_getLogs call fails.

GasAmount

Amount of gas consumed by a transaction

GasAndAmountForTx

Data for a single transaction including gas and transferred amount.

GasBreakdown

Detailed breakdown of gas costs for a transaction

GasBreakdownBuilder

Builder for constructing GasBreakdown instances

GasCache

In-memory cache for gas cost calculation results

GasCostCalculator

GasCostResult

Result of gas cost calculation over a block range

GasPrice

Gas price in wei per unit of gas

L1DataFee

L1 data fee for L2 transactions

MaxBlockRange

Maximum block range for RPC queries

MemoryCache

In-memory cache with optional TTL and size limits

NoOpCache

A no-operation cache that disables caching entirely

NormalizedAmount

Token amount normalized by decimals (human-readable)

OptimismReceiptAdapter

Receipt adapter for Optimism Stack chains

Percentage

Represents a percentage value in the range [0.0, 1.0]

TimestampMillis

Unix timestamp in milliseconds for high-precision cache ordering

TokenAmount

Raw token amount (not normalized for decimals)

TokenDecimals

ERC-20 token decimal precision

TokenPrice

Price of one token in USDC (or other stablecoin)

TokenSet

Represents a set of unique token addresses

TransactionCount

Represents a count of blockchain transactions

Transfer

ERC-20 Transfer event

UnixTimestamp

Unix timestamp in seconds (always UTC)

UsdValue

Represents a USD-denominated value for amounts, balances, and prices

WeiAmount

Represents an amount of native currency (ETH, MATIC, etc.) in wei

Enums

CombinedDataLookupPass

Which pass produced a lookup error while enriching a decoded transfer log.

CombinedDataLookupStage

Which follow-up RPC lookup failed while enriching a decoded transfer log.

DecimalPrecision

Decimal precision for blockchain values

EventType

Type of ERC-20 event for gas calculation

GasForTx

Gas data for a single transaction

UsdValueError

Errors that can occur when creating a USD value

Constants

DEFAULT_HEAD_TTL

Default TTL for the memoized chain head shared by BlockWindowCalculator::block_range_for_timestamps and BlockWindowCalculator::get_daily_window.

Traits

BlockWindowCache

Trait for block window cache backends

ReceiptAdapter

Trait for network-specific receipt handling

Functions

batch_fetch_balances

Batch fetch token balances for multiple (token, holder) pairs.

batch_fetch_eth_balances

Batch fetch ETH balances for multiple addresses.

extract_transferred_to_tokens

Extract tokens transferred to a router contract using default configuration

extract_transferred_to_tokens_with_config

Extract tokens transferred to a router contract with custom configuration

fetch_logs_chunked

Fetch logs in chunks to handle large block ranges.

get_token_decimal_precision

Get the decimal precision for a specific token on a specific chain. Native tokens (Address::ZERO) use 18 decimals. Most USDC tokens use 6 decimals, but BSC Binance-Peg USDC uses 18 decimals.

u256_to_bigdecimal

Convert U256 to BigDecimal with decimal scaling for database storage. This function properly handles large decimal places (like 18 for ETH) without overflow.

Type Aliases

BalanceError

Error from a failed balance fetch: (token_address, holder_address, error_message)

BalanceQuery

Query for a token balance: (token_address, holder_address)

BalanceResult

Result of a successful balance fetch: (token_address, holder_address, balance)