DocumentationSubstreamsGlossaryevm

Ethereum Substreams Type Glossary

Extended BlockBase Block
Block Header✅✅
Transaction Receipts✅✅
Event Logs✅✅
Balance Changes✅❌
Storage Changes✅❌
Internal Calls✅❌

Block

pub struct Block {
    pub hash: Vec<u8>,
    pub number: u64,
    pub size: u64,
    pub header: Option<BlockHeader>,
    pub uncles: Vec<BlockHeader>,
    pub transaction_traces: Vec<TransactionTrace>,
    pub balance_changes: Vec<BalanceChange>,
    pub detail_level: i32,
    pub code_changes: Vec<CodeChange>,
    pub system_calls: Vec<Call>,
    pub ver: i32,
}

Detail Level

pub enum DetailLevel {
    DetaillevelExtended = 0,    // Full block details including traces
    DetaillevelBase = 2,        // Basic block info without traces
}

Fields and Use Cases

hash

  • Description: The unique identifier of the block (32 bytes)
  • Use Case: Identify and reference specific blocks in the blockchain

number

  • Description: The block number
  • Use Case: Track the chronological order of blocks and blockchain height

size

  • Description: The size of the block in bytes
  • Use Case: Monitor network and storage requirements

header

  • Description: The block header information (optional)
  • Use Case: Access key metadata about the block (e.g., timestamp, difficulty, gas used)

uncles

  • Description: List of uncle block headers
  • Use Case: Analyze network propagation and mining competition (only relevant for PoW chains)

transaction_traces

  • Description: List of transaction traces with full execution details
  • Use Case: Analyze transaction flow, track contract interactions, and monitor state changes
  • Example: 
    fn analyze_transactions(block: &Block) {
    for trace in &block.transaction_traces {
        println!("Transaction hash: {:?}", trace.hash);
        // Analyze calls, state changes, gas usage, etc.
    }
}

balance_changes

  • Description: List of balance changes that occurred in this block
  • Use Case: Track ETH transfers, including mining rewards and fee payments
  • Example: 
    fn track_balance_changes(block: &Block) {
    for change in &block.balance_changes {
        println!("Balance change: {:?} for address {:?}", change.new_value, change.address);
        // Analyze reason, old value, and new value
    }
}

detail_level

  • Description: Exact tracing method used to build the block. EXTENDED (0) or BASE (2)
  • Use Case: Determine the level of detail available in the block data

code_changes

  • Description: List of code changes that occurred in this block
  • Use Case: Monitor contract deployments, upgrades, and self-destructs
  • Example: 
    fn track_code_changes(block: &Block) {
    for change in &block.code_changes {
        println!("Code change at address: {:?}", change.address);
        // Analyze old and new code hashes
    }
}

system_calls

  • Description: List of system calls that occurred in this block (introduced in Cancun)
  • Use Case: Monitor blockchain-level operations and state changes outside of normal transaction flow
  • Example: 
    fn analyze_system_calls(block: &Block) {
    for call in &block.system_calls {
        println!("System call to: {:?}", call.address);
        // Analyze system call details
    }
}

ver

  • Description: Version of the block
  • Use Case: Ensure compatibility with different data formats and handle potential schema changes

Important Notes

  • The detail_level field is crucial to understand which fields are available. BASE (2) level has been extracted using archive node RPC calls and will contain only the block header, transaction receipts and event logs. The EXTENDED (0) level has been extracted using the Firehose tracer and all fields are available.
  • The concept of ‘ordinal’ is important for understanding the global order of execution elements within the block.
  • The balance_changes field captures ETH transfers that happened at the block level, including those outside the normal transaction flow (e.g., mining rewards).
  • The code_changes field is particularly important for tracking modifications to internal smart contracts used by some Ethereum forks like BSC (Binance Smart Chain) and Polygon.
  • The system_calls field, introduced in the Cancun upgrade, allows for monitoring of blockchain-level operations that affect the state but are executed outside of normal transactions.

BlockHeader

pub struct BlockHeader {
    pub parent_hash: Vec<u8>,
    pub uncle_hash: Vec<u8>,
    pub coinbase: Vec<u8>,
    pub state_root: Vec<u8>,
    pub transactions_root: Vec<u8>,
    pub receipt_root: Vec<u8>,
    pub logs_bloom: Vec<u8>,
    pub difficulty: Option<BigInt>,
    pub total_difficulty: Option<BigInt>,
    pub number: u64,
    pub gas_limit: u64,
    pub gas_used: u64,
    pub timestamp: Option<Timestamp>,
    pub extra_data: Vec<u8>,
    pub mix_hash: Vec<u8>,
    pub nonce: u64,
    pub hash: Vec<u8>,
    pub base_fee_per_gas: Option<BigInt>,
    pub withdrawals_root: Option<Vec<u8>>,
    pub blob_gas_used: Option<u64>,
    pub excess_blob_gas: Option<u64>,
    pub parent_beacon_root: Vec<u8>,
}

Fields and Use Cases

parent_hash

  • Description: Hash of the parent block
  • Use Case: Maintain blockchain integrity and verify block order

uncle_hash

  • Description: Hash of the uncle blocks (also referred to as ommers)
  • Use Case: Analyze network propagation in PoW chains
  • Note: In PoS, this is set to a constant value

coinbase

  • Description: Address of the miner who mined this block
  • Use Case: Track mining rewards and analyze mining pool activities

state_root, transactions_root, receipt_root

  • Description: Root hashes of the state, transaction, and receipt tries respectively
  • Use Case: Verify blockchain state and transaction integrity

logs_bloom

  • Description: Bloom filter for the logs
  • Use Case: Efficiently query for logs without processing the entire block

difficulty, total_difficulty

  • Description: Block difficulty and cumulative chain difficulty
  • Note: In PoS, these values are set to constants

number, gas_limit, gas_used

  • Description: Block number, maximum gas allowed, and total gas used
  • Use Case: Analyze block capacity and network utilization

timestamp

  • Description: Unix timestamp when this block was mined
  • Use Case: Temporal analysis of blockchain activities

extra_data

  • Description: Additional data included by the miner
  • Note: Limited to 32 bytes in PoS

mix_hash, nonce

  • Description: Used for PoW algorithm
  • Note: Set to constants in PoS

hash

  • Description: Block hash
  • Use Case: Unique identifier for the block

base_fee_per_gas

  • Description: Base fee per gas (introduced in EIP-1559)
  • Use Case: Analyze transaction fee market

withdrawals_root

  • Description: Root hash of the withdrawals trie (introduced in Shanghai upgrade)
  • Use Case: Verify withdrawal integrity in PoS

blob_gas_used, excess_blob_gas

  • Description: Blob gas metrics (introduced in EIP-4844)
  • Use Case: Analyze blob transaction usage and pricing

parent_beacon_root

  • Description: Parent beacon block root (introduced in EIP-4788)
  • Use Case: Connect execution and consensus layers in PoS

Example Use Case

fn analyze_block_header(header: &BlockHeader) {
    println!("Block number: {}", header.number);
    println!("Gas usage: {}/{}", header.gas_used, header.gas_limit);
    
    if let Some(base_fee) = &header.base_fee_per_gas {
        println!("Base fee: {}", base_fee);
    }
 
    if let Some(blob_gas_used) = header.blob_gas_used {
        println!("Blob gas used: {}", blob_gas_used);
    }
 
    // Analyze other fields as needed
}

Important Notes

  • The BlockHeader contains crucial metadata about the block and is essential for maintaining blockchain integrity.
  • Some fields (like difficulty and nonce) have different meanings or constant values in PoS compared to PoW.
  • Fields like withdrawals_root, blob_gas_used, and excess_blob_gas are only present in specific network upgrades.
  • The parent_beacon_root is crucial for connecting the execution and consensus layers in PoS Ethereum.

