Struct Contract

pub struct Contract<E> { /* private fields */ }

Represents a contract instance for interacting with EVM environments.

This struct provides a way to interact with a deployed smart contract at a specific address within a given EVM environment E.

Note: This contract interaction is not type-safe regarding the ABI. Ensure the deployed contract at address matches the ABI used for calls (S: SolCall).

Usage Scenarios

1. Host (Preflight): Use Contract::preflight to set up calls on the host environment. The environment can be initialized using the EthEvmEnv::builder or EvmEnv::builder. This fetches necessary state and prepares proofs for guest execution.
   • Consider CallBuilder::call_with_prefetch for calls with many storage accesses to potentially optimize preflight time by reducing RPC calls.
2. Guest: Use Contract::new within the guest environment, typically initialized from EvmInput::into_env.

Making Contract Calls (Host Preflight or Guest Execution)

To interact with the contract’s functions, you use the Contract::call_builder method to prepare a call. This follows a specific workflow:

1. Create Builder: Call Contract::call_builder with a specific Solidity function call object (e.g., MyCall { arg1: ..., arg2: ... } derived using alloy_sol_types::sol!). This returns a CallBuilder instance, initializing its internal transaction environment (tx) with the contract address and call data.

2. Configure Transaction: Because the underlying transaction type (EvmFactory::Tx) is generic, configuration parameters (like caller address, value, gas limit, nonce) are set by directly modifying the public .tx field of the returned CallBuilder instance.

   let mut builder = contract.call_builder(&my_call);
   builder.tx.caller = Address::ZERO;
   builder.tx.value = U256::from(0); // Set value if payable
   builder.tx.gas_limit = 100_000;
   // ... set other fields like gas_price, nonce as needed

   Note: Fluent configuration methods like .from(address) or .value(amount) are not available directly on the CallBuilder due to this generic design. You must use direct field access on .tx. Consult the documentation of the specific Tx type provided by your chosen EvmFactory for available fields (e.g., revm::primitives::TxEnv).

3. Execute Call: Once configured, execute the call using the appropriate method on the CallBuilder instance. Common methods include:

   • .call(): Executes in the guest, panicking on EVM errors.
   • .try_call(): Executes in the guest, returning a Result for error handling.
   • .call().await: Executes preflight on the host (requires host feature).
   • .call_with_prefetch().await: Executes preflight on the host, potentially optimizing state loading (requires host feature).

See the CallBuilder documentation for more details on execution methods.

Examples

 const CONTRACT_ADDRESS: Address = address!("dAC17F958D2ee523a2206206994597C13D831ec7"); // USDT
 const ACCOUNT_TO_QUERY: Address = address!("F977814e90dA44bFA03b6295A0616a897441aceC"); // Binance
 sol! {
    interface IERC20 {
        function balanceOf(address account) external view returns (uint);
    }
}
const CALL: IERC20::balanceOfCall = IERC20::balanceOfCall { account: ACCOUNT_TO_QUERY };

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

// Preflight the call on the host
let mut contract_host = Contract::preflight(CONTRACT_ADDRESS, &mut host_env);
let mut builder = contract_host.call_builder(&CALL);
// Configure via builder.tx
builder.tx.caller = Address::default();
builder.tx.gas_limit = 10_000;
// Execute
let balance_result = builder.call().await?;
println!("Host preflight balance: {}", balance_result);

// Generate input for the guest
let evm_input = host_env.into_input().await?;

// === Guest Setup & Execution ===
// (Inside the RISC Zero guest)
let guest_env = evm_input.into_env(&ETH_MAINNET_CHAIN_SPEC);
let contract_guest = Contract::new(CONTRACT_ADDRESS, &guest_env);

// Execute the same call in the guest
let mut builder = contract_guest.call_builder(&CALL);
builder.tx.caller = Address::default();
builder.tx.gas_limit = 10_000;
let guest_balance_result = builder.call();
println!("Guest execution balance: {}", guest_balance_result);

Implementations

impl<'a, F, D, C> Contract<&'a mut EvmEnv<ProofDb<D>, F, HostCommit<C>>>

where F: EvmFactory,

pub fn preflight( address: Address, env: &'a mut EvmEnv<ProofDb<D>, F, HostCommit<C>>, ) -> Self

Available on crate feature host only.

Creates a Contract instance for use on the host for preflighting calls.

This prepares the environment for simulating the call, fetching necessary state via the Provider within env, and enabling proof generation via HostEvmEnv::into_input.

pub fn call_builder<S: SolCall>( &mut self, call: &S, ) -> CallBuilder<F::Tx, S, &mut EvmEnv<ProofDb<D>, F, HostCommit<C>>>

Available on crate feature host only.

Initializes a builder for preflighting a specific contract call (S) on the host.

impl<'a, F: EvmFactory> Contract<&'a EvmEnv<StateDb, F, Commitment>>

pub fn new(address: Address, env: &'a EvmEnv<StateDb, F, Commitment>) -> Self

Creates a Contract instance for use within the guest environment.

The env should typically be obtained via EvmInput::into_env.

pub fn call_builder<S: SolCall>( &self, call: &S, ) -> CallBuilder<F::Tx, S, &EvmEnv<StateDb, F, Commitment>>

Initializes a builder for executing a specific contract call (S) in the guest.