revm_interpreter/
interpreter.rs

1//! Core interpreter implementation and components.
2
3/// Extended bytecode functionality.
4pub mod ext_bytecode;
5mod input;
6mod loop_control;
7mod return_data;
8mod runtime_flags;
9mod shared_memory;
10mod stack;
11
12// re-exports
13pub use ext_bytecode::ExtBytecode;
14pub use input::InputsImpl;
15pub use return_data::ReturnDataImpl;
16pub use runtime_flags::RuntimeFlags;
17pub use shared_memory::{num_words, SharedMemory};
18pub use stack::{Stack, STACK_LIMIT};
19
20// imports
21use crate::{
22    host::DummyHost, instruction_context::InstructionContext, interpreter_types::*, Gas, Host,
23    InstructionResult, InstructionTable, InterpreterAction,
24};
25use bytecode::Bytecode;
26use primitives::{hardfork::SpecId, Bytes};
27
28/// Main interpreter structure that contains all components defined in [`InterpreterTypes`].
29#[derive(Debug, Clone)]
30#[cfg_attr(feature = "serde", derive(::serde::Serialize, ::serde::Deserialize))]
31pub struct Interpreter<WIRE: InterpreterTypes = EthInterpreter> {
32    /// Bytecode being executed.
33    pub bytecode: WIRE::Bytecode,
34    /// Gas tracking for execution costs.
35    pub gas: Gas,
36    /// EVM stack for computation.
37    pub stack: WIRE::Stack,
38    /// Buffer for return data from calls.
39    pub return_data: WIRE::ReturnData,
40    /// EVM memory for data storage.
41    pub memory: WIRE::Memory,
42    /// Input data for current execution context.
43    pub input: WIRE::Input,
44    /// Runtime flags controlling execution behavior.
45    pub runtime_flag: WIRE::RuntimeFlag,
46    /// Extended functionality and customizations.
47    pub extend: WIRE::Extend,
48}
49
50impl<EXT: Default> Interpreter<EthInterpreter<EXT>> {
51    /// Create new interpreter
52    pub fn new(
53        memory: SharedMemory,
54        bytecode: ExtBytecode,
55        input: InputsImpl,
56        is_static: bool,
57        spec_id: SpecId,
58        gas_limit: u64,
59    ) -> Self {
60        Self::new_inner(
61            Stack::new(),
62            memory,
63            bytecode,
64            input,
65            is_static,
66            spec_id,
67            gas_limit,
68        )
69    }
70
71    /// Create a new interpreter with default extended functionality.
72    pub fn default_ext() -> Self {
73        Self::do_default(Stack::new(), SharedMemory::new())
74    }
75
76    /// Create a new invalid interpreter.
77    pub fn invalid() -> Self {
78        Self::do_default(Stack::invalid(), SharedMemory::invalid())
79    }
80
81    fn do_default(stack: Stack, memory: SharedMemory) -> Self {
82        Self::new_inner(
83            stack,
84            memory,
85            ExtBytecode::default(),
86            InputsImpl::default(),
87            false,
88            SpecId::default(),
89            u64::MAX,
90        )
91    }
92
93    #[allow(clippy::too_many_arguments)]
94    fn new_inner(
95        stack: Stack,
96        memory: SharedMemory,
97        bytecode: ExtBytecode,
98        input: InputsImpl,
99        is_static: bool,
100        spec_id: SpecId,
101        gas_limit: u64,
102    ) -> Self {
103        Self {
104            bytecode,
105            gas: Gas::new(gas_limit),
106            stack,
107            return_data: Default::default(),
108            memory,
109            input,
110            runtime_flag: RuntimeFlags { is_static, spec_id },
111            extend: Default::default(),
112        }
113    }
114
115    /// Clears and reinitializes the interpreter with new parameters.
116    #[allow(clippy::too_many_arguments)]
117    pub fn clear(
118        &mut self,
119        memory: SharedMemory,
120        bytecode: ExtBytecode,
121        input: InputsImpl,
122        is_static: bool,
123        spec_id: SpecId,
124        gas_limit: u64,
125    ) {
126        let Self {
127            bytecode: bytecode_ref,
128            gas,
129            stack,
130            return_data,
131            memory: memory_ref,
132            input: input_ref,
133            runtime_flag,
134            extend,
135        } = self;
136        *bytecode_ref = bytecode;
137        *gas = Gas::new(gas_limit);
138        if stack.data().capacity() == 0 {
139            *stack = Stack::new();
140        } else {
141            stack.clear();
142        }
143        return_data.0.clear();
144        *memory_ref = memory;
145        *input_ref = input;
146        *runtime_flag = RuntimeFlags { spec_id, is_static };
147        *extend = EXT::default();
148    }
149
150    /// Sets the bytecode that is going to be executed
151    pub fn with_bytecode(mut self, bytecode: Bytecode) -> Self {
152        self.bytecode = ExtBytecode::new(bytecode);
153        self
154    }
155
156    /// Sets the specid for the interpreter.
157    pub fn set_spec_id(&mut self, spec_id: SpecId) {
158        self.runtime_flag.spec_id = spec_id;
159    }
160}
161
162impl Default for Interpreter<EthInterpreter> {
163    fn default() -> Self {
164        Self::default_ext()
165    }
166}
167
168/// Default types for Ethereum interpreter.
169#[derive(Debug)]
170pub struct EthInterpreter<EXT = (), MG = SharedMemory> {
171    _phantom: core::marker::PhantomData<fn() -> (EXT, MG)>,
172}
173
174impl<EXT> InterpreterTypes for EthInterpreter<EXT> {
175    type Stack = Stack;
176    type Memory = SharedMemory;
177    type Bytecode = ExtBytecode;
178    type ReturnData = ReturnDataImpl;
179    type Input = InputsImpl;
180    type RuntimeFlag = RuntimeFlags;
181    type Extend = EXT;
182    type Output = InterpreterAction;
183}
184
185impl<IW: InterpreterTypes> Interpreter<IW> {
186    /// Takes the next action from the control and returns it.
187    #[inline]
188    pub fn take_next_action(&mut self) -> InterpreterAction {
189        // Return next action if it is some.
190        core::mem::take(self.bytecode.action()).expect("Interpreter to set action")
191    }
192
193    /// Halt the interpreter with the given result.
194    ///
195    /// This will set the action to [`InterpreterAction::Return`] and set the gas to the current gas.
196    pub fn halt(&mut self, result: InstructionResult) {
197        self.bytecode
198            .set_action(InterpreterAction::new_halt(result, self.gas));
199    }
200
201    /// Return with the given output.
202    ///
203    /// This will set the action to [`InterpreterAction::Return`] and set the gas to the current gas.
204    pub fn return_with_output(&mut self, output: Bytes) {
205        self.bytecode.set_action(InterpreterAction::new_return(
206            InstructionResult::Return,
207            output,
208            self.gas,
209        ));
210    }
211
212    /// Executes the instruction at the current instruction pointer.
213    ///
214    /// Internally it will increment instruction pointer by one.
215    #[inline]
216    pub fn step<H: ?Sized>(&mut self, instruction_table: &InstructionTable<IW, H>, host: &mut H) {
217        let context = InstructionContext {
218            interpreter: self,
219            host,
220        };
221        context.step(instruction_table);
222    }
223
224    /// Executes the instruction at the current instruction pointer.
225    ///
226    /// Internally it will increment instruction pointer by one.
227    ///
228    /// This uses dummy Host.
229    #[inline]
230    pub fn step_dummy(&mut self, instruction_table: &InstructionTable<IW, DummyHost>) {
231        let context = InstructionContext {
232            interpreter: self,
233            host: &mut DummyHost,
234        };
235        context.step(instruction_table);
236    }
237
238    /// Executes the interpreter until it returns or stops.
239    #[inline]
240    pub fn run_plain<H: ?Sized>(
241        &mut self,
242        instruction_table: &InstructionTable<IW, H>,
243        host: &mut H,
244    ) -> InterpreterAction {
245        while self.bytecode.is_not_end() {
246            // Get current opcode.
247            let opcode = self.bytecode.opcode();
248
249            // SAFETY: In analysis we are doing padding of bytecode so that we are sure that last
250            // byte instruction is STOP so we are safe to just increment program_counter bcs on last instruction
251            // it will do noop and just stop execution of this contract
252            self.bytecode.relative_jump(1);
253            let context = InstructionContext {
254                interpreter: self,
255                host,
256            };
257            // Execute instruction.
258            instruction_table[opcode as usize](context);
259        }
260        self.bytecode.revert_to_previous_pointer();
261
262        self.take_next_action()
263    }
264}
265
266/// The result of an interpreter operation.
267#[derive(Clone, Debug, PartialEq, Eq)]
268#[cfg_attr(feature = "serde", derive(::serde::Serialize, ::serde::Deserialize))]
269pub struct InterpreterResult {
270    /// The result of the instruction execution.
271    pub result: InstructionResult,
272    /// The output of the instruction execution.
273    pub output: Bytes,
274    /// The gas usage information.
275    pub gas: Gas,
276}
277
278impl InterpreterResult {
279    /// Returns a new `InterpreterResult` with the given values.
280    pub fn new(result: InstructionResult, output: Bytes, gas: Gas) -> Self {
281        Self {
282            result,
283            output,
284            gas,
285        }
286    }
287
288    /// Returns whether the instruction result is a success.
289    #[inline]
290    pub const fn is_ok(&self) -> bool {
291        self.result.is_ok()
292    }
293
294    /// Returns whether the instruction result is a revert.
295    #[inline]
296    pub const fn is_revert(&self) -> bool {
297        self.result.is_revert()
298    }
299
300    /// Returns whether the instruction result is an error.
301    #[inline]
302    pub const fn is_error(&self) -> bool {
303        self.result.is_error()
304    }
305}
306
307// Special implementation for types where Output can be created from InterpreterAction
308impl<IW: InterpreterTypes> Interpreter<IW>
309where
310    IW::Output: From<InterpreterAction>,
311{
312    /// Takes the next action from the control and returns it as the specific Output type.
313    #[inline]
314    pub fn take_next_action_as_output(&mut self) -> IW::Output {
315        From::from(self.take_next_action())
316    }
317
318    /// Executes the interpreter until it returns or stops, returning the specific Output type.
319    #[inline]
320    pub fn run_plain_as_output<H: Host + ?Sized>(
321        &mut self,
322        instruction_table: &InstructionTable<IW, H>,
323        host: &mut H,
324    ) -> IW::Output {
325        From::from(self.run_plain(instruction_table, host))
326    }
327}
328
329#[cfg(test)]
330mod tests {
331    #[test]
332    #[cfg(feature = "serde")]
333    fn test_interpreter_serde() {
334        use super::*;
335        use bytecode::Bytecode;
336        use primitives::Bytes;
337
338        let bytecode = Bytecode::new_raw(Bytes::from(&[0x60, 0x00, 0x60, 0x00, 0x01][..]));
339        let interpreter = Interpreter::<EthInterpreter>::new(
340            SharedMemory::new(),
341            ExtBytecode::new(bytecode),
342            InputsImpl::default(),
343            false,
344            SpecId::default(),
345            u64::MAX,
346        );
347
348        let serialized =
349            bincode::serde::encode_to_vec(&interpreter, bincode::config::legacy()).unwrap();
350
351        let deserialized: Interpreter<EthInterpreter> =
352            bincode::serde::decode_from_slice(&serialized, bincode::config::legacy())
353                .unwrap()
354                .0;
355
356        assert_eq!(
357            interpreter.bytecode.pc(),
358            deserialized.bytecode.pc(),
359            "Program counter should be preserved"
360        );
361    }
362}
revm_interpreter/interpreter.rs

revm_interpreter/
interpreter.rs