TransactionTrace

pub struct TransactionTrace {
    pub to: Option<Vec<u8>>,
    pub nonce: u64,
    pub gas_price: Option<BigInt>,
    pub gas_limit: u64,
    pub value: Option<BigInt>,
    pub input: Vec<u8>,
    pub v: Vec<u8>,
    pub r: Vec<u8>,
    pub s: Vec<u8>,
    pub gas_used: u64,
    pub type_: i32,
    pub access_list: Vec<AccessTuple>,
    pub max_fee_per_gas: Option<BigInt>,
    pub max_priority_fee_per_gas: Option<BigInt>,
    pub index: u32,
    pub hash: Vec<u8>,
    pub from: Vec<u8>,
    pub return_data: Vec<u8>,
    pub public_key: Vec<u8>,
    pub begin_ordinal: u64,
    pub end_ordinal: u64,
    pub status: i32,
    pub receipt: Option<TransactionReceipt>,
    pub calls: Vec<Call>,
    pub blob_gas: Option<u64>,
    pub blob_gas_fee_cap: Option<BigInt>,
    pub blob_hashes: Vec<Vec<u8>>,
}

TransactionTrace Status

pub enum TransactionTraceStatus {
    Unknown = 0,
    Succeeded = 1,  // Transaction executed successfully
    Failed = 2,     // Transaction failed due to out of gas or other errors
    Reverted = 3,   // Transaction explicitly reverted by contract code
}

TransactionTrace Type

pub enum Type {
    TrxTypeLegacy = 0,           // Pre-EIP-2718 transaction format
    TrxTypeAccessList = 1,       // EIP-2930: Optional access lists
    TrxTypeDynamicFee = 2,       // EIP-1559: Fee market change
    TrxTypeBlob = 3,             // EIP-4844: Blob transactions
    // Arbitrum specific types
    TrxTypeArbitrumDeposit = 100,
    TrxTypeArbitrumUnsignedTx = 101,
    TrxTypeArbitrumContractTx = 102,
    TrxTypeArbitrumRetryTx = 104,
    TrxTypeArbitrumSubmitRetryable = 105,
    // Optimism specific types
    TrxTypeOptimismDeposit = 126,
 
    // reflects the evolution of Ethereum's transaction types, from legacy transactions to the latest blob transactions (EIP-4844). Layer 2 solutions like Arbitrum and Optimism have their own transaction types.
}

Fields and Use Cases

to

  • Description: Address of the recipient (optional, can be null for contract creation)
  • Use Case: Identify the target of the transaction (contract or EOA)
  • Example: 
    fn check_uniswap_v3_interaction(trace: &TransactionTrace) {
    if let Some(to) = &trace.to {
        if to == UNISWAP_V3_ROUTER_ADDRESS {
            println!("Interaction with Uniswap V3 Router detected");
        }
    }
}

nonce

  • Description: Sender’s transaction count
  • Use Case: Ensure transaction order and prevent double-spending
  • Example: 
    fn check_nonce_gap(traces: &[TransactionTrace]) {
    for window in traces.windows(2) {
        if window[1].nonce - window[0].nonce > 1 {
            println!("Nonce gap detected between transactions");
        }
    }
}

gas_price, max_fee_per_gas, max_priority_fee_per_gas

  • Description: Gas pricing parameters
  • Use Case: Analyze transaction fee market and EIP-1559 dynamics
  • Example: 
    fn analyze_gas_pricing(trace: &TransactionTrace) {
    if let Some(max_fee) = &trace.max_fee_per_gas {
        if let Some(priority_fee) = &trace.max_priority_fee_per_gas {
            let max_base_fee = max_fee - priority_fee;
            println!("Max base fee: {}", max_base_fee);
        }
    }
}

gas_limit, gas_used

  • Description: Maximum gas allowed and actual gas consumed
  • Use Case: Measure transaction complexity and efficiency
  • Example: 
    fn calculate_gas_efficiency(trace: &TransactionTrace) {
    let efficiency = (trace.gas_used as f64) / (trace.gas_limit as f64) * 100.0;
    println!("Gas efficiency: {:.2}%", efficiency);
}

value

  • Description: Amount of Ether transferred
  • Use Case: Track Ether movements
  • Example: 
    fn check_high_value_transfer(trace: &TransactionTrace) {
    if let Some(value) = &trace.value {
        if value > &BigInt::from(1000000000000000000u64) { // 1 ETH
            println!("High value transfer detected: {} ETH", value);
        }
    }
}

input

  • Description: Input data for the transaction
  • Use Case: Decode contract interactions and function calls
  • Example: 
    fn decode_uniswap_v3_swap(trace: &TransactionTrace) {
    if trace.input.len() >= 4 {
        let function_selector = &trace.input[0..4];
        if function_selector == EXACT_INPUT_SINGLE_SELECTOR {
            println!("Uniswap V3 ExactInputSingle swap detected");
            // Further decoding of input parameters
        }
    }
}

v, r, s

  • Description: Components of the transaction signature
  • Use Case: Verify transaction authenticity
  • Example: 
    fn check_signature_components(trace: &TransactionTrace) {
    println!("Signature components: v={:?}, r={:?}, s={:?}", trace.v, trace.r, trace.s);
}

type_

  • Description: Transaction type (e.g., legacy, EIP-2930, EIP-1559)
  • Use Case: Differentiate between transaction formats
  • Example: 
    fn categorize_transaction(trace: &TransactionTrace) {
    match trace.type_ {
        0 => println!("Legacy transaction"),
        1 => println!("EIP-2930 transaction"),
        2 => println!("EIP-1559 transaction"),
        _ => println!("Unknown transaction type"),
    }
}

hash, from, public_key

  • Description: Transaction identifier and sender information
  • Use Case: Track transaction origin and uniqueness
  • Example: 
    fn log_transaction_details(trace: &TransactionTrace) {
    println!("Transaction: {:?}", trace.hash);
    println!("From: {:?}", trace.from);
    println!("Public Key: {:?}", trace.public_key);
}

begin_ordinal, end_ordinal

  • Description: Global ordinals for transaction execution start and end
  • Use Case: Determine precise ordering of events within a block
  • Example:
fn calculate_execution_span(trace: &TransactionTrace) {
    let span = trace.end_ordinal - trace.begin_ordinal;
    println!("Transaction execution span: {}", span);
}

status

  • Description: Execution status of the transaction
  • Use Case: Quickly identify successful, failed, or reverted transactions
  • Example:
fn check_transaction_status(trace: &TransactionTrace) {
    match trace.status {
        1 => println!("Transaction succeeded"),
        2 => println!("Transaction failed"),
        3 => println!("Transaction reverted"),
        _ => println!("Unknown transaction status"),
    }
}

receipt

  • Description: Transaction receipt containing execution results
  • Use Case: Access logs, gas used, and other post-execution data
  • Example:
fn analyze_receipt(trace: &TransactionTrace) {
    if let Some(receipt) = &trace.receipt {
        println!("Cumulative gas used: {}", receipt.cumulative_gas_used);
        println!("Logs: {:?}", receipt.logs);
    }
}

calls

  • Description: List of internal calls made during transaction execution
  • Use Case: Analyze contract interactions and trace execution flow
  • Example:
fn trace_internal_calls(trace: &TransactionTrace) {
    for (index, call) in trace.calls.iter().enumerate() {
        println!("Call {}: from {:?} to {:?}", index, call.caller, call.address);
        if let Some(value) = &call.value {
            if value > &BigInt::from(0) {
                println!("  Value transferred: {:?}", value);
            }
        }
    }
}

blob_gas, blob_gas_fee_cap, blob_hashes

  • Description: EIP-4844 blob-related fields
  • Use Case: Analyze blob transactions in rollup-centric Ethereum
  • Example:
