revm_inspector/
traits.rs

1use context::{ContextTr, FrameStack, JournalTr};
2use handler::{
3    evm::{ContextDbError, FrameInitResult, FrameTr},
4    instructions::InstructionProvider,
5    EthFrame, EvmTr, FrameInitOrResult, FrameResult, ItemOrResult,
6};
7use interpreter::{
8    interpreter::EthInterpreter, interpreter_action::FrameInit, CallOutcome, FrameInput,
9    InterpreterTypes,
10};
11
12use crate::{
13    handler::{frame_end, frame_start},
14    inspect_instructions, Inspector, JournalExt,
15};
16
17/// Inspector EVM trait. Extends the [`EvmTr`] trait with inspector related methods.
18///
19/// It contains execution of interpreter with [`crate::Inspector`] calls [`crate::Inspector::step`] and [`crate::Inspector::step_end`] calls.
20///
21/// It is used inside [`crate::InspectorHandler`] to extend evm with support for inspection.
22pub trait InspectorEvmTr:
23    EvmTr<
24    Frame: InspectorFrame<IT = EthInterpreter>,
25    Instructions: InstructionProvider<InterpreterTypes = EthInterpreter, Context = Self::Context>,
26    Context: ContextTr<Journal: JournalExt>,
27>
28{
29    /// The inspector type used for EVM execution inspection.
30    type Inspector: Inspector<Self::Context, EthInterpreter, FrameInput, FrameResult>;
31
32    /// Returns a tuple of mutable references to the context, the inspector, the frame and the instructions.
33    ///
34    /// This is one of two functions that need to be implemented for Evm. Second one is `all_mut`.
35    #[allow(clippy::type_complexity)]
36    fn all_inspector(
37        &self,
38    ) -> (
39        &Self::Context,
40        &Self::Instructions,
41        &Self::Precompiles,
42        &FrameStack<Self::Frame>,
43        &Self::Inspector,
44    );
45
46    /// Returns a tuple of mutable references to the context, the inspector, the frame and the instructions.
47    ///
48    /// This is one of two functions that need to be implemented for Evm. Second one is `all`.
49    #[allow(clippy::type_complexity)]
50    fn all_mut_inspector(
51        &mut self,
52    ) -> (
53        &mut Self::Context,
54        &mut Self::Instructions,
55        &mut Self::Precompiles,
56        &mut FrameStack<Self::Frame>,
57        &mut Self::Inspector,
58    );
59
60    /// Returns a mutable reference to the inspector.
61    fn inspector(&mut self) -> &mut Self::Inspector {
62        let (_, _, _, _, inspector) = self.all_mut_inspector();
63        inspector
64    }
65
66    /// Returns a tuple of mutable references to the context and the inspector.
67    ///
68    /// Useful when you want to allow inspector to modify the context.
69    fn ctx_inspector(&mut self) -> (&mut Self::Context, &mut Self::Inspector) {
70        let (ctx, _, _, _, inspector) = self.all_mut_inspector();
71        (ctx, inspector)
72    }
73
74    /// Returns a tuple of mutable references to the context, the inspector and the frame.
75    ///
76    /// Useful when you want to allow inspector to modify the context and the frame.
77    fn ctx_inspector_frame(
78        &mut self,
79    ) -> (&mut Self::Context, &mut Self::Inspector, &mut Self::Frame) {
80        let (ctx, _, _, frame, inspector) = self.all_mut_inspector();
81        (ctx, inspector, frame.get())
82    }
83
84    /// Returns a tuple of mutable references to the context, the inspector, the frame and the instructions.
85    fn ctx_inspector_frame_instructions(
86        &mut self,
87    ) -> (
88        &mut Self::Context,
89        &mut Self::Inspector,
90        &mut Self::Frame,
91        &mut Self::Instructions,
92    ) {
93        let (ctx, instructions, _, frame, inspector) = self.all_mut_inspector();
94        (ctx, inspector, frame.get(), instructions)
95    }
96
97    /// Initializes the frame for the given frame input. Frame is pushed to the frame stack.
98    #[inline]
99    fn inspect_frame_init(
100        &mut self,
101        mut frame_init: <Self::Frame as FrameTr>::FrameInit,
102    ) -> Result<FrameInitResult<'_, Self::Frame>, ContextDbError<Self::Context>> {
103        let (ctx, inspector) = self.ctx_inspector();
104        if let Some(mut output) = frame_start(ctx, inspector, &mut frame_init.frame_input) {
105            frame_end(ctx, inspector, &frame_init.frame_input, &mut output);
106            return Ok(ItemOrResult::Result(output));
107        }
108
109        let frame_input = frame_init.frame_input.clone();
110        let logs_i = ctx.journal().logs().len();
111        if let ItemOrResult::Result(mut output) = self.frame_init(frame_init)? {
112            let (ctx, inspector) = self.ctx_inspector();
113            // for precompiles send logs to inspector.
114            if let FrameResult::Call(CallOutcome {
115                was_precompile_called,
116                precompile_call_logs,
117                ..
118            }) = &mut output
119            {
120                if *was_precompile_called {
121                    let logs = ctx.journal_mut().logs()[logs_i..].to_vec();
122                    for log in logs.into_iter().chain(precompile_call_logs.iter().cloned()) {
123                        inspector.log(ctx, log);
124                    }
125                }
126            }
127            frame_end(ctx, inspector, &frame_input, &mut output);
128            return Ok(ItemOrResult::Result(output));
129        }
130
131        // if it is new frame, initialize the interpreter.
132        let (ctx, inspector, frame) = self.ctx_inspector_frame();
133        if let Some(frame) = frame.eth_frame() {
134            let interp = &mut frame.interpreter;
135            inspector.initialize_interp(interp, ctx);
136        };
137        Ok(ItemOrResult::Item(frame))
138    }
139
140    /// Run the frame from the top of the stack. Returns the frame init or result.
141    ///
142    /// If frame has returned result it would mark it as finished.
143    #[inline]
144    fn inspect_frame_run(
145        &mut self,
146    ) -> Result<FrameInitOrResult<Self::Frame>, ContextDbError<Self::Context>> {
147        let (ctx, inspector, frame, instructions) = self.ctx_inspector_frame_instructions();
148
149        let Some(frame) = frame.eth_frame() else {
150            return self.frame_run();
151        };
152
153        let next_action = inspect_instructions(
154            ctx,
155            &mut frame.interpreter,
156            inspector,
157            instructions.instruction_table(),
158        );
159        let mut result = frame.process_next_action(ctx, next_action);
160
161        if let Ok(ItemOrResult::Result(frame_result)) = &mut result {
162            let (ctx, inspector, frame) = self.ctx_inspector_frame();
163            // TODO When all_mut fn is added we can fetch inspector at the top of the function.s
164            if let Some(frame) = frame.eth_frame() {
165                frame_end(ctx, inspector, &frame.input, frame_result);
166                frame.set_finished(true);
167            }
168        };
169        result
170    }
171}
172
173/// Trait that extends the [`FrameTr`] trait with additional functionality that is needed for inspection.
174pub trait InspectorFrame: FrameTr<FrameResult = FrameResult, FrameInit = FrameInit> {
175    /// The interpreter types used by this frame.
176    type IT: InterpreterTypes;
177
178    /// Returns a mutable reference to the EthFrame.
179    ///
180    /// If this frame does not have support for tracing (does not contain
181    /// the EthFrame) Inspector calls for this frame will be skipped.
182    fn eth_frame(&mut self) -> Option<&mut EthFrame<EthInterpreter>>;
183}
184
185/// Impl InspectorFrame for EthFrame.
186impl InspectorFrame for EthFrame<EthInterpreter> {
187    type IT = EthInterpreter;
188
189    fn eth_frame(&mut self) -> Option<&mut EthFrame<EthInterpreter>> {
190        Some(self)
191    }
192}
revm_inspector/traits.rs

revm_inspector/
traits.rs
