API Reference eevm v#0.1.0

EEVM — Ethereum Virtual Machine implementation in Elixir.

Encodes and decodes Solidity ABI data: calldata for a function call, return data, and event logs, as the Solidity ABI specification defines them.

A full execution-layer block — header, transactions, ommers, and withdrawals — and the public path to build, encode, validate, and execute one.

Ethereum logs bloom filter — 256-byte (2048-bit) probabilistic filter summarising the addresses and indexed topics of every log in a receipt or block. Each item is added via 3 hash probes derived from Keccak-256 (Yellow Paper §4.3.1). The data field of a log is not included.

Ethereum block header — the consensus-critical metadata for a block, with its canonical RLP codec (encode/1, decode/1), its hash (compute_hash/1), and the EIP-1559 base fee a child must carry (calc_base_fee_per_gas/1). Validation lives in EEVM.Block.HeaderValidator.

Validates a child EEVM.Block.Header against its parent.

Lower-level block engine with an injectable transaction executor: system calls, then transactions in order, then beacon-chain withdrawals, then EIP-7685 requests, then the commitments a consensus-level verifier will check.

Per-transaction receipt emitted after execution (Byzantium-and-later layout).

EIP-7685 execution-layer requests: the typed messages a block passes to the consensus layer from Prague on, and the header's requests_hash that commits to them.

The outcome of executing a block — the post-state database plus every commitment derived from it. Returned by EEVM.Block.execute/4 and EEVM.Block.build/4, and by the lower-level EEVM.Block.Processor.process_block/4.

EIP-4895 beacon-chain withdrawal: a credit applied to an execution-layer account at the start of a block.

The block environment a transaction executes in: the fields the EVM's block opcodes read. EEVM.Handler.execute/4 takes one; EEVM.Block derives it from each header with from_header/2.

The outcome of a message call: EEVM.run/2, EEVM.call/4, or EEVM.create/3.

Runtime configuration for EEVM execution: the hardfork whose rules apply, the chain id, any custom precompiles, and the simulation switches.

Deprecated: renamed to EEVM.BlockEnv with snake_case fields. new/1 still accepts the old field names for one minor version.

Contract/message-level context — the current call frame's environment. Each CALL / DELEGATECALL / STATICCALL / CREATE frame has its own.

Deprecated: renamed to EEVM.TxEnv, with gasprice renamed to gas_price. new/1 still accepts the old field name for one minor version.

ECDSA over the short-Weierstrass curves y² = x³ + ax + b (mod p) that Ethereum uses, in pure Elixir

Keccak-256, the hash Ethereum calls keccak256, in pure Elixir.

RIPEMD-160 in pure Elixir, as specified by Dobbertin, Bosselaers and Preneel, "RIPEMD-160: A Strengthened Version of RIPEMD" (1996). Used by the 0x03 precompile.

SHA-256 (FIPS 180-4, §6.2) in pure Elixir.

World state: a read-only backend plus eevm's own write overlay.

In-memory EEVM.Database backend backed by plain maps. It implements every callback, commit/2 included, so EEVM.transact/4 and EEVM.Block.execute/4 return it with their changes applied.

Adapts a backend written against the pre-1.0 EEVM.Database callbacks (get_account/2, get_balance/2, set_balance/3, storage_store/4, ...) to the read-only behaviour. EEVM.Database.new/2 wraps such a module automatically; this shim is kept for one minor version.

Raised when a database backend returns {:error, reason} from a read and you called an EEVM.Database function directly; reason is that reason. The entry points return {:error, {:database, reason}} instead.

EIP-7702 delegation designators.

Reference for all error atoms used across the EEVM codebase.

Cold/warm storage access cost tracking per EIP-2929.

Blob gas pricing (EIP-4844) and its later adjustments.

Dynamic gas costs that depend on opcode operands at runtime.

Intrinsic gas costs for transactions — costs that apply before execution begins.

Memory expansion gas cost calculation.

Static gas costs for each EVM opcode.

End-to-end transaction handler.

Step 8 of the transaction pipeline — actually run the EVM.

Steps 9-11 of the transaction pipeline

Steps 4-7 of the transaction pipeline (Yellow Paper §6)

Pre-flight checks on a wire transaction.

Hardfork configuration controlling which EIP rules are active during execution.

The EVM interpreter — fetches, decodes, and dispatches opcodes in a loop.

Per-hardfork instruction tables, built at compile time, and the programs decoded from them.

EVM arithmetic opcodes: ADD, MUL, SUB, DIV, SDIV, MOD, SMOD, ADDMOD, MULMOD, EXP, SIGNEXTEND.

EVM bitwise opcodes: AND, OR, XOR, NOT, BYTE, SHL, SHR, SAR, CLZ.

EVM comparison opcodes: LT, GT, SLT, SGT, EQ, ISZERO.

EVM cryptographic opcode: KECCAK256 (0x20).

Data-copying environment opcodes that read from calldata, code, or return data.

External account inspection opcodes with EIP-2929 access cost tracking.

Simple environment opcodes that read a single value from the execution context.

Shared utilities for opcode implementations.

EVM logging opcodes — LOG0 through LOG4.