fn analyze_blob_transaction(trace: &TransactionTrace) {
    if let Some(blob_gas) = trace.blob_gas {
        println!("Blob gas used: {}", blob_gas);
    }
    if let Some(blob_gas_fee_cap) = &trace.blob_gas_fee_cap {
        println!("Blob gas fee cap: {}", blob_gas_fee_cap);
    }
    println!("Number of blob hashes: {}", trace.blob_hashes.len());
}

AccessTuple

pub struct AccessTuple {
    pub address: Vec<u8>,
    pub storage_keys: Vec<Vec<u8>>,
}

Fields and Use Cases

address

  • Description: The address of the contract being accessed
  • Use Case: Identify which contracts are being interacted with in an access list transaction
  • Example: 
    fn analyze_access_tuple(tuple: &AccessTuple) {
    println!("Contract accessed: {:?}", tuple.address);
    if tuple.address == UNISWAP_V3_POOL_ADDRESS {
        println!("Uniswap V3 pool access detected");
    }
}

storage_keys

  • Description: A list of storage keys that are likely to be accessed during the transaction
  • Use Case: Pre-declare storage slots that will be accessed to potentially reduce gas costs
  • Example: 
    fn analyze_storage_access(tuple: &AccessTuple) {
    println!("Number of storage keys accessed: {}", tuple.storage_keys.len());
    for (index, key) in tuple.storage_keys.iter().enumerate() {
        println!("Storage key {}: {:?}", index, key);
    }
}

Important Notes

  • AccessTuple is part of EIP-2930 (Optional access lists), which was introduced to optimize gas costs for transactions that access contract storage.
  • By pre-declaring accessed addresses and storage slots, transactions can potentially save gas, especially in complex contract interactions.
  • In the context of Uniswap V3, access lists can be particularly useful for optimizing interactions with pool contracts, where multiple storage slots are typically accessed.

Example Use Case: Optimizing Uniswap V3 Interactions

fn optimize_uniswap_v3_access(tuples: &[AccessTuple]) {
    for tuple in tuples {
        if tuple.address == UNISWAP_V3_POOL_ADDRESS {
            println!("Uniswap V3 pool access optimization:");
            println!("  Pool address: {:?}", tuple.address);
            println!("  Accessed storage keys:");
            for key in &tuple.storage_keys {
                match key.as_slice() {
                    LIQUIDITY_SLOT => println!("    - Liquidity"),
                    SQRT_PRICE_X96_SLOT => println!("    - SqrtPriceX96"),
                    TICK_SLOT => println!("    - Current Tick"),
                    FEE_GROWTH_GLOBAL0_X128_SLOT => println!("    - FeeGrowthGlobal0X128"),
                    FEE_GROWTH_GLOBAL1_X128_SLOT => println!("    - FeeGrowthGlobal1X128"),
                    _ => println!("    - Other: {:?}", key),
                }
            }
        }
    }
}
 
// Constants representing known storage slots in Uniswap V3 pool contracts
const LIQUIDITY_SLOT: &[u8] = &[0; 32];
const SQRT_PRICE_X96_SLOT: &[u8] = &[1; 32];
const TICK_SLOT: &[u8] = &[2; 32];
const FEE_GROWTH_GLOBAL0_X128_SLOT: &[u8] = &[3; 32];
const FEE_GROWTH_GLOBAL1_X128_SLOT: &[u8] = &[4; 32];

Additional Context

  • Access lists are particularly useful for complex transactions that interact with multiple contracts or access multiple storage slots.
  • While access lists can potentially reduce gas costs, they also introduce an overhead in transaction size. The gas savings need to outweigh this overhead for the optimization to be effective.

Example: Calculating Potential Gas Savings

fn estimate_gas_savings(tuples: &[AccessTuple]) {
    let mut total_slots = 0;
    let mut contracts_accessed = HashSet::new();
 
    for tuple in tuples {
        contracts_accessed.insert(&tuple.address);
        total_slots += tuple.storage_keys.len();
    }
 
    // These values are approximate and may change with network upgrades
    let cold_sload_cost = 2100;
    let warm_sload_cost = 100;
    let cold_account_access_cost = 2600;
    let warm_account_access_cost = 100;
 
    let potential_savings = (cold_sload_cost - warm_sload_cost) * total_slots as u64
        + (cold_account_access_cost - warm_account_access_cost) * contracts_accessed.len() as u64;
 
    println!("Potential gas savings:");
    println!("  Contracts accessed: {}", contracts_accessed.len());
    println!("  Total storage slots: {}", total_slots);
    println!("  Estimated gas saved: {}", potential_savings);
}

TransactionReceipt

pub struct TransactionReceipt {
    pub state_root: Vec<u8>,
    pub cumulative_gas_used: u64,
    pub logs_bloom: Vec<u8>,
    pub logs: Vec<Log>,
    pub status: i32,
    pub contract_address: Option<Vec<u8>>,
    pub effective_gas_price: Option<BigInt>,
    pub blob_gas_price: Option<BigInt>,
    pub blob_gas_used: Option<u64>,
}

Fields and Use Cases

state_root

  • Description: The state root after the transaction execution (only for pre-Byzantium transactions)
  • Use Case: Verify the state changes in older transactions
  • Example: 
    fn check_state_root(receipt: &TransactionReceipt) {
    if !receipt.state_root.is_empty() {
        println!("Pre-Byzantium transaction detected");
        println!("State root: {:?}", receipt.state_root);
    }
}

cumulative_gas_used

  • Description: The total amount of gas used in the block up to and including this transaction
  • Use Case: Track gas usage within a block
  • Example: 
    fn analyze_gas_usage(receipt: &TransactionReceipt) {
    println!("Cumulative gas used: {}", receipt.cumulative_gas_used);
    if receipt.cumulative_gas_used > 15_000_000 {
        println!("High gas usage block detected");
    }
}

logs_bloom

  • Description: Bloom filter for light clients to quickly retrieve related logs
  • Use Case: Efficiently check if the transaction might have emitted specific logs
  • Example: 
    fn check_potential_event(receipt: &TransactionReceipt, event_signature: &[u8]) {
    if bloom_filter_contains(&receipt.logs_bloom, event_signature) {
        println!("Transaction potentially contains the specified event");
    }
}
 
fn bloom_filter_contains(bloom: &[u8], data: &[u8]) -> bool {
    // Simplified bloom filter check (actual implementation would be more complex)
    bloom.iter().any(|&byte| byte & data[0] != 0)
}

logs

  • Description: List of log entries the transaction generated
  • Use Case: Analyze events emitted during the transaction
  • Example: 
    fn analyze_uniswap_v3_events(receipt: &TransactionReceipt) {
    for log in &receipt.logs {
        if log.address == UNISWAP_V3_POOL_ADDRESS {
            match log.topics.get(0) {
                Some(topic) if topic == &SWAP_EVENT_SIGNATURE => {
                    println!("Uniswap V3 Swap event detected");
                    // Further analysis of swap event data
                },
                Some(topic) if topic == &MINT_EVENT_SIGNATURE => {
                    println!("Uniswap V3 Mint event detected");
                    // Analysis of liquidity provision
                },
                Some(topic) if topic == &BURN_EVENT_SIGNATURE => {
                    println!("Uniswap V3 Burn event detected");
                    // Analysis of liquidity removal
                },
                _ => println!("Other Uniswap V3 event or unrelated log"),
            }
        }
    }
}

status

  • Description: Status of the transaction (1 for success, 0 for failure)
  • Use Case: Quickly determine if a transaction was successful
  • Example: 
    fn check_transaction_status(receipt: &TransactionReceipt) {
    match receipt.status {
        1 => println!("Transaction succeeded"),
        0 => println!("Transaction failed"),
        _ => println!("Unknown transaction status: {}", receipt.status),
    }
}

