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)

Re-exports

pub use config::constants;

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::PriceSource;

pub use price::PriceSourceError;

pub use price::SwapData;

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

CombinedDataResult

Aggregated result for combined data retrieval over a block range.

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

GasAmount

Amount of gas consumed by a transaction

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

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

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

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)