eth_utils

Ethereum utilities for fetching block data, tracing execution, and generating execution witnesses.

This crate provides both a Rust library and an eth-cli binary. It is designed to work with an Ethereum JSON-RPC endpoint and uses revm for local transaction execution/tracing.

Features

• Fetch Ethereum block data from JSON-RPC.
• Collect state for accounts touched by block transactions.
• Trace block execution with revm.
• Generate execution witness data for a block.
• Export CLI output as text, json, or csv.
• Save generated witnesses as hex-encoded serialized JSON for downstream VM input.

Project Layout

src/
bin/eth_cli.rs CLI entry point
cli/ CLI parser and command implementations
fetcher.rs Ethereum JSON-RPC fetching
tracer.rs Block tracing and witness generation
types.rs Shared block, trace, and verification types
utils.rs Ethereum helper functions and constants

Prerequisites

• Rust and Cargo.
• Access to an Ethereum JSON-RPC endpoint.
• The expected workspace layout for the local dependency riscv = { path = ".." }.

The CLI requires an RPC URL for network operations.

Build

Build the crate:

cargo build

Build only the CLI binary:

cargo build --bin eth-cli

CLI Usage

General form:

cargo run --bin eth-cli -- --rpc-url <RPC_URL><COMMAND>

Increase logging verbosity with -v, -vv, or -vvv:

cargo run --bin eth-cli -- --rpc-url <RPC_URL> -v fetch 19000000

Fetch Block Data

Fetch a human-readable block summary:

cargo run --bin eth-cli -- --rpc-url https://your-rpc.example fetch 19000000

Fetch JSON output:

cargo run --bin eth-cli -- --rpc-url https://your-rpc.example fetch 19000000 --format json

Write CSV output to a file:

cargo run --bin eth-cli -- --rpc-url https://your-rpc.example fetch 19000000 --format csv --output block.csv

The fetch command reports:

• Block number.
• Block hash.
• State root.
• Transaction count.
• Timestamp.
• Miner.
• Gas used.
• Gas limit.

Generate Execution Witness

Generate a text summary for a block witness:

cargo run --bin eth-cli -- --rpc-url https://your-rpc.example generate-witness 19000000

Print the witness as JSON:

cargo run --bin eth-cli -- --rpc-url https://your-rpc.example generate-witness 19000000 --format json

Save the witness to a file:

cargo run --bin eth-cli -- --rpc-url https://your-rpc.example generate-witness 19000000 --format json --output witness.hex

When --output is used with generate-witness, the file contains hex-encoded serialized witness JSON.

Library Usage

The crate exports the main fetcher, tracer, trace type, and helper utilities:

use eth_utils::{BlockTracer,EthFetcher};#[tokio::main]asyncfnmain() -> anyhow::Result<()>{let fetcher = EthFetcher::new("https://your-rpc.example")?;let block_data = fetcher.fetch_block_data(19_000_000).await?;let trace = BlockTracer::trace_block(&block_data)?;let witness = BlockTracer::generate_witness(&block_data,&trace)?;println!("{}", serde_json::to_string_pretty(&witness)?);Ok(())}

Public exports include:

• EthFetcher
• BlockTracer
• BlockTrace
• get_chain_config
• parse_hex_u64
• parse_hex_u256
• EMPTY_CODE_HASH

Output Formats

Both CLI commands accept:

• --format text
• --format json
• --format csv

The default format is text.

For fetch, --output writes the selected formatted output directly to disk.

For generate-witness, --output writes the generated witness as hex-encoded serialized JSON, regardless of the display format printed to stdout.

Current Limitations

• --rpc-url is required for CLI commands.
• The BLOCK argument currently accepts decimal block numbers. Block hashes are not parsed by the shared command implementation yet.
• Account storage is initialized as empty when fetching touched accounts.
• Tracing accuracy depends on the fetched account data and the current revm execution setup.

Development

Run tests:

cargo test

Format the code:

cargo fmt

Run Clippy:

cargo clippy