revm_interpreter/
instructions.rs

1//! EVM opcode implementations.
2
3#[macro_use]
4pub mod macros;
5/// Arithmetic operations (ADD, SUB, MUL, DIV, etc.).
6pub mod arithmetic;
7/// Bitwise operations (AND, OR, XOR, NOT, etc.).
8pub mod bitwise;
9/// Block information instructions (COINBASE, TIMESTAMP, etc.).
10pub mod block_info;
11/// Contract operations (CALL, CREATE, DELEGATECALL, etc.).
12pub mod contract;
13/// Control flow instructions (JUMP, JUMPI, REVERT, etc.).
14pub mod control;
15/// Host environment interactions (SLOAD, SSTORE, LOG, etc.).
16pub mod host;
17/// Signed 256-bit integer operations.
18pub mod i256;
19/// Memory operations (MLOAD, MSTORE, MSIZE, etc.).
20pub mod memory;
21/// Stack operations (PUSH, POP, DUP, SWAP, etc.).
22pub mod stack;
23/// System information instructions (ADDRESS, CALLER, etc.).
24pub mod system;
25/// Transaction information instructions (ORIGIN, GASPRICE, etc.).
26pub mod tx_info;
27/// Utility functions and helpers for instruction implementation.
28pub mod utility;
29
30use crate::{interpreter_types::InterpreterTypes, Host, InstructionContext};
31
32/// EVM opcode function signature.
33#[derive(Debug, PartialEq, Eq)]
34pub struct Instruction<W: InterpreterTypes, H: ?Sized> {
35    fn_: fn(InstructionContext<'_, H, W>),
36    static_gas: u64,
37}
38
39impl<W: InterpreterTypes, H: Host + ?Sized> Instruction<W, H> {
40    /// Creates a new instruction with the given function and static gas cost.
41    #[inline]
42    pub const fn new(fn_: fn(InstructionContext<'_, H, W>), static_gas: u64) -> Self {
43        Self { fn_, static_gas }
44    }
45
46    /// Creates an unknown/invalid instruction.
47    #[inline]
48    pub const fn unknown() -> Self {
49        Self {
50            fn_: control::unknown,
51            static_gas: 0,
52        }
53    }
54
55    /// Executes the instruction with the given context.
56    #[inline(always)]
57    pub fn execute(self, ctx: InstructionContext<'_, H, W>) {
58        (self.fn_)(ctx)
59    }
60
61    /// Returns the static gas cost of this instruction.
62    #[inline(always)]
63    pub const fn static_gas(&self) -> u64 {
64        self.static_gas
65    }
66}
67
68impl<W: InterpreterTypes, H: Host + ?Sized> Copy for Instruction<W, H> {}
69impl<W: InterpreterTypes, H: Host + ?Sized> Clone for Instruction<W, H> {
70    fn clone(&self) -> Self {
71        *self
72    }
73}
74
75/// Instruction table is list of instruction function pointers mapped to 256 EVM opcodes.
76pub type InstructionTable<W, H> = [Instruction<W, H>; 256];
77
78/// Returns the default instruction table for the given interpreter types and host.
79#[inline]
80pub const fn instruction_table<WIRE: InterpreterTypes, H: Host>() -> [Instruction<WIRE, H>; 256] {
81    const { instruction_table_impl::<WIRE, H>() }
82}
83
84const fn instruction_table_impl<WIRE: InterpreterTypes, H: Host>() -> [Instruction<WIRE, H>; 256] {
85    use bytecode::opcode::*;
86    let mut table = [Instruction::unknown(); 256];
87
88    table[STOP as usize] = Instruction::new(control::stop, 0);
89    table[ADD as usize] = Instruction::new(arithmetic::add, 3);
90    table[MUL as usize] = Instruction::new(arithmetic::mul, 5);
91    table[SUB as usize] = Instruction::new(arithmetic::sub, 3);
92    table[DIV as usize] = Instruction::new(arithmetic::div, 5);
93    table[SDIV as usize] = Instruction::new(arithmetic::sdiv, 5);
94    table[MOD as usize] = Instruction::new(arithmetic::rem, 5);
95    table[SMOD as usize] = Instruction::new(arithmetic::smod, 5);
96    table[ADDMOD as usize] = Instruction::new(arithmetic::addmod, 8);
97    table[MULMOD as usize] = Instruction::new(arithmetic::mulmod, 8);
98    table[EXP as usize] = Instruction::new(arithmetic::exp, 0); // dynamic
99    table[SIGNEXTEND as usize] = Instruction::new(arithmetic::signextend, 5);
100
101    table[LT as usize] = Instruction::new(bitwise::lt, 3);
102    table[GT as usize] = Instruction::new(bitwise::gt, 3);
103    table[SLT as usize] = Instruction::new(bitwise::slt, 3);
104    table[SGT as usize] = Instruction::new(bitwise::sgt, 3);
105    table[EQ as usize] = Instruction::new(bitwise::eq, 3);
106    table[ISZERO as usize] = Instruction::new(bitwise::iszero, 3);
107    table[AND as usize] = Instruction::new(bitwise::bitand, 3);
108    table[OR as usize] = Instruction::new(bitwise::bitor, 3);
109    table[XOR as usize] = Instruction::new(bitwise::bitxor, 3);
110    table[NOT as usize] = Instruction::new(bitwise::not, 3);
111    table[BYTE as usize] = Instruction::new(bitwise::byte, 3);
112    table[SHL as usize] = Instruction::new(bitwise::shl, 3);
113    table[SHR as usize] = Instruction::new(bitwise::shr, 3);
114    table[SAR as usize] = Instruction::new(bitwise::sar, 3);
115    table[CLZ as usize] = Instruction::new(bitwise::clz, 5);
116
117    table[KECCAK256 as usize] = Instruction::new(system::keccak256, 0); // dynamic
118
119    table[ADDRESS as usize] = Instruction::new(system::address, 2);
120    table[BALANCE as usize] = Instruction::new(host::balance, 0); // dynamic
121    table[ORIGIN as usize] = Instruction::new(tx_info::origin, 2);
122    table[CALLER as usize] = Instruction::new(system::caller, 2);
123    table[CALLVALUE as usize] = Instruction::new(system::callvalue, 2);
124    table[CALLDATALOAD as usize] = Instruction::new(system::calldataload, 3);
125    table[CALLDATASIZE as usize] = Instruction::new(system::calldatasize, 2);
126    table[CALLDATACOPY as usize] = Instruction::new(system::calldatacopy, 0); // static 2, mostly dynamic
127    table[CODESIZE as usize] = Instruction::new(system::codesize, 2);
128    table[CODECOPY as usize] = Instruction::new(system::codecopy, 0); // static 2, mostly dynamic
129
130    table[GASPRICE as usize] = Instruction::new(tx_info::gasprice, 2);
131    table[EXTCODESIZE as usize] = Instruction::new(host::extcodesize, 0); // dynamic
132    table[EXTCODECOPY as usize] = Instruction::new(host::extcodecopy, 0); // dynamic
133    table[RETURNDATASIZE as usize] = Instruction::new(system::returndatasize, 2);
134    table[RETURNDATACOPY as usize] = Instruction::new(system::returndatacopy, 0); // static 2, mostly dynamic
135    table[EXTCODEHASH as usize] = Instruction::new(host::extcodehash, 0); // dynamic
136    table[BLOCKHASH as usize] = Instruction::new(host::blockhash, 20);
137    table[COINBASE as usize] = Instruction::new(block_info::coinbase, 2);
138    table[TIMESTAMP as usize] = Instruction::new(block_info::timestamp, 2);
139    table[NUMBER as usize] = Instruction::new(block_info::block_number, 2);
140    table[DIFFICULTY as usize] = Instruction::new(block_info::difficulty, 2);
141    table[GASLIMIT as usize] = Instruction::new(block_info::gaslimit, 2);
142    table[CHAINID as usize] = Instruction::new(block_info::chainid, 2);
143    table[SELFBALANCE as usize] = Instruction::new(host::selfbalance, 5);
144    table[BASEFEE as usize] = Instruction::new(block_info::basefee, 2);
145    table[BLOBHASH as usize] = Instruction::new(tx_info::blob_hash, 3);
146    table[BLOBBASEFEE as usize] = Instruction::new(block_info::blob_basefee, 2);
147
148    table[POP as usize] = Instruction::new(stack::pop, 2);
149    table[MLOAD as usize] = Instruction::new(memory::mload, 3);
150    table[MSTORE as usize] = Instruction::new(memory::mstore, 3);
151    table[MSTORE8 as usize] = Instruction::new(memory::mstore8, 3);
152    table[SLOAD as usize] = Instruction::new(host::sload, 0); // dynamic
153    table[SSTORE as usize] = Instruction::new(host::sstore, 0); // dynamic
154    table[JUMP as usize] = Instruction::new(control::jump, 8);
155    table[JUMPI as usize] = Instruction::new(control::jumpi, 10);
156    table[PC as usize] = Instruction::new(control::pc, 2);
157    table[MSIZE as usize] = Instruction::new(memory::msize, 2);
158    table[GAS as usize] = Instruction::new(system::gas, 2);
159    table[JUMPDEST as usize] = Instruction::new(control::jumpdest, 1);
160    table[TLOAD as usize] = Instruction::new(host::tload, 100);
161    table[TSTORE as usize] = Instruction::new(host::tstore, 100);
162    table[MCOPY as usize] = Instruction::new(memory::mcopy, 0); // static 2, mostly dynamic
163
164    table[PUSH0 as usize] = Instruction::new(stack::push0, 2);
165    table[PUSH1 as usize] = Instruction::new(stack::push::<1, _, _>, 3);
166    table[PUSH2 as usize] = Instruction::new(stack::push::<2, _, _>, 3);
167    table[PUSH3 as usize] = Instruction::new(stack::push::<3, _, _>, 3);
168    table[PUSH4 as usize] = Instruction::new(stack::push::<4, _, _>, 3);
169    table[PUSH5 as usize] = Instruction::new(stack::push::<5, _, _>, 3);
170    table[PUSH6 as usize] = Instruction::new(stack::push::<6, _, _>, 3);
171    table[PUSH7 as usize] = Instruction::new(stack::push::<7, _, _>, 3);
172    table[PUSH8 as usize] = Instruction::new(stack::push::<8, _, _>, 3);
173    table[PUSH9 as usize] = Instruction::new(stack::push::<9, _, _>, 3);
174    table[PUSH10 as usize] = Instruction::new(stack::push::<10, _, _>, 3);
175    table[PUSH11 as usize] = Instruction::new(stack::push::<11, _, _>, 3);
176    table[PUSH12 as usize] = Instruction::new(stack::push::<12, _, _>, 3);
177    table[PUSH13 as usize] = Instruction::new(stack::push::<13, _, _>, 3);
178    table[PUSH14 as usize] = Instruction::new(stack::push::<14, _, _>, 3);
179    table[PUSH15 as usize] = Instruction::new(stack::push::<15, _, _>, 3);
180    table[PUSH16 as usize] = Instruction::new(stack::push::<16, _, _>, 3);
181    table[PUSH17 as usize] = Instruction::new(stack::push::<17, _, _>, 3);
182    table[PUSH18 as usize] = Instruction::new(stack::push::<18, _, _>, 3);
183    table[PUSH19 as usize] = Instruction::new(stack::push::<19, _, _>, 3);
184    table[PUSH20 as usize] = Instruction::new(stack::push::<20, _, _>, 3);
185    table[PUSH21 as usize] = Instruction::new(stack::push::<21, _, _>, 3);
186    table[PUSH22 as usize] = Instruction::new(stack::push::<22, _, _>, 3);
187    table[PUSH23 as usize] = Instruction::new(stack::push::<23, _, _>, 3);
188    table[PUSH24 as usize] = Instruction::new(stack::push::<24, _, _>, 3);
189    table[PUSH25 as usize] = Instruction::new(stack::push::<25, _, _>, 3);
190    table[PUSH26 as usize] = Instruction::new(stack::push::<26, _, _>, 3);
191    table[PUSH27 as usize] = Instruction::new(stack::push::<27, _, _>, 3);
192    table[PUSH28 as usize] = Instruction::new(stack::push::<28, _, _>, 3);
193    table[PUSH29 as usize] = Instruction::new(stack::push::<29, _, _>, 3);
194    table[PUSH30 as usize] = Instruction::new(stack::push::<30, _, _>, 3);
195    table[PUSH31 as usize] = Instruction::new(stack::push::<31, _, _>, 3);
196    table[PUSH32 as usize] = Instruction::new(stack::push::<32, _, _>, 3);
197
198    table[DUP1 as usize] = Instruction::new(stack::dup::<1, _, _>, 3);
199    table[DUP2 as usize] = Instruction::new(stack::dup::<2, _, _>, 3);
200    table[DUP3 as usize] = Instruction::new(stack::dup::<3, _, _>, 3);
201    table[DUP4 as usize] = Instruction::new(stack::dup::<4, _, _>, 3);
202    table[DUP5 as usize] = Instruction::new(stack::dup::<5, _, _>, 3);
203    table[DUP6 as usize] = Instruction::new(stack::dup::<6, _, _>, 3);
204    table[DUP7 as usize] = Instruction::new(stack::dup::<7, _, _>, 3);
205    table[DUP8 as usize] = Instruction::new(stack::dup::<8, _, _>, 3);
206    table[DUP9 as usize] = Instruction::new(stack::dup::<9, _, _>, 3);
207    table[DUP10 as usize] = Instruction::new(stack::dup::<10, _, _>, 3);
208    table[DUP11 as usize] = Instruction::new(stack::dup::<11, _, _>, 3);
209    table[DUP12 as usize] = Instruction::new(stack::dup::<12, _, _>, 3);
210    table[DUP13 as usize] = Instruction::new(stack::dup::<13, _, _>, 3);
211    table[DUP14 as usize] = Instruction::new(stack::dup::<14, _, _>, 3);
212    table[DUP15 as usize] = Instruction::new(stack::dup::<15, _, _>, 3);
213    table[DUP16 as usize] = Instruction::new(stack::dup::<16, _, _>, 3);
214
215    table[SWAP1 as usize] = Instruction::new(stack::swap::<1, _, _>, 3);
216    table[SWAP2 as usize] = Instruction::new(stack::swap::<2, _, _>, 3);
217    table[SWAP3 as usize] = Instruction::new(stack::swap::<3, _, _>, 3);
218    table[SWAP4 as usize] = Instruction::new(stack::swap::<4, _, _>, 3);
219    table[SWAP5 as usize] = Instruction::new(stack::swap::<5, _, _>, 3);
220    table[SWAP6 as usize] = Instruction::new(stack::swap::<6, _, _>, 3);
221    table[SWAP7 as usize] = Instruction::new(stack::swap::<7, _, _>, 3);
222    table[SWAP8 as usize] = Instruction::new(stack::swap::<8, _, _>, 3);
223    table[SWAP9 as usize] = Instruction::new(stack::swap::<9, _, _>, 3);
224    table[SWAP10 as usize] = Instruction::new(stack::swap::<10, _, _>, 3);
225    table[SWAP11 as usize] = Instruction::new(stack::swap::<11, _, _>, 3);
226    table[SWAP12 as usize] = Instruction::new(stack::swap::<12, _, _>, 3);
227    table[SWAP13 as usize] = Instruction::new(stack::swap::<13, _, _>, 3);
228    table[SWAP14 as usize] = Instruction::new(stack::swap::<14, _, _>, 3);
229    table[SWAP15 as usize] = Instruction::new(stack::swap::<15, _, _>, 3);
230    table[SWAP16 as usize] = Instruction::new(stack::swap::<16, _, _>, 3);
231
232    table[LOG0 as usize] = Instruction::new(host::log::<0, _>, 0); // dynamic
233    table[LOG1 as usize] = Instruction::new(host::log::<1, _>, 0); // dynamic
234    table[LOG2 as usize] = Instruction::new(host::log::<2, _>, 0); // dynamic
235    table[LOG3 as usize] = Instruction::new(host::log::<3, _>, 0); // dynamic
236    table[LOG4 as usize] = Instruction::new(host::log::<4, _>, 0); // dynamic
237
238    table[CREATE as usize] = Instruction::new(contract::create::<_, false, _>, 0); // dynamic
239    table[CALL as usize] = Instruction::new(contract::call, 0); // dynamic
240    table[CALLCODE as usize] = Instruction::new(contract::call_code, 0); // dynamic
241    table[RETURN as usize] = Instruction::new(control::ret, 0);
242    table[DELEGATECALL as usize] = Instruction::new(contract::delegate_call, 0); // dynamic
243    table[CREATE2 as usize] = Instruction::new(contract::create::<_, true, _>, 0); // dynamic
244
245    table[STATICCALL as usize] = Instruction::new(contract::static_call, 0); // dynamic
246    table[REVERT as usize] = Instruction::new(control::revert, 0);
247    table[INVALID as usize] = Instruction::new(control::invalid, 0);
248    table[SELFDESTRUCT as usize] = Instruction::new(host::selfdestruct, 0); // dynamic
249    table
250}
251
252#[cfg(test)]
253mod tests {
254    use super::instruction_table;
255    use crate::{host::DummyHost, interpreter::EthInterpreter};
256    use bytecode::opcode::*;
257
258    #[test]
259    fn all_instructions_and_opcodes_used() {
260        // known unknown instruction we compare it with other instructions from table.
261        let unknown_instruction = 0x0C_usize;
262        let instr_table = instruction_table::<EthInterpreter, DummyHost>();
263
264        let unknown_istr = instr_table[unknown_instruction];
265        for (i, instr) in instr_table.iter().enumerate() {
266            let is_opcode_unknown = OpCode::new(i as u8).is_none();
267            //
268            let is_instr_unknown = std::ptr::fn_addr_eq(instr.fn_, unknown_istr.fn_);
269            assert_eq!(
270                is_instr_unknown, is_opcode_unknown,
271                "Opcode 0x{i:X?} is not handled",
272            );
273        }
274    }
275}