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

revm_interpreter/
interpreter.rs
