> ## Documentation Index
> Fetch the complete documentation index at: https://docs.herodotus.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Provable EVM Contract Calls

> Using execute_eth_call to call EVM contracts at historical blocks inside HDP

`execute_eth_call` is one of HDP's most powerful features: you can run an EVM contract call inside a ZK execution context and prove the result.

In practice, this gives you a clean way to reason about **time**:

* "What was this wallet's USDC balance at block X?"
* "What was voting power exactly when voting started?"
* "Was an address eligible at snapshot block Y?"

## Why this dramatically simplifies development

With `execute_eth_call`, you can often avoid manual slot math and low-level proof wiring:

* Reuse contract ABIs and familiar call patterns.
* Keep most application logic in Solidity/backends.
* Add a focused Cairo1 proof module only for the verifiable part.
* Get historical, provable answers without deep storage-proof expertise.

Under the hood, HDP wraps the call in an EIP-1559-style transaction context and executes it inside a Cairo EVM interpreter while reading state through HDP memorizers.

## Function signature

```rust theme={null}
pub fn execute_eth_call(
    hdp: @HDP,
    time_and_space: @TimeAndSpace,
    sender: EthAddress,
    target: EthAddress,
    calldata: Span<u8>,
) -> TransactionResult
```

`TimeAndSpace` pins the call to a specific chain and block:

```rust theme={null}
TimeAndSpace { chain_id: 1, block_number: 21370000 }
```

## Return value

`TransactionResult` includes:

* `success: bool`
* `return_data: Span<u8>`
* `gas_used: u64`
* `state: State`

You decode `return_data` in your Cairo module according to the ABI.

## Real example: historical `balanceOf`

The official example calls USDC `balanceOf(address)` for Vitalik at a fixed Ethereum mainnet block and converts return bytes into `u256`:

* Example module: [examples/eth\_call/src/lib.cairo](https://github.com/HerodotusDev/hdp-cairo/blob/main/examples/eth_call/src/lib.cairo)
* Example run script: [examples/eth\_call/run.sh](https://github.com/HerodotusDev/hdp-cairo/blob/main/examples/eth_call/run.sh)

## Typical use cases

* Historical balance snapshots for governance, rewards, and accounting
* Time-bounded eligibility checks (airdrop, campaign, compliance windows)
* Proof-backed state derivations without manual storage-slot plumbing
* Solidity-heavy products that need minimal Cairo1 surface area

## Current behavior to be aware of

As currently implemented, `execute_eth_call` constructs an EIP-1559 call with fixed internals (for example `nonce = 0`, `value = 0`, configured gas fields, empty access list). For most read-style calls this is exactly what you want, but advanced flows should still review implementation details in source.

`execute_eth_call` is designed for `eth_call`-style execution (read-oriented behavior, no state mutation as part of settled chain state), and opcode support is intentionally scoped.

## Run and prove

One practical flow is:

1. Build and run HDP pipeline (`dry-run` -> `fetch-proofs` -> `sound-run`)
2. Export Cairo PIE
3. Send proving/verification workload to [Atlantic](/atlantic-api/introduction)

See:

* [Ways to run HDP](/data-processor/running-hdp)
* [Atlantic Introduction](/atlantic-api/introduction)