Opcode metadata registry — single source of truth for every opcode's name, stack I/O signature, implementing module, and static-context flag.

Memory access opcodes: MLOAD, MSTORE, MSTORE8, MSIZE, and MCOPY.

Stack manipulation opcodes: POP (0x50), DUP1–DUP16 (0x80–0x8F), and SWAP1–SWAP16 (0x90–0x9F).

Persistent and transient storage opcodes: SLOAD, SSTORE, TLOAD, and TSTORE.

Cross-contract call opcodes.

Contract creation opcodes.

Execution-terminating opcodes: STOP, RETURN, REVERT, INVALID, and SELFDESTRUCT.

Snapshot/commit semantics for nested EVM call frames.

The EVM machine state — the envelope that holds everything that survives a single opcode step.

Per-call read-only execution environment.

Per-call execution frame.

Transaction-scoped accumulators that survive nested call frames.

EVM memory — a byte-addressable, dynamically expanding linear memory.

The EVM stack — a LIFO data structure with a max depth of 1024.

Hex-prefix (aka compact) encoding used by Ethereum's Merkle Patricia Trie.

Ethereum Merkle Patricia Trie (Yellow Paper, Appendix D), as a persistent value that caches each node's hash.

Behaviour for EVM precompile implementations.

Dispatcher for EVM precompiled contracts.

BN256 (alt_bn128) curve precompiles — addresses 0x06, 0x07, 0x08 (EIP-196, EIP-197).

Arithmetic on the BN254 (alt_bn128) curve for the ecAdd, ecMul, and ecPairing precompiles (EIP-196, EIP-197): G1 point addition and scalar multiplication, G2 curve and subgroup checks, and the optimal ate pairing.

Blake2f precompile — address 0x09 (EIP-152).

BLS12-381 precompiles — addresses 0x0B through 0x11 (EIP-2537).

Arithmetic on the BLS12-381 curve, in pure Elixir, for the EIP-2537 precompiles (0x0B–0x11) and the EIP-4844 point-evaluation precompile (0x0A).

ECRecover precompile — address 0x01.

Identity precompile — address 0x04. Returns its input bytes unchanged.

KZG point evaluation precompile — address 0x0A (EIP-4844).

Modular exponentiation precompile — address 0x05 (EIP-198).

P256VERIFY precompile — address 0x100 (EIP-7951, Osaka onward).

RIPEMD-160 precompile — address 0x03.

SHA-256 precompile — address 0x02.

The state a transaction, block, or call wrote, as a backend's EEVM.Database.commit/2 receives it and results carry it in changes.

Computes Ethereum storage roots and state roots from the current EEVM.Database.

Genesis setup for the system contracts that blocks call from Cancun on.

EIP-4788 beacon block root contract (activated in Cancun).

EIP-2935 historical block hashes contract (activated in Prague).

Opt-in opcode-level execution tracer.

A single recorded step: one opcode execution in the trace. Every field except error describes the machine before the opcode runs.

Ethereum transaction wire-format structs.

EIP-2930 access list transaction (type 1): chain_id, nonce, gas_price, gas_limit, to, value, data, access_list, and the signature y_parity, r, s. EEVM.Transaction describes each field.

EIP-7702 authorization tuple: the account that signs it (its authority, see EEVM.Transaction.Signer.recover_authority/1) lets address's code run as its own.

EIP-4844 blob transaction (type 3): chain_id, nonce, max_priority_fee_per_gas, max_fee_per_gas, gas_limit, to, value, data, access_list, max_fee_per_blob_gas, blob_versioned_hashes, and the signature y_parity, r, s. EEVM.Transaction describes each field.

Transaction envelope encoding/decoding for legacy and typed transactions.

EIP-1559 fee market transaction (type 2): chain_id, nonce, max_priority_fee_per_gas, max_fee_per_gas, gas_limit, to, value, data, access_list, and the signature y_parity, r, s. EEVM.Transaction describes each field.

Intrinsic transaction gas calculation.

Legacy transaction (type 0): nonce, gas_price, gas_limit, to, value, data, and the signature v, r, s. EEVM.Transaction describes each field.

EIP-7702 set-code transaction (type 4): chain_id, nonce, max_priority_fee_per_gas, max_fee_per_gas, gas_limit, to, value, data, access_list, authorization_list, and the signature y_parity, r, s. EEVM.Transaction describes each field.

Transaction signing, signing hashes, and sender recovery.

Transaction pre-execution validation.

A rejected transaction with the values that broke the rule, returned as {:error, %EEVM.TransactionError{}} by EEVM.transact/4 when it is called with details: true. Without that option the same failure returns the bare reason atom, which stays the stable, matchable part.

The outcome of a transaction that passed validation, returned by EEVM.transact/4. A transaction that fails validation returns {:error, reason} instead, and the database is unchanged.

The transaction environment code executes in: the signed transaction as the EVM sees it. EEVM.transact/4 builds one from the wire transaction. Set it yourself to give bytecode run with EEVM.run/2 a transaction context, through its :tx option, or to simulate a transaction from any address: EEVM.transact/4 also takes an unsigned TxEnv and treats its origin as the sender, without a signature. Set gas_price for a legacy or EIP-2930 type, and the max_* fee fields for the others.