Struct Event

pub struct Event<S, E> { /* private fields */ }

Represents an EVM event query.

This query builder is designed for fetching specific Solidity events that occurred within the block associated with the provided EvmEnv.

Filtering Capabilities

This Event query builder is intentionally designed to mirror the structure and capabilities of the [alloy_rpc_types::Filter] type used in standard Ethereum RPC calls, adapted for the constraints of the RISC Zero zkVM environment.

You can filter events based on:

• Contract Addresses: Use the .address() method to specify the event source:
  • A single address matches only events from this address.
  • Multiple addresses (pass a Vec<Address>) matches events from any contract address.
  • Wildcard (default): If .address() is not called, or if an empty Vec is provided, it matches events from any contract address.
• Indexed Topics: Use the .topic1(), .topic2() and .topic3() to filter by the indexed arguments of the event:
  • A single value matches only events where the topic has this exact value.
  • Multiple values (pass a Vec<B256>) matches events where the topic matches any value in the list.
  • Wildcard (default): If .topicX() is not called or if an empty Vec is provided, it matches any value for that topic position.

Certain filtering options available in [alloy_rpc_types::Filter] are not applicable or are fixed within the Steel environment:

• Block Specification: The block context for the query is determined by the EvmEnv (retrieved via env.header()) used to create the Event query. You cannot specify a block range or a different block hash.
• Topic 0 (Event Signature): This topic is automatically set based on the SolEvent type parameter (S) provided to Event::new or Event::preflight (using S::SIGNATURE_HASH). It cannot be altered or set to a wildcard/list. Anonymous events (where S::ANONYMOUS is true) are not supported.

Usage

The usage pattern mirrors other Steel interactions like Contract:

• Preflight calls on the Host: To prepare the event query on the host environment and build the necessary proof, use Event::preflight.
• Calls in the Guest: To initialize the event query in the guest, use Event::new.

Examples

Basic usage with a single contract address:

let contract_address = address!("dAC17F958D2ee523a2206206994597C13D831ec7");
sol! {
    interface IERC20 {
        event Transfer(address indexed from, address indexed to, uint256 value);
    }
}

// Host:
let url = "https://ethereum-rpc.publicnode.com".parse()?;
let mut env = EthEvmEnv::builder().rpc(url).chain_spec(&ETH_MAINNET_CHAIN_SPEC).build().await?;
let event = Event::preflight::<IERC20::Transfer>(&mut env).address(contract_address);
event.query().await?;

let evm_input = env.into_input().await?;

// Guest:
let env = evm_input.into_env(&ETH_MAINNET_CHAIN_SPEC);
let event = Event::new::<IERC20::Transfer>(&env).address(contract_address);
let logs = event.query();

Advanced filtering with multiple addresses and topics:

// define multiple contract addresses and potential senders
let usdt_address = address!("dAC17F958D2ee523a2206206994597C13D831ec7");
let usdc_address = address!("A0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48");

sol! {
    interface IERC20 {
        event Transfer(address indexed from, address indexed to, uint256 value);
    }
}

let url = "https://ethereum-rpc.publicnode.com".parse()?;
let mut env = EthEvmEnv::builder().rpc(url).chain_spec(&ETH_MAINNET_CHAIN_SPEC).build().await?;

// Create an event query for Transfer events from *either* USDT or USDC contract,
// originating from *either* sender1 or sender2.
let event = Event::preflight::<IERC20::Transfer>(&mut env)
    // filter by contract address: Match USDT OR USDC
    .address(vec![usdt_address, usdc_address])
    // filter by topic 1 (`from`): Match sender1 OR sender2
    .topic1(vec![
        address!("0000000000000000000000000000000000000001").into_word(),
        address!("0000000000000000000000000000000000000002").into_word(),
    ]);
// topic2 (`to`) and topic3 are left as wildcards

let logs = event.query().await?;

Implementations

impl<D, F: EvmFactory, C> Event<(), &mut EvmEnv<ProofDb<D>, F, HostCommit<C>>>

where D: EvmDatabase + Send + 'static, <D as RevmDatabase>::Error: StdError + Send + Sync + 'static,

pub fn preflight<S: SolEvent>( env: &mut EvmEnv<ProofDb<D>, F, HostCommit<C>>, ) -> Event<S, &mut EvmEnv<ProofDb<D>, F, HostCommit<C>>>

Available on crate feature host only.

Constructor for preflighting an event query for a specific EVM event.

Initializes the environment for event queries, fetching necessary data via the Provider, and generating a storage proof for any accessed elements using EvmEnv::into_input.

impl<S: SolEvent, D, F: EvmFactory, C> Event<S, &mut EvmEnv<ProofDb<D>, F, HostCommit<C>>>

where D: EvmDatabase + Send + 'static, <D as RevmDatabase>::Error: StdError + Send + Sync + 'static,

pub async fn query(self) -> Result<Vec<Log<S>>>

Available on crate feature host only.

Executes the event query using an EvmEnv constructed with Event::preflight.

This uses [tokio::task::spawn_blocking] to run the blocking revm execution.

impl<F: EvmFactory> Event<(), &EvmEnv<StateDb, F, Commitment>>

pub fn new<S: SolEvent>( env: &EvmEnv<StateDb, F, Commitment>, ) -> Event<S, &EvmEnv<StateDb, F, Commitment>>

Constructor for executing an event query for a specific Solidity event.

impl<S: SolEvent, F: EvmFactory> Event<S, &EvmEnv<StateDb, F, Commitment>>

pub fn query(self) -> Vec<Log<S>>

Executes the query and returns the matching logs and panics on failure.

A convenience wrapper for Event::try_query, panicking if the call fails. Useful when success is expected.

pub fn try_query(self) -> Result<Vec<Log<S>>>

Attempts to execute the query and returns the matching logs or an error.

impl<S, E> Event<S, E>

pub fn address<T: Into<ValueOrArray<Address>>>(self, address: T) -> Self

Sets the address to query with this filter.

See [Filter::address].

pub fn topic1<T: Into<Topic>>(self, topic: T) -> Self

Sets the 1st indexed topic.

pub fn topic2<T: Into<Topic>>(self, topic: T) -> Self

Sets the 2nd indexed topic.

pub fn topic3<T: Into<Topic>>(self, topic: T) -> Self

Sets the 3rd indexed topic.