contract_address

  • Description: The contract address created, if the transaction was a contract creation
  • Use Case: Track new contract deployments
  • Example: 
    fn check_contract_creation(receipt: &TransactionReceipt) {
    if let Some(address) = &receipt.contract_address {
        println!("New contract created at address: {:?}", address);
    }
}

effective_gas_price, blob_gas_price, blob_gas_used

  • Description: Gas pricing information, including blob-related fields for EIP-4844
  • Use Case: Analyze transaction costs and blob usage
  • Example: 
    fn analyze_gas_pricing(receipt: &TransactionReceipt) {
    if let Some(price) = &receipt.effective_gas_price {
        println!("Effective gas price: {} wei", price);
    }
    if let Some(blob_price) = &receipt.blob_gas_price {
        println!("Blob gas price: {} wei", blob_price);
    }
    if let Some(blob_gas) = receipt.blob_gas_used {
        println!("Blob gas used: {}", blob_gas);
    }
}

Important Notes

  • TransactionReceipt provides crucial information about the execution and effects of a transaction.
  • The logs field is particularly important for event-driven applications and indexers.
  • The status field was introduced in the Byzantium hard fork. For pre-Byzantium transactions, success is inferred from the presence of the state_root.
  • Blob-related fields are only relevant for transactions that use EIP-4844 blob transactions.

Log

pub struct Log {
    pub address: Vec<u8>,
    pub topics: Vec<Vec<u8>>,
    pub data: Vec<u8>,
    pub index: u32,
    pub block_index: u32,
    pub ordinal: u64,
}

Fields and Use Cases

address

  • Description: Address of the contract that emitted the log
  • Use Case: Identify which contract generated the event
  • Example: 
    fn identify_log_source(log: &Log) {
    println!("Log emitted by contract: {:?}", log.address);
    if log.address == UNISWAP_V3_POOL_ADDRESS {
        println!("Uniswap V3 pool event detected");
    }
}

topics

  • Description: Indexed parameters of the event
  • Use Case: Efficiently filter and categorize events
  • Example: 
    fn analyze_event_type(log: &Log) {
    if !log.topics.is_empty() {
        let event_signature = &log.topics[0];
        match event_signature.as_slice() {
            SWAP_EVENT_SIGNATURE => println!("Swap event detected"),
            MINT_EVENT_SIGNATURE => println!("Mint event detected"),
            BURN_EVENT_SIGNATURE => println!("Burn event detected"),
            _ => println!("Other event type: {:?}", event_signature),
        }
    }
}

data

  • Description: Non-indexed parameters of the event
  • Use Case: Access additional event data
  • Example: 
    fn decode_swap_event(log: &Log) {
    if log.topics[0] == SWAP_EVENT_SIGNATURE {
        // Assuming data contains amount0, amount1, sqrtPriceX96, and liquidity
        let amount0 = BigInt::from_bytes_le(Sign::Plus, &log.data[0..32]);
        let amount1 = BigInt::from_bytes_le(Sign::Plus, &log.data[32..64]);
        println!("Swap amounts: {} {}", amount0, amount1);
    }
}

index, block_index

  • Description: Index of the log within the transaction and block
  • Use Case: Determine the order of events
  • Example: 
    fn analyze_event_sequence(log: &Log) {
    println!("Event index in transaction: {}", log.index);
    println!("Event index in block: {}", log.block_index);
}

ordinal

  • Description: Global ordinal of the log
  • Use Case: Establish a global order of events across blocks
  • Example: 
    fn track_global_event_order(logs: &[Log]) {
    let mut sorted_logs = logs.to_vec();
    sorted_logs.sort_by_key(|l| l.ordinal);
    for (i, log) in sorted_logs.iter().enumerate() {
        println!("Global event {}: Ordinal {}, Contract {:?}", 
                 i + 1, log.ordinal, log.address);
    }
}

Important Notes

  • Logs are crucial for tracking on-chain events and are often used as the primary data source for indexing and analyzing blockchain activity.
  • The topics field typically contains the event signature as the first element, followed by indexed parameters.
  • The data field contains non-indexed parameters and requires knowledge of the event structure for proper decoding.
  • Logs are particularly important in Uniswap V3 for tracking swaps, mints, burns, and other pool events.

Example Use Case: Analyzing Uniswap V3 Swap Events

fn analyze_uniswap_v3_swaps(logs: &[Log]) {
    for log in logs {
        if log.address == UNISWAP_V3_POOL_ADDRESS && log.topics[0] == SWAP_EVENT_SIGNATURE {
            let sender = &log.topics[1];
            let recipient = &log.topics[2];
            
            // Decode data (example assumes specific data layout)
            let amount0 = BigInt::from_bytes_le(Sign::Plus, &log.data[0..32]);
            let amount1 = BigInt::from_bytes_le(Sign::Plus, &log.data[32..64]);
            let sqrt_price_x96 = BigInt::from_bytes_le(Sign::Plus, &log.data[64..96]);
            let liquidity = BigInt::from_bytes_le(Sign::Plus, &log.data[96..128]);
 
            println!("Uniswap V3 Swap detected:");
            println!("  Sender: {:?}", sender);
            println!("  Recipient: {:?}", recipient);
            println!("  Amount0: {}", amount0);
            println!("  Amount1: {}", amount1);
            println!("  SqrtPriceX96: {}", sqrt_price_x96);
            println!("  Liquidity: {}", liquidity);
            println!("  Transaction Index: {}", log.index);
            println!("  Block Index: {}", log.block_index);
            println!("  Global Ordinal: {}", log.ordinal);
        }
    }
}

This example demonstrates how to parse and analyze Uniswap V3 Swap events from logs, extracting key information about each swap.

Additional Context

  • Log analysis is fundamental to many blockchain indexing and analytics tasks.
  • For complex smart contracts like Uniswap V3, logs often provide more gas-efficient and easier-to-access data compared to reading contract state.
  • When working with logs, it’s important to have a clear understanding of the event signatures and parameter encodings for the contracts you’re analyzing.
  • The ordinal field can be particularly useful for maintaining a consistent global order of events, especially when processing data across multiple blocks or in parallel.

Call

pub struct Call {
    pub index: u32,
    pub parent_index: u32,
    pub depth: u32,
    pub call_type: i32,
    pub caller: Vec<u8>,
    pub address: Vec<u8>,
    pub value: Option<BigInt>,
    pub gas_limit: u64,
    pub gas_consumed: u64,
    pub return_data: Vec<u8>,
    pub input: Vec<u8>,
    pub executed_code: bool,
    pub suicide: bool,
    pub status_failed: bool,
    pub error: String,
    pub status_reverted: bool,
    pub keccak_preimages: HashMap<String, String>,
    pub storage_changes: Vec<StorageChange>,
    pub balance_changes: Vec<BalanceChange>,
    pub nonce_changes: Vec<NonceChange>,
    pub logs: Vec<Log>,
    pub code_changes: Vec<CodeChange>,
    pub gas_changes: Vec<GasChange>,
    pub state_reverted: bool,
    pub begin_ordinal: u64,
    pub end_ordinal: u64,
    pub account_creations: Vec<AccountCreation>,
}

CallType

pub enum CallType {
    Unspecified = 0,
    Call = 1,       // Standard call to external contract/EOA
    Callcode = 2,   // Legacy call type, similar to delegatecall
    Delegate = 3,   // Delegatecall - executes code in caller's context
    Static = 4,     // Static call - prevents state modifications
    Create = 5,     // Contract creation call
}

Fields and Use Cases

