Struct CallBuilder

pub struct CallBuilder<T, S, E> {
    pub tx: T,
    /* private fields */
}

Represents a prepared EVM contract call, ready for configuration and execution.

Instances are created via Contract::call_builder. The primary interaction involves configuring the transaction parameters via the public CallBuilder::tx field, followed by invoking an execution method like .call().

See the documentation on the Contract struct for a detailed explanation of the configuration workflow and examples.

Fields

tx: T

The transaction environment (EvmFactory::Tx) containing call parameters.

Configuration: This field holds the transaction details (caller, value, gas, etc.). It must be configured directly by modifying its members before calling an execution method.

Example: builder.tx.caller = MY_ADDRESS; builder.tx.gas_limit = 100_000;

Implementations

impl<S, F, N, P, C> CallBuilder<F::Tx, S, &mut EvmEnv<ProofDb<ProviderDb<N, P>>, F, HostCommit<C>>>

where N: Network, P: Provider<N> + Send + Sync + 'static, S: SolCall + Send + Sync + 'static, <S as SolCall>::Return: Send, F: EvmFactory,

pub async fn prefetch_access_list(self, access_list: AccessList) -> Result<Self>

Available on crate feature host only.

Prefetches state for a given EIP-2930 AccessList on the host.

Fetches EIP-1186 storage proofs for the items in the access_list. This can reduce the number of individual RPC calls (eth_getStorageAt) needed during subsequent execution simulation if the accessed slots are known beforehand.

This method only fetches data; it does not set the access list field on the transaction itself (EIP-2930).

Usage

Useful when an access list is already available. For automatic generation and prefetching, see CallBuilder::call_with_prefetch.

Example

let mut contract = Contract::preflight(contract_address, &mut env);
let builder = contract.call_builder(&call).prefetch_access_list(access_list).await?;
let result = builder.call().await?;

pub async fn call(self) -> Result<S::Return>

Available on crate feature host only.

Executes the configured call during host preflight.

This simulates the transaction execution using revm within a blocking thread (via [tokio::task::spawn_blocking]) to avoid blocking the async runtime. It uses the state fetched (and potentially prefetched) into the ProviderDb.

Returns the decoded return value of the call or an error if execution fails.

impl<S, P, C> CallBuilder<<EthEvmFactory as EvmFactory>::Tx, S, &mut EvmEnv<ProofDb<ProviderDb<Ethereum, P>>, EthEvmFactory, HostCommit<C>>>

where S: SolCall + Send + Sync + 'static, <S as SolCall>::Return: Send, P: Provider<Ethereum> + Send + Sync + 'static,

pub async fn call_with_prefetch(self) -> Result<S::Return>

Available on crate feature host only.

Automatically creates and prefetches an EIP-2930 access list, then executes the call.

This method aims to optimize host preflight time for calls involving numerous storage reads (SLOAD). It performs the following steps:

1. Calls eth_createAccessList RPC to determine the storage slots and accounts the transaction is likely to access.
2. Calls CallBuilder::prefetch_access_list with the generated list to fetch the required state efficiently (often in a single batch RPC).
3. Executes the call simulation using CallBuilder::call.

Trade-offs

• Node Compatibility: Relies on the eth_createAccessList RPC, which might not be available or fully supported on all Ethereum node software or chains.
• Gas Estimation Issues: Some node implementations might perform gas checks or require sufficient balance in the from account for eth_createAccessList, even for view calls. Setting a relevant from address might be necessary.

Example

let mut contract = Contract::preflight(contract_address, &mut env);
// Automatically generates access list, fetches state, and executes
let result = contract.call_builder(&call).call_with_prefetch().await?;

impl<S, F> CallBuilder<F::Tx, S, &EvmEnv<StateDb, F, Commitment>>

where S: SolCall, F: EvmFactory,

pub fn try_call(self) -> Result<S::Return, String>

Executes the call within the guest environment, returning a Result.

Use this if you need to handle potential EVM execution errors explicitly (e.g., reverts, halts) within the guest. The error type is String for simplicity in the guest context.

For straightforward calls where failure should halt guest execution, prefer CallBuilder::call.

pub fn call(self) -> S::Return

Executes the call within the guest environment, panicking on failure.

This is a convenience wrapper around CallBuilder::try_call. It unwraps the result, causing the guest to panic if the EVM call reverts, halts, or encounters an error. Use this when a successful call is expected.

Trait Implementations

impl<T: Clone, S: Clone, E: Clone> Clone for CallBuilder<T, S, E>

fn clone(&self) -> CallBuilder<T, S, E>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T: Debug, S: Debug, E: Debug> Debug for CallBuilder<T, S, E>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.