ethrex_levm/lib.rs
1//! # LEVM - Lambda EVM
2//!
3//! A pure Rust implementation of the Ethereum Virtual Machine.
4//!
5//! ## Overview
6//!
7//! LEVM (Lambda EVM) is ethrex's native EVM implementation, designed for:
8//! - **Correctness**: Full compatibility with Ethereum consensus tests
9//! - **Performance**: Optimized opcode execution and memory management
10//! - **Readability**: Clean, well-documented Rust code
11//! - **Extensibility**: Modular design for easy feature additions
12//!
13//! ## Architecture
14//!
15//! ```text
16//! ┌─────────────────────────────────────────────────────────────┐
17//! │ VM │
18//! │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │
19//! │ │ CallFrame │ │ Memory │ │ Stack │ │
20//! │ └─────────────┘ └─────────────┘ └─────────────────────┘ │
21//! │ │
22//! │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │
23//! │ │ Substate │ │ Precompiles │ │ Environment │ │
24//! │ └─────────────┘ └─────────────┘ └─────────────────────┘ │
25//! └─────────────────────────────────────────────────────────────┘
26//! │
27//! ▼
28//! ┌─────────────────────────────────────────────────────────────┐
29//! │ GeneralizedDatabase │
30//! │ (Account state, storage, code) │
31//! └─────────────────────────────────────────────────────────────┘
32//! ```
33//!
34//! ## Key Components
35//!
36//! - [`vm::VM`]: Main EVM execution engine
37//! - [`call_frame::CallFrame`]: Execution context for each call
38//! - [`memory::Memory`]: EVM memory with expansion tracking
39//! - [`environment::Environment`]: Block and transaction context
40//! - [`precompiles`]: Native implementations of precompiled contracts
41//! - [`hooks`]: Execution hooks for pre/post-execution logic and L2-specific behavior
42//!
43//! ## Supported Forks
44//!
45//! LEVM supports post-merge Ethereum forks:
46//! - Paris (The Merge), Shanghai, Cancun, Prague, Osaka
47//!
48//! Note: ethrex is a post-merge client and does not support pre-merge forks.
49//!
50//! ## Usage
51//!
52//! ```ignore
53//! use levm::{VM, Environment};
54//!
55//! // Create VM with database and environment
56//! let mut vm = VM::new(env, db, &tx, tracer, vm_type, &NativeCrypto);
57//!
58//! // Execute the transaction
59//! let report = vm.execute()?;
60//!
61//! // Check execution result
62//! if report.is_success() {
63//! println!("Gas used: {}", report.gas_used);
64//! }
65//! ```
66
67pub mod call_frame;
68pub mod constants;
69pub mod db;
70pub mod debug;
71pub mod environment;
72pub mod errors;
73pub mod execution_handlers;
74pub mod gas_cost;
75pub mod hooks;
76pub mod memory;
77pub mod opcode_handlers;
78pub mod opcode_tracer;
79pub mod opcodes;
80pub mod precompiles;
81pub mod tracing;
82pub mod utils;
83pub mod vm;
84pub use environment::*;
85pub mod account;
86#[cfg(feature = "perf_opcode_timings")]
87pub mod timings;