index, parent_index, depth

  • Description: Positioning of the call within the transaction’s call tree
  • Use Case: Analyze call stack and trace execution flow
  • Example: 
    fn analyze_call_depth(call: &Call) {
    println!("Call index: {}, Parent index: {}, Depth: {}", 
             call.index, call.parent_index, call.depth);
    if call.depth > 10 {
        println!("Warning: Deep call stack detected");
    }
}

call_type

  • Description: Type of call (UNSPECIFIED, CALL, CALLCODE, DELEGATE, STATIC, CREATE)
  • Use Case: Differentiate between various types of contract interactions
  • Example: 
    fn categorize_call(call: &Call) {
    match call.call_type {
        0 => println!("Unspecified call"),
        1 => println!("Regular call"),
        2 => println!("Callcode"),
        3 => println!("Delegate call"),
        4 => println!("Static call"),
        5 => println!("Contract creation"),
        _ => println!("Unknown call type"),
    }
}

caller, address

  • Description: Addresses of the caller and the contract being called
  • Use Case: Track contract interactions and identify frequently used contracts
  • Example: 
    fn check_uniswap_interaction(call: &Call) {
    if call.address == UNISWAP_V3_ROUTER_ADDRESS {
        println!("Uniswap V3 Router interaction detected");
        println!("Caller: {:?}", call.caller);
    }
}

value, gas_limit, gas_consumed

  • Description: Ether transferred, gas limit, and actual gas used in the call
  • Use Case: Analyze transaction costs and efficiency
  • Example: 
    fn analyze_call_efficiency(call: &Call) {
    if let Some(value) = &call.value {
        println!("Value transferred: {} wei", value);
    }
    let gas_efficiency = (call.gas_consumed as f64) / (call.gas_limit as f64) * 100.0;
    println!("Gas efficiency: {:.2}%", gas_efficiency);
}

input, return_data

  • Description: Input data for the call and data returned by the call
  • Use Case: Decode function calls and analyze contract responses
  • Example: 
    fn decode_erc20_transfer(call: &Call) {
    if call.input.len() >= 4 && call.input[0..4] == [0xa9, 0x05, 0x9c, 0xbb] {
        println!("ERC20 transfer detected");
        // Further decoding of transfer parameters
    }
}

executed_code, suicide, status_failed, status_reverted

  • Description: Execution status flags
  • Use Case: Quickly identify call outcomes and potential issues
  • Example: 
    fn check_call_status(call: &Call) {
    if call.status_failed || call.status_reverted {
        println!("Call failed or reverted");
        if !call.error.is_empty() {
            println!("Error: {}", call.error);
        }
    }
    if call.suicide {
        println!("Contract self-destructed");
    }
}

storage_changes, balance_changes, nonce_changes, code_changes

  • Description: Lists of state changes caused by the call
  • Use Case: Track contract state modifications and token transfers
  • Example: 
    fn analyze_state_changes(call: &Call) {
    for change in &call.storage_changes {
        println!("Storage change at {:?}: {:?} -> {:?}", 
                 change.address, change.old_value, change.new_value);
    }
    for change in &call.balance_changes {
        println!("Balance change for {:?}: {:?} -> {:?}", 
                 change.address, change.old_value, change.new_value);
    }
}

logs

  • Description: List of logs emitted during the call
  • Use Case: Monitor contract events and extract indexed data
  • Example: 
    fn process_transfer_events(call: &Call) {
    for log in &call.logs {
        if log.topics.len() == 3 && log.topics[0] == TRANSFER_EVENT_SIGNATURE {
            println!("Transfer event detected");
            println!("From: {:?}", log.topics[1]);
            println!("To: {:?}", log.topics[2]);
            println!("Value: {:?}", log.data);
        }
    }
}

begin_ordinal, end_ordinal

  • Description: Global ordinals for call execution start and end
  • Use Case: Determine precise ordering of events within a transaction
  • Example: 
    fn calculate_call_duration(call: &Call) {
    let duration = call.end_ordinal - call.begin_ordinal;
    println!("Call duration (in ordinals): {}", duration);
}

Important Notes

  • The Call struct provides a comprehensive view of contract interactions within a transaction.
  • The call_type field is crucial for understanding the nature of the interaction (e.g., regular call vs. contract creation).
  • State changes (storage_changes, balance_changes, etc.) allow for detailed analysis of contract behavior and token movements.
  • The logs field is particularly useful for tracking events emitted by contracts, such as ERC-20 transfers.
  • The keccak_preimages field can be used to reverse-engineer certain hashed values used in the call.

StorageChange

pub struct StorageChange {
    pub address: Vec<u8>,
    pub key: Vec<u8>,
    pub old_value: Vec<u8>,
    pub new_value: Vec<u8>,
    pub ordinal: u64,
}

Fields and Use Cases

address

  • Description: Address of the contract whose storage is being changed
  • Use Case: Identify which contract’s state is being modified
  • Example: 
    fn track_contract_changes(change: &StorageChange) {
    println!("Storage change detected for contract: {:?}", change.address);
    if change.address == UNISWAP_V3_POOL_ADDRESS {
        println!("Uniswap V3 pool state change detected");
    }
}

key

  • Description: Storage key being modified
  • Use Case: Identify specific state variables within the contract
  • Example: 
    fn analyze_storage_slot(change: &StorageChange) {
    println!("Storage slot modified: {:?}", change.key);
    if change.key == UNISWAP_V3_LIQUIDITY_SLOT {
        println!("Liquidity change in Uniswap V3 pool");
    }
}

old_value, new_value

  • Description: Previous and new values at the storage key
  • Use Case: Track the nature and magnitude of state changes
  • Example: 
    fn calculate_value_change(change: &StorageChange) {
    let old_value = BigInt::from_bytes_be(Sign::Plus, &change.old_value);
    let new_value = BigInt::from_bytes_be(Sign::Plus, &change.new_value);
    let delta = &new_value - &old_value;
    println!("Value change: {}", delta);
    if delta > BigInt::from(1000000000000000000u64) { // 1 ETH
        println!("Large value change detected!");
    }
}

ordinal

  • Description: The block’s global ordinal when the storage change was recorded
  • Use Case: Determine the exact sequence of state changes within a transaction
  • Example: 
    fn sequence_storage_changes(changes: &[StorageChange]) {
    let mut sorted_changes = changes.to_vec();
    sorted_changes.sort_by_key(|c| c.ordinal);
    for (index, change) in sorted_changes.iter().enumerate() {
        println!("Change {}: Ordinal {}", index + 1, change.ordinal);
    }
}

Important Notes

  • StorageChange is crucial for understanding how contract states evolve during transaction execution.
  • The key field often corresponds to specific variables in the contract’s storage layout. Knowledge of the contract’s structure is helpful for meaningful interpretation.
  • Changes to certain storage slots can indicate significant events, such as token transfers, liquidity changes in AMMs, or governance actions.
  • The ordinal field allows for precise sequencing of state changes, which can be critical in understanding complex contract interactions.
  • When analyzing StorageChanges, it’s often necessary to consider the context of the overall transaction and the specific contract being interacted with.
  • For contracts with upgradeable proxies, storage changes might need to be interpreted differently based on the current implementation contract.

Example Use Case: Tracking Uniswap V3 Pool Changes

fn analyze_uniswap_v3_pool_changes(changes: &[StorageChange]) {
    for change in changes {
        if change.address == UNISWAP_V3_POOL_ADDRESS {
            match change.key.as_slice() {
                LIQUIDITY_SLOT => {
                    let old_liquidity = BigInt::from_bytes_be(Sign::Plus, &change.old_value);
                    let new_liquidity = BigInt::from_bytes_be(Sign::Plus, &change.new_value);
                    println!("Liquidity changed from {} to {}", old_liquidity, new_liquidity);
                },
                SQRT_PRICE_X96_SLOT => {
                    let old_price = calculate_price_from_sqrt_price_x96(&change.old_value);
                    let new_price = calculate_price_from_sqrt_price_x96(&change.new_value);
                    println!("Price changed from {} to {}", old_price, new_price);
                },
                _ => println!("Other Uniswap V3 pool storage change: {:?}", change.key),
            }
        }
    }
}
 
