edb-engine 0.0.1

EDB's core analysis and instrumentation engine
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72

// EDB - Ethereum Debugger
// Copyright (C) 2024 Zhuo Zhang and Wuqi Zhang
//
// This program is free software: you can redistribute it and/or modify
// it under the terms of the GNU Affero General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// This program is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU Affero General Public License for more details.
//
// You should have received a copy of the GNU Affero General Public License
// along with this program. If not, see <https://www.gnu.org/licenses/>.

//! Common evaluation utilities and convenience functions.
//!
//! This module provides high-level convenience functions for expression evaluation
//! that are commonly used throughout the EDB system.

use std::sync::Arc;

use alloy_dyn_abi::DynSolValue;
use eyre::Result;
use revm::{database::CacheDB, Database, DatabaseCommit, DatabaseRef};

use crate::{EngineContext, ExpressionEvaluator};

/// Evaluate a Solidity expression string within the context of a specific debug snapshot.
///
/// This is a convenience function that creates an EDB-configured expression evaluator
/// and evaluates the given expression against the specified snapshot.
///
/// # Arguments
/// * `context` - The EDB engine context containing snapshots and trace data
/// * `expr` - The expression string to evaluate (e.g., "balances[msg.sender]")
/// * `snapshot_id` - The ID of the debug snapshot to evaluate against
///
/// # Returns
/// The result of the expression evaluation as a [`DynSolValue`]
///
/// # Errors
/// Returns an error if:
/// - The expression cannot be parsed
/// - The snapshot ID is invalid
/// - The expression evaluation fails (e.g., variable not found, function call fails)
///
/// # Examples
/// ```rust,ignore
/// // Evaluate a balance check
/// let result = eval_on_snapshot(context, "balances[msg.sender] > 1000", snapshot_id)?;
///
/// // Evaluate a function call
/// let supply = eval_on_snapshot(context, "totalSupply()", snapshot_id)?;
///
/// // Evaluate blockchain context
/// let is_recent = eval_on_snapshot(context, "block.timestamp - lastUpdate < 3600", snapshot_id)?;
/// ```
pub fn eval_on_snapshot<DB>(
    context: Arc<EngineContext<DB>>,
    expr: &str,
    snapshot_id: usize,
) -> Result<DynSolValue>
where
    DB: Database + DatabaseCommit + DatabaseRef + Clone + Send + Sync + 'static,
    <CacheDB<DB> as Database>::Error: Clone + Send + Sync,
    <DB as Database>::Error: Clone + Send + Sync,
{
    let evaluator = ExpressionEvaluator::new_edb(context);
    evaluator.eval(expr, snapshot_id)
}