edb_engine/
lib.rs

1// EDB - Ethereum Debugger
2// Copyright (C) 2024 Zhuo Zhang and Wuqi Zhang
3//
4// This program is free software: you can redistribute it and/or modify
5// it under the terms of the GNU Affero General Public License as published by
6// the Free Software Foundation, either version 3 of the License, or
7// (at your option) any later version.
8//
9// This program is distributed in the hope that it will be useful,
10// but WITHOUT ANY WARRANTY; without even the implied warranty of
11// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12// GNU Affero General Public License for more details.
13//
14// You should have received a copy of the GNU Affero General Public License
15// along with this program. If not, see <https://www.gnu.org/licenses/>.
16
17// Copyright (C) 2024 Zhuo Zhang and Wuqi Zhang
18// SPDX-License-Identifier: AGPL-3.0
19
20//! EDB Engine - Advanced Ethereum smart contract debugging and analysis engine.
21//!
22//! This crate provides the core debugging engine for EDB (Ethereum Debugger), enabling
23//! detailed analysis and debugging of smart contract execution at both opcode and source levels.
24//! The engine supports real-time expression evaluation, comprehensive snapshot management,
25//! and advanced debugging features for Ethereum smart contracts.
26//!
27//! # Key Features
28//!
29//! ## 🔍 **Multi-Level Debugging**
30//! - **Opcode-level debugging**: Step through EVM bytecode execution
31//! - **Source-level debugging**: Debug using original Solidity source code
32//! - **Hybrid debugging**: Switch seamlessly between opcode and source views
33//!
34//! ## 📸 **Snapshot System**
35//! - Capture execution state at any point during contract execution
36//! - Navigate forward/backward through execution history
37//! - Support for both hook-based and opcode-based snapshots
38//!
39//! ## ⚡ **Real-time Expression Evaluation**
40//! - Evaluate Solidity-like expressions against any execution snapshot
41//! - Access variables, function calls, storage, and blockchain context
42//! - Support for complex expressions with type casting and operations
43//!
44//! ## 🔗 **JSON-RPC API**
45//! - Complete debugging API for frontend integration
46//! - WebSocket and HTTP support for real-time debugging
47//! - Comprehensive error handling and protocol compliance
48//!
49//! ## 🛠 **Advanced Analysis**
50//! - Contract instrumentation for debugging hooks
51//! - Source code analysis and mapping
52//! - ABI resolution and type inference
53//! - Storage layout analysis
54//!
55//! # Core Modules
56//!
57//! - [`analysis`] - Source code analysis and contract instrumentation
58//! - [`core`] - Core engine types and execution management
59//! - [`context`] - Engine context and state management
60//! - [`eval`] - Expression evaluation system
61//! - [`inspector`] - EVM execution inspectors for data collection
62//! - [`instrumentation`] - Contract instrumentation and code generation
63//! - [`rpc`] - JSON-RPC debugging API
64//! - [`snapshot`] - Snapshot management and analysis
65//! - [`tweak`] - Runtime contract modification for debugging
66//! - [`utils`] - Utility functions and helpers
67//!
68//! # Quick Start
69//!
70//! ```rust,ignore
71//! use edb_engine::{EngineContext, DebugRpcServer};
72//! use revm::primitives::Address;
73//!
74//! // Create engine context with debugging data
75//! let context = EngineContext::new(db, snapshots, trace, artifacts);
76//!
77//! // Start RPC server for debugging API
78//! let server = DebugRpcServer::new(context);
79//! let handle = server.start().await?;
80//!
81//! println!("Debug server running on port {}", handle.port());
82//! ```
83//!
84//! # Architecture
85//!
86//! The EDB engine follows a modular architecture:
87//!
88//! 1. **Data Collection**: Inspectors collect execution data during EVM execution
89//! 2. **Snapshot Management**: Captured data is organized into navigable snapshots
90//! 3. **Expression Evaluation**: Real-time evaluation against snapshot data
91//! 4. **API Layer**: JSON-RPC interface exposes all debugging functionality
92//! 5. **Analysis**: Deep contract analysis for enhanced debugging experience
93
94/// Source code analysis and contract instrumentation (internal module).
95pub mod analysis;
96use analysis::*;
97
98pub mod core;
99pub use core::*;
100
101pub mod context;
102pub use context::*;
103
104pub mod eval;
105pub use eval::*;
106
107pub mod inspector;
108pub use inspector::*;
109
110/// Contract instrumentation and code generation (internal module).
111pub mod instrumentation;
112pub use instrumentation::*;
113
114pub mod rpc;
115pub use rpc::*;
116
117pub mod snapshot;
118pub use snapshot::*;
119
120pub mod tweak;
121pub use tweak::*;
122
123pub mod utils;
124pub use utils::*;
edb_engine/lib.rs

edb_engine/
lib.rs