fn calculate_price_from_sqrt_price_x96(sqrt_price_x96: &[u8]) -> f64 {
    // Implementation to convert sqrtPriceX96 to human-readable price
    // This is a placeholder and would need actual implementation
    0.0
}

BalanceChange

pub struct BalanceChange {
    pub address: Vec<u8>,
    pub old_value: Option<BigInt>,
    pub new_value: Option<BigInt>,
    pub reason: i32,
    pub ordinal: u64,
}

Reason

pub enum Reason {
    Unknown = 0,
    RewardMineUncle = 1,      // Reward for including uncle blocks (PoW)
    RewardMineBlock = 2,      // Block reward for mining/validating
    DaoRefundContract = 3,    // Historical DAO fork refunds
    DaoAdjustBalance = 4,     // Historical DAO fork balance adjustments
    Transfer = 5,             // Standard ETH transfer
    GenesisBalance = 6,       // Initial genesis block balances
    GasBuy = 7,               // Gas purchases for transaction execution
    RewardTransactionFee = 8, // Transaction fee rewards
    GasRefund = 9,            // Gas refunds from storage operations
    TouchAccount = 10,        // Account accessed during execution
    SuicideRefund = 11,       // Refund from contract self-destruct
    CallBalanceOverride = 12, // Balance changes from call operations
    SuicideWithdraw = 13,     // Withdrawal of funds during self-destruct
    RewardFeeReset = 14,      // Fee resets in certain scenarios
    Burn = 15,                // ETH burning (e.g., EIP-1559 base fee)
    Withdrawal = 16,          // PoS validator withdrawals
    RewardBlobFee = 17,       // Blob transaction fee rewards
    IncreaseMint = 18,        // Optimism chain-specific minting
 
    //is crucial for tracking ETH movements and understanding the economic flow in Ethereum. The `Burn` reason became particularly important after EIP-1559 where base fees are burned.
}

Fields and Use Cases

address

  • Description: Address of the account whose balance is changing
  • Use Case: Identify which account’s balance is being modified
  • Example: 
    fn track_balance_changes(change: &BalanceChange) {
    println!("Balance change detected for account: {:?}", change.address);
    if change.address == UNISWAP_V3_POOL_ADDRESS {
        println!("Uniswap V3 pool balance change detected");
    }
}

old_value, new_value

  • Description: Previous and new balance values
  • Use Case: Calculate the magnitude of balance changes
  • Example: 
    fn calculate_balance_change(change: &BalanceChange) {
    if let (Some(old), Some(new)) = (&change.old_value, &change.new_value) {
        let delta = new - old;
        println!("Balance change: {} wei", delta);
        if delta > BigInt::from(1000000000000000000u64) { // 1 ETH
            println!("Large balance change detected!");
        }
    }
}

reason

  • Description: Reason for the balance change
  • Use Case: Categorize and analyze different types of balance changes
  • Example: 
    fn analyze_balance_change_reason(change: &BalanceChange) {
    match change.reason {
        0 => println!("Unknown reason"),
        1 => println!("Block reward"),
        2 => println!("Transaction fee"),
        3 => println!("Value transfer"),
        4 => println!("Contract creation"),
        5 => println!("Contract self-destruct"),
        6 => println!("Withdrawal"),
        _ => println!("Other reason: {}", change.reason),
    }
}

ordinal

  • Description: The block’s global ordinal when the balance change was recorded
  • Use Case: Determine the exact sequence of balance changes within a transaction
  • Example: 
    fn sequence_balance_changes(changes: &[BalanceChange]) {
    let mut sorted_changes = changes.to_vec();
    sorted_changes.sort_by_key(|c| c.ordinal);
    for (index, change) in sorted_changes.iter().enumerate() {
        println!("Change {}: Ordinal {}", index + 1, change.ordinal);
    }
}

Important Notes

  • BalanceChange is crucial for tracking Ether movements across accounts, including both EOAs and contract accounts.
  • The reason field provides valuable context about why the balance change occurred, which can be particularly useful for identifying different types of transactions or system-level operations.
  • Balance changes with reason “Block reward” or “Transaction fee” are particularly interesting for analyzing miner/validator rewards and network usage.
  • When analyzing BalanceChanges, it’s important to consider the context of the overall transaction and block.
  • The ordinal field allows for precise sequencing of balance changes, which can be critical in understanding complex interactions involving multiple transfers.

Example Use Case: Analyzing Uniswap V3 Swap Impact

fn analyze_uniswap_v3_swap_impact(changes: &[BalanceChange]) {
    let mut total_fee = BigInt::from(0);
    let mut token_transfers = Vec::new();
 
    for change in changes {
        match change.reason {
            2 => { // Transaction fee
                if let (Some(old), Some(new)) = (&change.old_value, &change.new_value) {
                    total_fee += new - old;
                }
            },
            3 => { // Value transfer
                if change.address == UNISWAP_V3_POOL_ADDRESS {
                    if let (Some(old), Some(new)) = (&change.old_value, &change.new_value) {
                        let delta = new - old;
                        token_transfers.push(delta);
                    }
                }
            },
            _ => {}
        }
    }
 
    println!("Total transaction fee: {} wei", total_fee);
    println!("Token transfers in Uniswap V3 pool:");
    for (index, transfer) in token_transfers.iter().enumerate() {
        println!("  Transfer {}: {} wei", index + 1, transfer);
    }
}

Additional Context

  • Balance changes can occur for reasons beyond simple transfers, such as mining rewards, gas refunds, or contract self-destructs.
  • In the context of Uniswap V3, balance changes can indicate liquidity additions/removals, swap fees collected, or protocol fees paid.
  • When working with balance changes, always consider the possibility of overflow/underflow in large numbers and use appropriate big integer libraries.

NonceChange

pub struct NonceChange {
    pub address: Vec<u8>,
    pub old_value: u64,
    pub new_value: u64,
    pub ordinal: u64,
}

Fields and Use Cases

address

  • Description: Address of the account whose nonce is changing
  • Use Case: Identify which account’s transaction count is being modified
  • Example: 
    fn track_nonce_changes(change: &NonceChange) {
    println!("Nonce change detected for account: {:?}", change.address);
    if change.address == UNISWAP_V3_ROUTER_ADDRESS {
        println!("Uniswap V3 router nonce change detected");
    }
}

old_value, new_value

  • Description: Previous and new nonce values
  • Use Case: Track account activity and ensure transaction ordering
  • Example: 
    fn analyze_nonce_increment(change: &NonceChange) {
    let increment = change.new_value - change.old_value;
    println!("Nonce increased by: {}", increment);
    if increment > 1 {
        println!("Multiple transactions in a single block detected!");
    }
}

ordinal

  • Description: The block’s global ordinal when the nonce change was recorded
  • Use Case: Determine the exact sequence of nonce changes within a transaction or block
  • Example: 
    fn sequence_nonce_changes(changes: &[NonceChange]) {
    let mut sorted_changes = changes.to_vec();
    sorted_changes.sort_by_key(|c| c.ordinal);
    for (index, change) in sorted_changes.iter().enumerate() {
        println!("Change {}: Ordinal {}, Address {:?}", 
                 index + 1, change.ordinal, change.address);
    }
}

Important Notes

  • NonceChange is crucial for tracking account activity and ensuring proper transaction ordering.
  • For EOAs (Externally Owned Accounts), nonce changes indicate outgoing transactions.
  • For contract accounts, nonce changes typically indicate contract deployments.
  • The difference between new_value and old_value is usually 1, but can be more in cases of multiple transactions per block or certain types of contract interactions.
  • Nonce tracking is essential for preventing replay attacks and ensuring transaction uniqueness.

