revm_interpreter/interpreter_types.rs
1use crate::{CallInput, InstructionResult, InterpreterAction};
2use core::cell::Ref;
3use core::ops::{Deref, Range};
4use primitives::{hardfork::SpecId, Address, Bytes, B256, U256};
5
6/// Helper function to read immediates data from the bytecode
7pub trait Immediates {
8 /// Reads next 16 bits as signed integer from the bytecode.
9 #[inline]
10 fn read_i16(&self) -> i16 {
11 self.read_u16() as i16
12 }
13 /// Reads next 16 bits as unsigned integer from the bytecode.
14 fn read_u16(&self) -> u16;
15
16 /// Reads next 8 bits as signed integer from the bytecode.
17 #[inline]
18 fn read_i8(&self) -> i8 {
19 self.read_u8() as i8
20 }
21
22 /// Reads next 8 bits as unsigned integer from the bytecode.
23 fn read_u8(&self) -> u8;
24
25 /// Reads next 16 bits as signed integer from the bytecode at given offset.
26 #[inline]
27 fn read_offset_i16(&self, offset: isize) -> i16 {
28 self.read_offset_u16(offset) as i16
29 }
30
31 /// Reads next 16 bits as unsigned integer from the bytecode at given offset.
32 fn read_offset_u16(&self, offset: isize) -> u16;
33
34 /// Reads next `len` bytes from the bytecode.
35 ///
36 /// Used by PUSH opcode.
37 fn read_slice(&self, len: usize) -> &[u8];
38}
39
40/// Trait for fetching inputs of the call.
41pub trait InputsTr {
42 /// Returns target address of the call.
43 fn target_address(&self) -> Address;
44 /// Returns bytecode address of the call. For DELEGATECALL this address will be different from target address.
45 /// And if initcode is called this address will be [`None`].
46 fn bytecode_address(&self) -> Option<&Address>;
47 /// Returns caller address of the call.
48 fn caller_address(&self) -> Address;
49 /// Returns input of the call.
50 fn input(&self) -> &CallInput;
51 /// Returns call value of the call.
52 fn call_value(&self) -> U256;
53}
54
55/// Trait needed for legacy bytecode.
56///
57/// Used in [`bytecode::opcode::CODECOPY`] and [`bytecode::opcode::CODESIZE`] opcodes.
58pub trait LegacyBytecode {
59 /// Returns current bytecode original length. Used in [`bytecode::opcode::CODESIZE`] opcode.
60 fn bytecode_len(&self) -> usize;
61 /// Returns current bytecode original slice. Used in [`bytecode::opcode::CODECOPY`] opcode.
62 fn bytecode_slice(&self) -> &[u8];
63}
64
65/// Trait for Interpreter to be able to jump
66pub trait Jumps {
67 /// Relative jumps does not require checking for overflow.
68 fn relative_jump(&mut self, offset: isize);
69 /// Absolute jumps require checking for overflow and if target is a jump destination
70 /// from jump table.
71 fn absolute_jump(&mut self, offset: usize);
72 /// Check legacy jump destination from jump table.
73 fn is_valid_legacy_jump(&mut self, offset: usize) -> bool;
74 /// Returns current program counter.
75 fn pc(&self) -> usize;
76 /// Returns instruction opcode.
77 fn opcode(&self) -> u8;
78}
79
80/// Trait for Interpreter memory operations.
81pub trait MemoryTr {
82 /// Sets memory data at given offset from data with a given data_offset and len.
83 ///
84 /// # Panics
85 ///
86 /// Panics if range is out of scope of allocated memory.
87 fn set_data(&mut self, memory_offset: usize, data_offset: usize, len: usize, data: &[u8]);
88
89 /// Inner clone part of memory from global context to local context.
90 /// This is used to clone calldata to memory.
91 ///
92 /// # Panics
93 ///
94 /// Panics if range is out of scope of allocated memory.
95 fn set_data_from_global(
96 &mut self,
97 memory_offset: usize,
98 data_offset: usize,
99 len: usize,
100 data_range: Range<usize>,
101 );
102
103 /// Memory slice with global range. This range
104 ///
105 /// # Panics
106 ///
107 /// Panics if range is out of scope of allocated memory.
108 fn global_slice(&self, range: Range<usize>) -> Ref<'_, [u8]>;
109
110 /// Offset of local context of memory.
111 fn local_memory_offset(&self) -> usize;
112
113 /// Sets memory data at given offset.
114 ///
115 /// # Panics
116 ///
117 /// Panics if range is out of scope of allocated memory.
118 fn set(&mut self, memory_offset: usize, data: &[u8]);
119
120 /// Returns memory size.
121 fn size(&self) -> usize;
122
123 /// Copies memory data from source to destination.
124 ///
125 /// # Panics
126 /// Panics if range is out of scope of allocated memory.
127 fn copy(&mut self, destination: usize, source: usize, len: usize);
128
129 /// Memory slice with range
130 ///
131 /// # Panics
132 ///
133 /// Panics if range is out of scope of allocated memory.
134 fn slice(&self, range: Range<usize>) -> Ref<'_, [u8]>;
135
136 /// Memory slice len
137 ///
138 /// Uses [`slice`][MemoryTr::slice] internally.
139 fn slice_len(&self, offset: usize, len: usize) -> impl Deref<Target = [u8]> + '_ {
140 self.slice(offset..offset + len)
141 }
142
143 /// Resizes memory to new size
144 ///
145 /// # Note
146 ///
147 /// It checks memory limits.
148 fn resize(&mut self, new_size: usize) -> bool;
149}
150
151/// Functions needed for Interpreter Stack operations.
152pub trait StackTr {
153 /// Returns stack length.
154 fn len(&self) -> usize;
155
156 /// Returns `true` if stack is empty.
157 fn is_empty(&self) -> bool {
158 self.len() == 0
159 }
160
161 /// Clears the stack.
162 fn clear(&mut self);
163
164 /// Pushes values to the stack.
165 ///
166 /// Returns `true` if push was successful, `false` if stack overflow.
167 ///
168 /// # Note
169 /// Error is internally set in interpreter.
170 #[must_use]
171 fn push(&mut self, value: U256) -> bool;
172
173 /// Pushes slice to the stack.
174 ///
175 /// Returns `true` if push was successful, `false` if stack overflow.
176 ///
177 /// # Note
178 /// Error is internally set in interpreter.
179 fn push_slice(&mut self, slice: &[u8]) -> bool;
180
181 /// Pushes B256 value to the stack.
182 ///
183 /// Internally converts B256 to U256 and then calls [`StackTr::push`].
184 #[must_use]
185 fn push_b256(&mut self, value: B256) -> bool {
186 self.push(value.into())
187 }
188
189 /// Pops value from the stack.
190 #[must_use]
191 fn popn<const N: usize>(&mut self) -> Option<[U256; N]>;
192
193 /// Pop N values from the stack and return top value.
194 #[must_use]
195 fn popn_top<const POPN: usize>(&mut self) -> Option<([U256; POPN], &mut U256)>;
196
197 /// Returns top value from the stack.
198 #[must_use]
199 fn top(&mut self) -> Option<&mut U256> {
200 self.popn_top().map(|([], top)| top)
201 }
202
203 /// Pops one value from the stack.
204 #[must_use]
205 fn pop(&mut self) -> Option<U256> {
206 self.popn::<1>().map(|[value]| value)
207 }
208
209 /// Pops address from the stack.
210 ///
211 /// Internally call [`StackTr::pop`] and converts [`U256`] into [`Address`].
212 #[must_use]
213 fn pop_address(&mut self) -> Option<Address> {
214 self.pop().map(|value| Address::from(value.to_be_bytes()))
215 }
216
217 /// Exchanges two values on the stack.
218 ///
219 /// Indexes are based from the top of the stack.
220 ///
221 /// Returns `true` if swap was successful, `false` if stack underflow.
222 #[must_use]
223 fn exchange(&mut self, n: usize, m: usize) -> bool;
224
225 /// Duplicates the `N`th value from the top of the stack.
226 ///
227 /// Index is based from the top of the stack.
228 ///
229 /// Returns `true` if duplicate was successful, `false` if stack underflow.
230 #[must_use]
231 fn dup(&mut self, n: usize) -> bool;
232}
233
234/// Returns return data.
235pub trait ReturnData {
236 /// Returns return data.
237 fn buffer(&self) -> &Bytes;
238
239 /// Sets return buffer.
240 fn set_buffer(&mut self, bytes: Bytes);
241
242 /// Clears return buffer.
243 fn clear(&mut self) {
244 self.set_buffer(Bytes::new());
245 }
246}
247
248/// Trait controls execution of the loop.
249pub trait LoopControl {
250 /// Returns `true` if the loop should continue.
251 fn is_not_end(&self) -> bool;
252 /// Is end of the loop.
253 #[inline]
254 fn is_end(&self) -> bool {
255 !self.is_not_end()
256 }
257 /// Sets the `end` flag internally. Action should be taken after.
258 fn reset_action(&mut self);
259 /// Set return action.
260 fn set_action(&mut self, action: InterpreterAction);
261 /// Returns the current action.
262 fn action(&mut self) -> &mut Option<InterpreterAction>;
263 /// Returns instruction result
264 #[inline]
265 fn instruction_result(&mut self) -> Option<InstructionResult> {
266 self.action()
267 .as_ref()
268 .and_then(|action| action.instruction_result())
269 }
270}
271
272/// Runtime flags that control interpreter execution behavior.
273pub trait RuntimeFlag {
274 /// Returns true if the current execution context is static (read-only).
275 fn is_static(&self) -> bool;
276 /// Returns the current EVM specification ID.
277 fn spec_id(&self) -> SpecId;
278}
279
280/// Trait for interpreter execution.
281pub trait Interp {
282 /// The instruction type.
283 type Instruction;
284 /// The action type returned after execution.
285 type Action;
286
287 /// Runs the interpreter with the given instruction table.
288 fn run(&mut self, instructions: &[Self::Instruction; 256]) -> Self::Action;
289}
290
291/// Trait defining the component types used by an interpreter implementation.
292pub trait InterpreterTypes {
293 /// Stack implementation type.
294 type Stack: StackTr;
295 /// Memory implementation type.
296 type Memory: MemoryTr;
297 /// Bytecode implementation type.
298 type Bytecode: Jumps + Immediates + LoopControl + LegacyBytecode;
299 /// Return data implementation type.
300 type ReturnData: ReturnData;
301 /// Input data implementation type.
302 type Input: InputsTr;
303 /// Runtime flags implementation type.
304 type RuntimeFlag: RuntimeFlag;
305 /// Extended functionality type.
306 type Extend;
307 /// Output type for execution results.
308 type Output;
309}