# astraeuszhao/minievm architecture

> Architecture diagram of the GitHub repository astraeuszhao/minievm, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/astraeuszhao/minievm
- Repository: https://github.com/astraeuszhao/minievm

## Overview

MiniEVM is an embeddable Rust EVM bytecode execution engine. Its main workflow accepts a transaction, validates and checkpoints account state, executes target bytecode through a frame and opcode dispatcher, then returns an execution result or restores state on failure. The graph also preserves the documented gas, memory, environment, and tracing capabilities. The sampled source shows the transaction executor and module boundaries; dispatcher internals were not sampled, so their detailed opcode-level wiring is omitted.

Main entry points: [`src/vm/engine.rs`](https://github.com/astraeuszhao/minievm/blob/master/src/vm/engine.rs) (EVM Executor), [`src/vm/instructions.rs`](https://github.com/astraeuszhao/minievm/blob/master/src/vm/instructions.rs) (Opcode Dispatcher), [`src/state/world.rs`](https://github.com/astraeuszhao/minievm/blob/master/src/state/world.rs) (World State), [`src/vm/frame.rs`](https://github.com/astraeuszhao/minievm/blob/master/src/vm/frame.rs) (Execution Frame)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_execution["Execution"]
  node_evm["EVM Executor<br/>[engine.rs]"]
  node_bytecode["Analyzed Bytecode<br/>[bytecode.rs]"]
  node_dispatcher["Opcode Dispatcher<br/>[instructions.rs]"]
end

subgraph group_runtime["Runtime"]
  node_frame["Execution Frame<br/>[frame.rs]"]
  node_calldata["Call Data<br/>[calldata.rs]"]
  node_memory["Linear Memory<br/>[linear.rs]"]
  node_gas["Gas Meter<br/>[meter.rs]"]
  node_schedule["Opcode Pricing<br/>[schedule.rs]"]
  node_trace["Tracing Interface<br/>[tracer.rs]"]
  node_primitives["Address and Word<br/>[mod.rs]"]
end

subgraph group_state["Account State"]
  node_world[("World State<br/>[world.rs]")]
  node_account["Account<br/>[account.rs]"]
  node_log["Execution Logs<br/>[log.rs]"]
end

subgraph group_interfaces["Inputs and Results"]
  node_transaction["Transaction<br/>[transaction.rs]"]
  node_environment["Block Environment<br/>[environment.rs]"]
  node_result["Execution Result<br/>[receipt.rs]"]
  node_errors["VM Errors<br/>[mod.rs]"]
end

node_caller(("Embedding Caller"))
node_consumer(("Result Consumer"))

node_caller -->|"provides"| node_transaction
node_transaction -->|"submitted to"| node_evm
node_evm -->|"checks and updates"| node_world
node_evm -->|"analyzes code"| node_bytecode
node_evm -->|"creates frame"| node_frame
node_evm -->|"creates meter"| node_gas
node_evm -->|"prices opcodes"| node_schedule
node_evm -->|"dispatches opcode"| node_dispatcher
node_dispatcher -->|"executes against"| node_frame
node_dispatcher -->|"uses memory"| node_memory
node_dispatcher -->|"reads and writes"| node_world
node_dispatcher -->|"reads values"| node_environment
node_dispatcher -->|"charges gas"| node_gas
node_dispatcher -->|"emits events"| node_trace
node_world -->|"stores accounts"| node_account
node_world -->|"stores logs"| node_log
node_evm -->|"returns outcome"| node_result
node_evm -->|"handles failures"| node_errors
node_evm -->|"returns result"| node_consumer
node_primitives -->|"defines state values"| node_world
node_calldata -->|"supplies input"| node_frame

click node_transaction "https://github.com/astraeuszhao/minievm/blob/master/src/core/transaction.rs"
click node_evm "https://github.com/astraeuszhao/minievm/blob/master/src/vm/engine.rs"
click node_bytecode "https://github.com/astraeuszhao/minievm/blob/master/src/vm/bytecode.rs"
click node_dispatcher "https://github.com/astraeuszhao/minievm/blob/master/src/vm/instructions.rs"
click node_frame "https://github.com/astraeuszhao/minievm/blob/master/src/vm/frame.rs"
click node_calldata "https://github.com/astraeuszhao/minievm/blob/master/src/vm/calldata.rs"
click node_memory "https://github.com/astraeuszhao/minievm/blob/master/src/memory/linear.rs"
click node_gas "https://github.com/astraeuszhao/minievm/blob/master/src/gas/meter.rs"
click node_schedule "https://github.com/astraeuszhao/minievm/blob/master/src/gas/schedule.rs"
click node_environment "https://github.com/astraeuszhao/minievm/blob/master/src/core/environment.rs"
click node_world "https://github.com/astraeuszhao/minievm/blob/master/src/state/world.rs"
click node_account "https://github.com/astraeuszhao/minievm/blob/master/src/state/account.rs"
click node_log "https://github.com/astraeuszhao/minievm/blob/master/src/state/log.rs"
click node_trace "https://github.com/astraeuszhao/minievm/blob/master/src/trace/tracer.rs"
click node_result "https://github.com/astraeuszhao/minievm/blob/master/src/core/receipt.rs"
click node_primitives "https://github.com/astraeuszhao/minievm/blob/master/src/primitives/mod.rs"
click node_errors "https://github.com/astraeuszhao/minievm/blob/master/src/error/mod.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_evm,node_bytecode,node_dispatcher toneBlue
class node_frame,node_calldata,node_memory,node_gas,node_schedule,node_trace,node_primitives toneAmber
class node_world,node_account,node_log toneMint
class node_transaction,node_environment,node_result,node_errors toneRose
class node_caller,node_consumer toneIndigo
```

## Components

### Execution

- [EVM Executor](https://github.com/astraeuszhao/minievm/blob/master/src/vm/engine.rs): `src/vm/engine.rs`
- [Analyzed Bytecode](https://github.com/astraeuszhao/minievm/blob/master/src/vm/bytecode.rs): `src/vm/bytecode.rs`
- [Opcode Dispatcher](https://github.com/astraeuszhao/minievm/blob/master/src/vm/instructions.rs): `src/vm/instructions.rs`

### Runtime

- [Execution Frame](https://github.com/astraeuszhao/minievm/blob/master/src/vm/frame.rs): `src/vm/frame.rs`
- [Call Data](https://github.com/astraeuszhao/minievm/blob/master/src/vm/calldata.rs): `src/vm/calldata.rs`
- [Linear Memory](https://github.com/astraeuszhao/minievm/blob/master/src/memory/linear.rs): `src/memory/linear.rs`
- [Gas Meter](https://github.com/astraeuszhao/minievm/blob/master/src/gas/meter.rs): `src/gas/meter.rs`
- [Opcode Pricing](https://github.com/astraeuszhao/minievm/blob/master/src/gas/schedule.rs): `src/gas/schedule.rs`
- [Tracing Interface](https://github.com/astraeuszhao/minievm/blob/master/src/trace/tracer.rs): `src/trace/tracer.rs`
- [Address and Word](https://github.com/astraeuszhao/minievm/blob/master/src/primitives/mod.rs): `src/primitives/mod.rs`

### Account State

- [World State](https://github.com/astraeuszhao/minievm/blob/master/src/state/world.rs): `src/state/world.rs`
- [Account](https://github.com/astraeuszhao/minievm/blob/master/src/state/account.rs): `src/state/account.rs`
- [Execution Logs](https://github.com/astraeuszhao/minievm/blob/master/src/state/log.rs): `src/state/log.rs`

### Inputs and Results

- [Transaction](https://github.com/astraeuszhao/minievm/blob/master/src/core/transaction.rs): `src/core/transaction.rs`
- [Block Environment](https://github.com/astraeuszhao/minievm/blob/master/src/core/environment.rs): `src/core/environment.rs`
- [Execution Result](https://github.com/astraeuszhao/minievm/blob/master/src/core/receipt.rs): `src/core/receipt.rs`
- [VM Errors](https://github.com/astraeuszhao/minievm/blob/master/src/error/mod.rs): `src/error/mod.rs`

### Other components

- **Embedding Caller**
- **Result Consumer**

## Connections

- Embedding Caller → Transaction: provides
- Transaction → EVM Executor: submitted to
- EVM Executor → World State: checks and updates
- EVM Executor → Analyzed Bytecode: analyzes code
- EVM Executor → Execution Frame: creates frame
- EVM Executor → Gas Meter: creates meter
- EVM Executor → Opcode Pricing: prices opcodes
- EVM Executor → Opcode Dispatcher: dispatches opcode
- Opcode Dispatcher → Execution Frame: executes against
- Opcode Dispatcher → Linear Memory: uses memory
- Opcode Dispatcher → World State: reads and writes
- Opcode Dispatcher → Block Environment: reads values
- Opcode Dispatcher → Gas Meter: charges gas
- Opcode Dispatcher → Tracing Interface: emits events
- World State → Account: stores accounts
- World State → Execution Logs: stores logs
- EVM Executor → Execution Result: returns outcome
- EVM Executor → VM Errors: handles failures
- EVM Executor → Result Consumer: returns result
- Address and Word → World State: defines state values
- Call Data → Execution Frame: supplies input