Example Use Case: Analyzing Account Activity

fn analyze_account_activity(changes: &[NonceChange]) {
    let mut account_activity = HashMap::new();
 
    for change in changes {
        let activity_count = account_activity.entry(change.address.clone())
            .or_insert(0);
        *activity_count += 1;
 
        if change.new_value - change.old_value > 1 {
            println!("Multiple nonce increments for account {:?}: {} to {}", 
                     change.address, change.old_value, change.new_value);
        }
    }
 
    println!("Account activity summary:");
    for (address, count) in account_activity.iter() {
        println!("Account {:?}: {} nonce changes", address, count);
        if *count > 5 {
            println!("  High activity detected for this account!");
        }
    }
}

This example demonstrates how to analyze nonce changes to understand account activity levels and detect unusual patterns, such as multiple nonce increments in a single transaction or block.

Additional Context

  • In the context of Uniswap V3, tracking nonce changes for the router contract or frequently interacting accounts can provide insights into trading activity and contract deployments.
  • Nonce changes are particularly important when dealing with account abstraction or meta-transactions, where nonce management might differ from standard EOAs.
  • For some Layer 2 solutions or sidechains, nonce behavior might differ from the Ethereum mainnet, so it’s important to consider the specific network context.
  • Monitoring nonce gaps (e.g., jumps from nonce 5 to nonce 8) can help identify potential issues with transaction ordering or missed transactions.

Example: Detecting Potential Contract Deployments

fn detect_contract_deployments(changes: &[NonceChange]) {
    for change in changes {
        if change.old_value == 0 && change.new_value == 1 {
            println!("Potential contract deployment detected:");
            println!("  Address: {:?}", change.address);
            println!("  Ordinal: {}", change.ordinal);
        }
    }
}

This example shows how to use nonce changes to detect potential contract deployments, which typically occur when an account’s nonce changes from 0 to 1.

AccountCreation

pub struct AccountCreation {
    pub account: Vec<u8>,
    pub ordinal: u64,
}

Fields and Use Cases

account

  • Description: Address of the newly created account
  • Use Case: Identify new accounts created during contract deployments or other events

ordinal

  • Description: Global ordinal of when the account creation occurred
  • Use Case: Establish the exact sequence of account creations

CodeChange

pub struct CodeChange {
    pub address: Vec<u8>,
    pub old_hash: Vec<u8>,
    pub new_hash: Vec<u8>,
    pub code: Vec<u8>,
    pub ordinal: u64,
}

Fields and Use Cases

address

  • Description: Address of the contract whose code is changing
  • Use Case: Identify which contract is being created, updated, or destroyed
  • Example: 
    fn track_code_changes(change: &CodeChange) {
    println!("Code change detected for contract: {:?}", change.address);
    if change.address == UNISWAP_V3_FACTORY_ADDRESS {
        println!("Uniswap V3 factory code change detected!");
    }
}

old_hash, new_hash

  • Description: Hash of the contract’s code before and after the change
  • Use Case: Quickly detect if a contract’s code has changed and verify integrity
  • Example: 
    fn analyze_code_change_type(change: &CodeChange) {
    if change.old_hash.is_empty() {
        println!("New contract deployed at {:?}", change.address);
    } else if change.new_hash.is_empty() {
        println!("Contract destroyed at {:?}", change.address);
    } else {
        println!("Contract code updated at {:?}", change.address);
        println!("Old hash: {:?}", change.old_hash);
        println!("New hash: {:?}", change.new_hash);
    }
}

code

  • Description: New bytecode of the contract
  • Use Case: Analyze the actual code changes or verify deployed contracts
  • Example: 
    fn analyze_new_code(change: &CodeChange) {
    if !change.code.is_empty() {
        println!("New code size: {} bytes", change.code.len());
        if change.code.starts_with(&[0x60, 0x80, 0x60, 0x40, 0x52]) {
            println!("Standard Solidity contract detected");
        }
        // Further bytecode analysis can be performed here
    }
}

ordinal

  • Description: Global ordinal of when the code change occurred
  • Use Case: Establish the exact sequence of code changes
  • Example: 
    fn sequence_code_changes(changes: &[CodeChange]) {
    let mut sorted_changes = changes.to_vec();
    sorted_changes.sort_by_key(|c| c.ordinal);
    for (index, change) in sorted_changes.iter().enumerate() {
        println!("Change {}: Ordinal {}, Address {:?}", 
                 index + 1, change.ordinal, change.address);
    }
}

Important Notes

  • CodeChange is crucial for tracking contract deployments, upgrades, and self-destructs.
  • An empty old_hash typically indicates a new contract deployment.
  • An empty new_hash usually signifies a contract self-destruct operation.
  • For upgradeable contracts, you might see changes to the same address multiple times.
  • The code field allows for deep analysis of contract behavior and security auditing.

Example Use Case: Monitoring Uniswap V3 Contract Deployments

fn monitor_uniswap_v3_deployments(changes: &[CodeChange]) {
    for change in changes {
        if change.old_hash.is_empty() {  // New deployment
            if is_uniswap_v3_pool_bytecode(&change.code) {
                println!("New Uniswap V3 pool deployed:");
                println!("  Address: {:?}", change.address);
                println!("  Code hash: {:?}", change.new_hash);
                println!("  Deployment ordinal: {}", change.ordinal);
                
                // Additional analysis can be performed here, such as:
                // - Extracting pool parameters from the bytecode
                // - Checking for any deviations from expected Uniswap V3 pool code
            }
        }
    }
}
 
fn is_uniswap_v3_pool_bytecode(code: &[u8]) -> bool {
    // This is a simplified check and should be replaced with a more robust verification
    // You might want to check for specific bytecode patterns or known constants
    code.len() > 1000 && code.starts_with(&[0x60, 0x80, 0x60, 0x40, 0x52])
}

This example demonstrates how to monitor for new Uniswap V3 pool deployments by analyzing CodeChange events.

Additional Context

  • In the context of Uniswap V3, CodeChanges are particularly important for tracking the deployment of new pool contracts.
  • For upgradeable proxy patterns, you might see frequent code changes at proxy addresses.
  • CodeChanges can be used to detect potential security issues, such as unexpected changes to critical contracts.
  • When analyzing CodeChanges, it’s often useful to compare the new bytecode against known good versions or to decompile it for further analysis.
  • In some cases, especially with optimized contracts, small changes in source code can result in significantly different bytecode, so hash comparisons alone may not always indicate the magnitude of changes.

Example: Detecting Potential Proxy Upgrades

This example shows how to detect potential proxy contract upgrades, which is a common pattern in upgradeable smart contract systems.

fn detect_proxy_upgrades(changes: &[CodeChange]) {
    for change in changes {
        if !change.old_hash.is_empty() && !change.new_hash.is_empty() {
            println!("Potential proxy upgrade detected:");
            println!("  Address: {:?}", change.address);
            println!("  Old hash: {:?}", change.old_hash);
            println!("  New hash: {:?}", change.new_hash);
            println!("  Upgrade ordinal: {}", change.ordinal);
            
            // Here you might want to:
            // - Compare the new code against known implementations
            // - Check for any unexpected changes in contract behavior
            // - Verify that the upgrade was performed by authorized addresses
        }
    }
}

GasChange

pub struct GasChange {
    pub old_value: u64,
    pub new_value: u64,
    pub reason: i32,
    pub ordinal: u64,
}

Reason

