# eevm v0.1.0 - Table of Contents

An Ethereum Virtual Machine in pure Elixir: bytecode, transactions, and blocks from Frontier to Osaka, with no native code.

## Pages

- [README](readme.md)
- [Changelog](changelog.md)
- [Benchmarks](benchmarks.md)
- [LICENSE](license.md)

## Modules

- Getting started
  - [EEVM](EEVM.md): EEVM — Ethereum Virtual Machine implementation in Elixir.
  - [EEVM.ABI](EEVM.ABI.md): Encodes and decodes Solidity ABI data: calldata for a function call,
return data, and event logs, as the
[Solidity ABI specification](https://docs.soliditylang.org/en/latest/abi-spec.html)
defines them.
  - [EEVM.BlockEnv](EEVM.BlockEnv.md): 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`.
  - [EEVM.CallResult](EEVM.CallResult.md): The outcome of a message call: `EEVM.run/2`, `EEVM.call/4`, or
`EEVM.create/3`.
  - [EEVM.Config](EEVM.Config.md): Runtime configuration for EEVM execution: the hardfork whose rules apply,
the chain id, any custom precompiles, and the simulation switches.
  - [EEVM.Error](EEVM.Error.md): Reference for all error atoms used across the EEVM codebase.
  - [EEVM.TxEnv](EEVM.TxEnv.md): 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.

- Transactions
  - [EEVM.Handler](EEVM.Handler.md): End-to-end transaction handler.
  - [EEVM.Transaction](EEVM.Transaction.md): Ethereum transaction wire-format structs.
  - [EEVM.Transaction.AccessList](EEVM.Transaction.AccessList.md): 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.

  - [EEVM.Transaction.Authorization](EEVM.Transaction.Authorization.md): 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.
  - [EEVM.Transaction.Blob](EEVM.Transaction.Blob.md): 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.

  - [EEVM.Transaction.Envelope](EEVM.Transaction.Envelope.md): Transaction envelope encoding/decoding for legacy and typed transactions.
  - [EEVM.Transaction.FeeMarket](EEVM.Transaction.FeeMarket.md): 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.

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

  - [EEVM.Transaction.SetCode](EEVM.Transaction.SetCode.md): 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.

  - [EEVM.Transaction.Signer](EEVM.Transaction.Signer.md): Transaction signing, signing hashes, and sender recovery.
  - [EEVM.TransactionError](EEVM.TransactionError.md): 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.
  - [EEVM.TransactionResult](EEVM.TransactionResult.md): 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.

- Blocks
  - [EEVM.Block](EEVM.Block.md): A full execution-layer block — header, transactions, ommers, and
withdrawals — and the public path to build, encode, validate, and execute
one.
  - [EEVM.Block.Header](EEVM.Block.Header.md): 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`.
  - [EEVM.Block.Receipt](EEVM.Block.Receipt.md): Per-transaction receipt emitted after execution (Byzantium-and-later layout).
  - [EEVM.Block.Result](EEVM.Block.Result.md): 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`.
  - [EEVM.Block.Withdrawal](EEVM.Block.Withdrawal.md): EIP-4895 beacon-chain withdrawal: a credit applied to an execution-layer
account at the start of a block.

- State
  - [EEVM.Database](EEVM.Database.md): World state: a read-only backend plus eevm's own write overlay.
  - [EEVM.Database.InMemory](EEVM.Database.InMemory.md): 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.
  - [EEVM.Database.ReadError](EEVM.Database.ReadError.md): 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.

  - [EEVM.StateChanges](EEVM.StateChanges.md): The state a transaction, block, or call wrote, as a backend's
`c:EEVM.Database.commit/2` receives it and results carry it in `changes`.
  - [EEVM.StateRoot](EEVM.StateRoot.md): Computes Ethereum storage roots and state roots from the current `EEVM.Database`.

- Extending
  - [EEVM.Block.Bloom](EEVM.Block.Bloom.md): 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.

  - [EEVM.Block.Processor](EEVM.Block.Processor.md): 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.
  - [EEVM.Block.Requests](EEVM.Block.Requests.md): 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.
  - [EEVM.Precompile](EEVM.Precompile.md): Behaviour for EVM precompile implementations.

  - [EEVM.SystemContracts](EEVM.SystemContracts.md): Genesis setup for the system contracts that blocks call from Cancun on.
  - [EEVM.SystemContracts.BeaconRoots](EEVM.SystemContracts.BeaconRoots.md): EIP-4788 beacon block root contract (activated in Cancun).
  - [EEVM.SystemContracts.BlockHashes](EEVM.SystemContracts.BlockHashes.md): EIP-2935 historical block hashes contract (activated in Prague).
  - [EEVM.Tracer](EEVM.Tracer.md): Opt-in opcode-level execution tracer.
  - [EEVM.Tracer.TraceStep](EEVM.Tracer.TraceStep.md): A single recorded step: one opcode execution in the trace. Every field
except `error` describes the machine *before* the opcode runs.

- Deprecated
  - [EEVM.Context.Block](EEVM.Context.Block.md): Deprecated: renamed to `EEVM.BlockEnv` with snake_case fields. `new/1`
still accepts the old field names for one minor version.

  - [EEVM.Context.Transaction](EEVM.Context.Transaction.md): Deprecated: renamed to `EEVM.TxEnv`, with `gasprice` renamed to
`gas_price`. `new/1` still accepts the old field name for one minor
version.

  - [EEVM.Database.Legacy](EEVM.Database.Legacy.md): 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.

- Internals
  - [EEVM.Block.HeaderValidator](EEVM.Block.HeaderValidator.md): Validates a child `EEVM.Block.Header` against its parent.
  - [EEVM.Context.Contract](EEVM.Context.Contract.md): Contract/message-level context — the current call frame's environment.
Each CALL / DELEGATECALL / STATICCALL / CREATE frame has its own.
  - [EEVM.Crypto.ECDSA](EEVM.Crypto.ECDSA.md): ECDSA over the short-Weierstrass curves `y² = x³ + ax + b (mod p)` that
Ethereum uses, in pure Elixir
  - [EEVM.Crypto.Keccak](EEVM.Crypto.Keccak.md): Keccak-256, the hash Ethereum calls `keccak256`, in pure Elixir.
  - [EEVM.Crypto.RIPEMD160](EEVM.Crypto.RIPEMD160.md): RIPEMD-160 in pure Elixir, as specified by Dobbertin, Bosselaers and
Preneel, ["RIPEMD-160: A Strengthened Version of RIPEMD"](https://homes.esat.kuleuven.be/~bosselae/ripemd160.html)
(1996). Used by the `0x03` precompile.
  - [EEVM.Crypto.SHA256](EEVM.Crypto.SHA256.md): SHA-256 ([FIPS 180-4](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.180-4.pdf), §6.2)
in pure Elixir.
  - [EEVM.Delegation](EEVM.Delegation.md): EIP-7702 delegation designators.
  - [EEVM.Gas.Access](EEVM.Gas.Access.md): Cold/warm storage access cost tracking per EIP-2929.
  - [EEVM.Gas.Blob](EEVM.Gas.Blob.md): Blob gas pricing (EIP-4844) and its later adjustments.
  - [EEVM.Gas.Dynamic](EEVM.Gas.Dynamic.md): Dynamic gas costs that depend on opcode operands at runtime.
  - [EEVM.Gas.Intrinsic](EEVM.Gas.Intrinsic.md): Intrinsic gas costs for transactions — costs that apply before execution begins.
  - [EEVM.Gas.Memory](EEVM.Gas.Memory.md): Memory expansion gas cost calculation.
  - [EEVM.Gas.Static](EEVM.Gas.Static.md): Static gas costs for each EVM opcode.
  - [EEVM.Handler.Execution](EEVM.Handler.Execution.md): Step 8 of the transaction pipeline — actually run the EVM.
  - [EEVM.Handler.PostExecution](EEVM.Handler.PostExecution.md): Steps 9-11 of the transaction pipeline
  - [EEVM.Handler.PreExecution](EEVM.Handler.PreExecution.md): Steps 4-7 of the transaction pipeline (Yellow Paper §6)
  - [EEVM.Handler.Validation](EEVM.Handler.Validation.md): Pre-flight checks on a wire transaction.
  - [EEVM.HardforkConfig](EEVM.HardforkConfig.md): Hardfork configuration controlling which EIP rules are active during execution.
  - [EEVM.Interpreter](EEVM.Interpreter.md): The EVM interpreter — fetches, decodes, and dispatches opcodes in a loop.
  - [EEVM.Interpreter.InstructionTable](EEVM.Interpreter.InstructionTable.md): Per-hardfork instruction tables, built at compile time, and the programs
decoded from them.
  - [EEVM.Interpreter.Instructions.Arithmetic](EEVM.Interpreter.Instructions.Arithmetic.md): EVM arithmetic opcodes: ADD, MUL, SUB, DIV, SDIV, MOD, SMOD, ADDMOD, MULMOD, EXP, SIGNEXTEND.
  - [EEVM.Interpreter.Instructions.Bitwise](EEVM.Interpreter.Instructions.Bitwise.md): EVM bitwise opcodes: AND, OR, XOR, NOT, BYTE, SHL, SHR, SAR, CLZ.
  - [EEVM.Interpreter.Instructions.Comparison](EEVM.Interpreter.Instructions.Comparison.md): EVM comparison opcodes: LT, GT, SLT, SGT, EQ, ISZERO.
  - [EEVM.Interpreter.Instructions.Crypto](EEVM.Interpreter.Instructions.Crypto.md): EVM cryptographic opcode: KECCAK256 (0x20).
  - [EEVM.Interpreter.Instructions.Environment.Data](EEVM.Interpreter.Instructions.Environment.Data.md): Data-copying environment opcodes that read from calldata, code, or return data.
  - [EEVM.Interpreter.Instructions.Environment.External](EEVM.Interpreter.Instructions.Environment.External.md): External account inspection opcodes with EIP-2929 access cost tracking.
  - [EEVM.Interpreter.Instructions.Environment.Simple](EEVM.Interpreter.Instructions.Environment.Simple.md): Simple environment opcodes that read a single value from the execution context.
  - [EEVM.Interpreter.Instructions.Helpers](EEVM.Interpreter.Instructions.Helpers.md): Shared utilities for opcode implementations.
  - [EEVM.Interpreter.Instructions.Logging](EEVM.Interpreter.Instructions.Logging.md): EVM logging opcodes — LOG0 through LOG4.
  - [EEVM.Interpreter.Instructions.Registry](EEVM.Interpreter.Instructions.Registry.md): Opcode metadata registry — single source of truth for every opcode's name,
stack I/O signature, implementing module, and static-context flag.
  - [EEVM.Interpreter.Instructions.StackMemoryStorage.MemoryOps](EEVM.Interpreter.Instructions.StackMemoryStorage.MemoryOps.md): Memory access opcodes: MLOAD, MSTORE, MSTORE8, MSIZE, and MCOPY.
  - [EEVM.Interpreter.Instructions.StackMemoryStorage.StackOps](EEVM.Interpreter.Instructions.StackMemoryStorage.StackOps.md): Stack manipulation opcodes: POP (0x50), DUP1–DUP16 (0x80–0x8F), and
SWAP1–SWAP16 (0x90–0x9F).

  - [EEVM.Interpreter.Instructions.StackMemoryStorage.StorageOps](EEVM.Interpreter.Instructions.StackMemoryStorage.StorageOps.md): Persistent and transient storage opcodes: SLOAD, SSTORE, TLOAD, and TSTORE.
  - [EEVM.Interpreter.Instructions.System.Calls](EEVM.Interpreter.Instructions.System.Calls.md): Cross-contract call opcodes.
  - [EEVM.Interpreter.Instructions.System.Creation](EEVM.Interpreter.Instructions.System.Creation.md): Contract creation opcodes.
  - [EEVM.Interpreter.Instructions.System.Termination](EEVM.Interpreter.Instructions.System.Termination.md): Execution-terminating opcodes: STOP, RETURN, REVERT, INVALID, and SELFDESTRUCT.
  - [EEVM.Interpreter.Journal](EEVM.Interpreter.Journal.md): Snapshot/commit semantics for nested EVM call frames.
  - [EEVM.Interpreter.MachineState](EEVM.Interpreter.MachineState.md): The EVM machine state — the envelope that holds everything that survives
a single opcode step.
  - [EEVM.Interpreter.MachineState.Env](EEVM.Interpreter.MachineState.Env.md): Per-call read-only execution environment.
  - [EEVM.Interpreter.MachineState.Frame](EEVM.Interpreter.MachineState.Frame.md): Per-call execution frame.
  - [EEVM.Interpreter.MachineState.Substate](EEVM.Interpreter.MachineState.Substate.md): Transaction-scoped accumulators that survive nested call frames.
  - [EEVM.Interpreter.Memory](EEVM.Interpreter.Memory.md): EVM memory — a byte-addressable, dynamically expanding linear memory.
  - [EEVM.Interpreter.Stack](EEVM.Interpreter.Stack.md): The EVM stack — a LIFO data structure with a max depth of 1024.
  - [EEVM.MPT.HexPrefix](EEVM.MPT.HexPrefix.md): Hex-prefix (aka compact) encoding used by Ethereum's Merkle Patricia Trie.
  - [EEVM.MPT.Trie](EEVM.MPT.Trie.md): Ethereum Merkle Patricia Trie (Yellow Paper, Appendix D), as a persistent
value that caches each node's hash.
  - [EEVM.Precompiles](EEVM.Precompiles.md): Dispatcher for EVM precompiled contracts.
  - [EEVM.Precompiles.BN256](EEVM.Precompiles.BN256.md): BN256 (alt_bn128) curve precompiles — addresses `0x06`, `0x07`, `0x08`
(EIP-196, EIP-197).
  - [EEVM.Precompiles.BN256.Curve](EEVM.Precompiles.BN256.Curve.md): 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.
  - [EEVM.Precompiles.Blake2F](EEVM.Precompiles.Blake2F.md): Blake2f precompile — address `0x09` (EIP-152).
  - [EEVM.Precompiles.Bls12381](EEVM.Precompiles.Bls12381.md): BLS12-381 precompiles — addresses `0x0B` through `0x11` (EIP-2537).
  - [EEVM.Precompiles.Bls12381.Curve](EEVM.Precompiles.Bls12381.Curve.md): Arithmetic on the BLS12-381 curve, in pure Elixir, for the EIP-2537
precompiles (`0x0B`–`0x11`) and the EIP-4844 point-evaluation precompile
(`0x0A`).
  - [EEVM.Precompiles.ECRecover](EEVM.Precompiles.ECRecover.md): ECRecover precompile — address `0x01`.
  - [EEVM.Precompiles.Identity](EEVM.Precompiles.Identity.md): Identity precompile — address `0x04`. Returns its input bytes unchanged.
  - [EEVM.Precompiles.KZGPointEval](EEVM.Precompiles.KZGPointEval.md): KZG point evaluation precompile — address `0x0A` (EIP-4844).
  - [EEVM.Precompiles.ModExp](EEVM.Precompiles.ModExp.md): Modular exponentiation precompile — address `0x05` (EIP-198).
  - [EEVM.Precompiles.P256Verify](EEVM.Precompiles.P256Verify.md): P256VERIFY precompile — address `0x100` (EIP-7951, Osaka onward).
  - [EEVM.Precompiles.RIPEMD160](EEVM.Precompiles.RIPEMD160.md): RIPEMD-160 precompile — address `0x03`.
  - [EEVM.Precompiles.SHA256](EEVM.Precompiles.SHA256.md): SHA-256 precompile — address `0x02`.
  - [EEVM.Transaction.IntrinsicGas](EEVM.Transaction.IntrinsicGas.md): Intrinsic transaction gas calculation.
  - [EEVM.Transaction.Validator](EEVM.Transaction.Validator.md): Transaction pre-execution validation.