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, resize_memory, 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    /// Performs EVM memory resize.
187    #[inline]
188    #[must_use]
189    pub fn resize_memory(&mut self, offset: usize, len: usize) -> bool {
190        resize_memory(&mut self.gas, &mut self.memory, offset, len)
191    }
192
193    /// Takes the next action from the control and returns it.
194    #[inline]
195    pub fn take_next_action(&mut self) -> InterpreterAction {
196        self.bytecode.reset_action();
197        // Return next action if it is some.
198        let action = core::mem::take(self.bytecode.action()).expect("Interpreter to set action");
199        action
200    }
201
202    /// Halt the interpreter with the given result.
203    ///
204    /// This will set the action to [`InterpreterAction::Return`] and set the gas to the current gas.
205    #[cold]
206    #[inline(never)]
207    pub fn halt(&mut self, result: InstructionResult) {
208        self.bytecode
209            .set_action(InterpreterAction::new_halt(result, self.gas));
210    }
211
212    /// Halt the interpreter with an out-of-gas error.
213    #[cold]
214    #[inline(never)]
215    pub fn halt_oog(&mut self) {
216        self.gas.spend_all();
217        self.halt(InstructionResult::OutOfGas);
218    }
219
220    /// Halt the interpreter with an out-of-gas error.
221    #[cold]
222    #[inline(never)]
223    pub fn halt_memory_oog(&mut self) {
224        self.halt(InstructionResult::MemoryLimitOOG);
225    }
226
227    /// Halt the interpreter with and overflow error.
228    #[cold]
229    #[inline(never)]
230    pub fn halt_overflow(&mut self) {
231        self.halt(InstructionResult::StackOverflow);
232    }
233
234    /// Halt the interpreter with and underflow error.
235    #[cold]
236    #[inline(never)]
237    pub fn halt_underflow(&mut self) {
238        self.halt(InstructionResult::StackUnderflow);
239    }
240
241    /// Halt the interpreter with and not activated error.
242    #[cold]
243    #[inline(never)]
244    pub fn halt_not_activated(&mut self) {
245        self.halt(InstructionResult::NotActivated);
246    }
247
248    /// Return with the given output.
249    ///
250    /// This will set the action to [`InterpreterAction::Return`] and set the gas to the current gas.
251    pub fn return_with_output(&mut self, output: Bytes) {
252        self.bytecode.set_action(InterpreterAction::new_return(
253            InstructionResult::Return,
254            output,
255            self.gas,
256        ));
257    }
258
259    /// Executes the instruction at the current instruction pointer.
260    ///
261    /// Internally it will increment instruction pointer by one.
262    #[inline]
263    pub fn step<H: Host + ?Sized>(
264        &mut self,
265        instruction_table: &InstructionTable<IW, H>,
266        host: &mut H,
267    ) {
268        // Get current opcode.
269        let opcode = self.bytecode.opcode();
270
271        // SAFETY: In analysis we are doing padding of bytecode so that we are sure that last
272        // byte instruction is STOP so we are safe to just increment program_counter bcs on last instruction
273        // it will do noop and just stop execution of this contract
274        self.bytecode.relative_jump(1);
275
276        let instruction = unsafe { instruction_table.get_unchecked(opcode as usize) };
277
278        if self.gas.record_cost_unsafe(instruction.static_gas()) {
279            return self.halt_oog();
280        }
281        let context = InstructionContext {
282            interpreter: self,
283            host,
284        };
285        instruction.execute(context);
286    }
287
288    /// Executes the instruction at the current instruction pointer.
289    ///
290    /// Internally it will increment instruction pointer by one.
291    ///
292    /// This uses dummy Host.
293    #[inline]
294    pub fn step_dummy(&mut self, instruction_table: &InstructionTable<IW, DummyHost>) {
295        self.step(instruction_table, &mut DummyHost);
296    }
297
298    /// Executes the interpreter until it returns or stops.
299    #[inline]
300    pub fn run_plain<H: Host + ?Sized>(
301        &mut self,
302        instruction_table: &InstructionTable<IW, H>,
303        host: &mut H,
304    ) -> InterpreterAction {
305        while self.bytecode.is_not_end() {
306            self.step(instruction_table, host);
307        }
308        self.take_next_action()
309    }
310}
311
312/* used for cargo asm
313pub fn asm_step(
314    interpreter: &mut Interpreter<EthInterpreter>,
315    instruction_table: &InstructionTable<EthInterpreter, DummyHost>,
316    host: &mut DummyHost,
317) {
318    interpreter.step(instruction_table, host);
319}
320
321pub fn asm_run(
322    interpreter: &mut Interpreter<EthInterpreter>,
323    instruction_table: &InstructionTable<EthInterpreter, DummyHost>,
324    host: &mut DummyHost,
325) {
326    interpreter.run_plain(instruction_table, host);
327}
328*/
329
330/// The result of an interpreter operation.
331#[derive(Clone, Debug, PartialEq, Eq)]
332#[cfg_attr(feature = "serde", derive(::serde::Serialize, ::serde::Deserialize))]
333pub struct InterpreterResult {
334    /// The result of the instruction execution.
335    pub result: InstructionResult,
336    /// The output of the instruction execution.
337    pub output: Bytes,
338    /// The gas usage information.
339    pub gas: Gas,
340}
341
342impl InterpreterResult {
343    /// Returns a new `InterpreterResult` with the given values.
344    pub fn new(result: InstructionResult, output: Bytes, gas: Gas) -> Self {
345        Self {
346            result,
347            output,
348            gas,
349        }
350    }
351
352    /// Returns whether the instruction result is a success.
353    #[inline]
354    pub const fn is_ok(&self) -> bool {
355        self.result.is_ok()
356    }
357
358    /// Returns whether the instruction result is a revert.
359    #[inline]
360    pub const fn is_revert(&self) -> bool {
361        self.result.is_revert()
362    }
363
364    /// Returns whether the instruction result is an error.
365    #[inline]
366    pub const fn is_error(&self) -> bool {
367        self.result.is_error()
368    }
369}
370
371// Special implementation for types where Output can be created from InterpreterAction
372impl<IW: InterpreterTypes> Interpreter<IW>
373where
374    IW::Output: From<InterpreterAction>,
375{
376    /// Takes the next action from the control and returns it as the specific Output type.
377    #[inline]
378    pub fn take_next_action_as_output(&mut self) -> IW::Output {
379        From::from(self.take_next_action())
380    }
381
382    /// Executes the interpreter until it returns or stops, returning the specific Output type.
383    #[inline]
384    pub fn run_plain_as_output<H: Host + ?Sized>(
385        &mut self,
386        instruction_table: &InstructionTable<IW, H>,
387        host: &mut H,
388    ) -> IW::Output {
389        From::from(self.run_plain(instruction_table, host))
390    }
391}
392
393#[cfg(test)]
394mod tests {
395    #[test]
396    #[cfg(feature = "serde")]
397    fn test_interpreter_serde() {
398        use super::*;
399        use bytecode::Bytecode;
400        use primitives::Bytes;
401
402        let bytecode = Bytecode::new_raw(Bytes::from(&[0x60, 0x00, 0x60, 0x00, 0x01][..]));
403        let interpreter = Interpreter::<EthInterpreter>::new(
404            SharedMemory::new(),
405            ExtBytecode::new(bytecode),
406            InputsImpl::default(),
407            false,
408            SpecId::default(),
409            u64::MAX,
410        );
411
412        let serialized =
413            bincode::serde::encode_to_vec(&interpreter, bincode::config::legacy()).unwrap();
414
415        let deserialized: Interpreter<EthInterpreter> =
416            bincode::serde::decode_from_slice(&serialized, bincode::config::legacy())
417                .unwrap()
418                .0;
419
420        assert_eq!(
421            interpreter.bytecode.pc(),
422            deserialized.bytecode.pc(),
423            "Program counter should be preserved"
424        );
425    }
426}
revm_interpreter/interpreter.rs

revm_interpreter/
interpreter.rs