pub enum Reason {
    Unknown = 0,
    Call = 1,                    // Standard contract calls
    CallCode = 2,                // Legacy callcode operations
    CallDataCopy = 3,            // Copying calldata to memory
    CodeCopy = 4,                // Copying code to memory
    CodeStorage = 5,             // Contract code storage
    ContractCreation = 6,        // CREATE opcode execution
    ContractCreation2 = 7,       // CREATE2 opcode execution
    DelegateCall = 8,            // DELEGATECALL opcode
    EventLog = 9,                // LOG0-LOG4 operations
    ExtCodeCopy = 10,            // EXTCODECOPY opcode
    FailedExecution = 11,        // Failed transaction execution
    IntrinsicGas = 12,          // Base transaction gas cost
    PrecompiledContract = 13,    // Built-in contract execution
    RefundAfterExecution = 14,   // Post-execution gas refunds
    Return = 15,                 // RETURN opcode
    ReturnDataCopy = 16,         // RETURNDATACOPY opcode
    Revert = 17,                 // REVERT opcode
    SelfDestruct = 18,          // SELFDESTRUCT opcode
    StaticCall = 19,            // STATICCALL opcode
    StateColdAccess = 20,       // EIP-2929 cold access costs
    TxInitialBalance = 21,      // Initial transaction gas balance
    TxRefunds = 22,             // Transaction refunds
    TxLeftOverReturned = 23,    // Unused gas returned
    CallInitialBalance = 24,    // Initial call frame gas balance
    CallLeftOverReturned = 25,  // Unused call frame gas returned
}

Fields and Use Cases

old_value, new_value

  • Description: Previous and new gas values
  • Use Case: Track gas consumption throughout transaction execution
  • Example: 
    fn analyze_gas_change(change: &GasChange) {
    let gas_used = change.old_value - change.new_value;
    println!("Gas change: {} -> {}", change.old_value, change.new_value);
    println!("Gas consumed: {}", gas_used);
    if gas_used > 1_000_000 {
        println!("High gas consumption detected!");
    }
}

reason

  • Description: Reason for the gas change
  • Use Case: Categorize different types of gas consumption
  • Example: 
    fn categorize_gas_change(change: &GasChange) {
    match change.reason {
        0 => println!("REASON_UNKNOWN"),
        1 => println!("REASON_CALL"),
        2 => println!("REASON_CALL_CODE"),
        3 => println!("REASON_DELEGATE_CALL"),
        4 => println!("REASON_STATIC_CALL"),
        5 => println!("REASON_CREATE"),
        6 => println!("REASON_CREATE2"),
        7 => println!("REASON_CALL_NEW_ACCOUNT"),
        8 => println!("REASON_CALL_EMPTY_ACCOUNT"),
        9 => println!("REASON_CALL_VALUE_TRANSFER"),
        10 => println!("REASON_CALL_STIPEND"),
        11 => println!("REASON_MEMORY_EXPANSION"),
        12 => println!("REASON_MEMORY_COPY"),
        13 => println!("REASON_STORAGE_STORE"),
        14 => println!("REASON_STORAGE_MODIFY"),
        15 => println!("REASON_STORAGE_DELETE"),
        16 => println!("REASON_STORAGE_RESTORE"),
        17 => println!("REASON_INTRINSIC_GAS"),
        18 => println!("REASON_LOG_TOPIC"),
        19 => println!("REASON_LOG_DATA"),
        20 => println!("REASON_RETURN_DATA"),
        21 => println!("REASON_REFUND_SUICIDE"),
        22 => println!("REASON_REFUND_SSTORE_CLEARS"),
        _ => println!("Unknown reason: {}", change.reason),
    }
}

ordinal

  • Description: Global ordinal of when the gas change occurred
  • Use Case: Establish the exact sequence of gas changes within a transaction
  • Example: 
    fn sequence_gas_changes(changes: &[GasChange]) {
    let mut sorted_changes = changes.to_vec();
    sorted_changes.sort_by_key(|c| c.ordinal);
    for (index, change) in sorted_changes.iter().enumerate() {
        println!("Change {}: Ordinal {}, Gas change: {} -> {}", 
                 index + 1, change.ordinal, change.old_value, change.new_value);
    }
}

Important Notes

  • GasChange provides detailed insights into gas consumption during transaction execution.
  • The reason field is particularly useful for understanding which operations are consuming the most gas.
  • Analyzing gas changes can help optimize smart contracts and understand transaction costs.
  • In the context of Uniswap V3, gas changes can provide insights into the efficiency of various operations like swaps, mints, and burns.

Example Use Case: Analyzing Gas Usage in Uniswap V3 Operations

fn analyze_uniswap_v3_gas_usage(changes: &[GasChange]) {
    let mut total_gas_used = 0;
    let mut operation_gas = HashMap::new();
 
    for change in changes {
        let gas_used = change.old_value - change.new_value;
        total_gas_used += gas_used;
 
        let reason = match change.reason {
            1 => "CALL",
            5 => "CREATE",
            13 => "STORAGE_STORE",
            14 => "STORAGE_MODIFY",
            18 => "LOG_TOPIC",
            19 => "LOG_DATA",
            _ => "OTHER",
        };
 
        *operation_gas.entry(reason).or_insert(0) += gas_used;
    }
 
    println!("Total gas used: {}", total_gas_used);
    println!("Gas usage breakdown:");
    for (reason, gas) in operation_gas.iter() {
        let percentage = (*gas as f64 / total_gas_used as f64) * 100.0;
        println!("  {}: {} gas ({:.2}%)", reason, gas, percentage);
    }
}

Additional Context

  • Gas changes are crucial for understanding the economic costs of transactions and contract interactions.
  • In complex contracts like Uniswap V3, different operations (e.g., swaps, adding liquidity, removing liquidity) can have significantly different gas costs.
  • Monitoring gas changes can help detect potential gas-related attacks or inefficiencies in smart contracts.
  • When analyzing gas changes, it’s important to consider the current gas price and block gas limit to understand the full economic impact.

Example: Detecting Potential Gas-Intensive Operations

fn detect_gas_intensive_operations(changes: &[GasChange]) {
    const GAS_THRESHOLD: u64 = 100_000; // Adjust this threshold as needed
 
    for (i, change) in changes.iter().enumerate() {
        let gas_used = change.old_value - change.new_value;
        if gas_used > GAS_THRESHOLD {
            println!("Gas-intensive operation detected:");
            println!("  Operation index: {}", i);
            println!("  Gas used: {}", gas_used);
            println!("  Reason: {}", change.reason);
            println!("  Ordinal: {}", change.ordinal);
        }
    }
}

HeaderOnlyBlock

pub struct HeaderOnlyBlock {
    pub hash: Vec<u8>,
    pub number: u64,
    pub size: u64,
    pub header: Option<BlockHeader>,
}
  • hash: The unique identifier of the block (32 bytes)
  • number: The block number
  • size: The size of the block in bytes
  • header: The block header information (optional)

BlockWithRefs

pub struct BlockWithRefs {
    pub id: String,
    pub block: Option<Block>,
    pub transaction_trace_refs: Option<TransactionRefs>,
    pub irreversible: bool,
}
  • id: Identifier of the block
  • block: The block data (optional)
  • transaction_trace_refs: References to transaction traces (optional)
  • irreversible: Whether the block is considered irreversible

TransactionTraceWithBlockRef

pub struct TransactionTraceWithBlockRef {
    pub trace: Option<TransactionTrace>,
    pub block_ref: Option<BlockRef>,
}
  • trace: The transaction trace (optional)
  • block_ref: Reference to the block containing this transaction (optional)

TransactionRefs

pub struct TransactionRefs {
    pub hashes: Vec<Vec<u8>>,
}
  • hashes: List of transaction hashes

BlockRef

pub struct BlockRef {
    pub hash: Vec<u8>,
    pub number: u64,
}
  • hash: The unique identifier of the block (32 bytes)
  • number: The block number
Last updated on
CosmosSolana