evm_runtime/
handler.rs

1use crate::{Capture, Context, CreateScheme, ExitError, ExitReason, Machine, Opcode, Stack};
2use alloc::vec::Vec;
3use primitive_types::{H160, H256, U256};
4
5/// Transfer from source to target, with given value.
6#[derive(Clone, Debug)]
7pub struct Transfer {
8	/// Source address.
9	pub source: H160,
10	/// Target address.
11	pub target: H160,
12	/// Transfer value.
13	pub value: U256,
14}
15
16/// EVM context handler.
17#[auto_impl::auto_impl(&mut, Box)]
18pub trait Handler {
19	/// Type of `CREATE` interrupt.
20	type CreateInterrupt;
21	/// Feedback value for `CREATE` interrupt.
22	type CreateFeedback;
23	/// Type of `CALL` interrupt.
24	type CallInterrupt;
25	/// Feedback value of `CALL` interrupt.
26	type CallFeedback;
27
28	/// Get balance of address.
29	fn balance(&self, address: H160) -> U256;
30	/// Get code size of address.
31	fn code_size(&self, address: H160) -> U256;
32	/// Get code hash of address.
33	fn code_hash(&self, address: H160) -> H256;
34	/// Get code of address.
35	fn code(&self, address: H160) -> Vec<u8>;
36	/// Get code of address, following EIP-7702 delegations if enabled.
37	fn delegated_code(&self, address: H160) -> Option<Vec<u8>> {
38		let code = self.code(address);
39		evm_core::extract_delegation_address(&code)
40			.map(|delegated_address| self.code(delegated_address))
41	}
42	/// Get storage value of address at index.
43	fn storage(&self, address: H160, index: H256) -> H256;
44	/// Get transient storage value of address at index.
45	fn transient_storage(&self, address: H160, index: H256) -> H256;
46
47	/// Get original storage value of address at index.
48	fn original_storage(&self, address: H160, index: H256) -> H256;
49
50	/// Get the gas left value.
51	fn gas_left(&self) -> U256;
52	/// Get the gas price value.
53	fn gas_price(&self) -> U256;
54	/// Get execution origin.
55	fn origin(&self) -> H160;
56	/// Get environmental block hash.
57	fn block_hash(&self, number: U256) -> H256;
58	/// Get environmental block number.
59	fn block_number(&self) -> U256;
60	/// Get environmental coinbase.
61	fn block_coinbase(&self) -> H160;
62	/// Get environmental block timestamp.
63	fn block_timestamp(&self) -> U256;
64	/// Get environmental block difficulty.
65	fn block_difficulty(&self) -> U256;
66	/// Get environmental block randomness.
67	fn block_randomness(&self) -> Option<H256>;
68	/// Get environmental gas limit.
69	fn block_gas_limit(&self) -> U256;
70	/// Environmental block base fee.
71	fn block_base_fee_per_gas(&self) -> U256;
72	/// Get environmental chain ID.
73	fn chain_id(&self) -> U256;
74
75	/// Check whether an address exists.
76	fn exists(&self, address: H160) -> bool;
77	/// Check whether an address has already been deleted.
78	fn deleted(&self, address: H160) -> bool;
79	/// Checks if the address or (address, index) pair has been previously accessed
80	/// (or set in `accessed_addresses` / `accessed_storage_keys` via an access list
81	/// transaction).
82	/// References:
83	/// * <https://eips.ethereum.org/EIPS/eip-2929>
84	/// * <https://eips.ethereum.org/EIPS/eip-2930>
85	fn is_cold(&mut self, address: H160, index: Option<H256>) -> Result<bool, ExitError>;
86
87	/// Set storage value of address at index.
88	fn set_storage(&mut self, address: H160, index: H256, value: H256) -> Result<(), ExitError>;
89	/// Set transient storage value of address at index, transient storage gets discarded after every transaction. (see EIP-1153)
90	fn set_transient_storage(&mut self, address: H160, index: H256, value: H256);
91	/// Create a log owned by address with given topics and data.
92	fn log(&mut self, address: H160, topics: Vec<H256>, data: Vec<u8>) -> Result<(), ExitError>;
93	/// Mark an address to be deleted, with funds transferred to target.
94	fn mark_delete(&mut self, address: H160, target: H160) -> Result<(), ExitError>;
95	/// Invoke a create operation.
96	fn create(
97		&mut self,
98		caller: H160,
99		scheme: CreateScheme,
100		value: U256,
101		init_code: Vec<u8>,
102		target_gas: Option<u64>,
103	) -> Capture<(ExitReason, Option<H160>, Vec<u8>), Self::CreateInterrupt>;
104	/// Feed in create feedback.
105	fn create_feedback(&mut self, _feedback: Self::CreateFeedback) -> Result<(), ExitError> {
106		Ok(())
107	}
108	/// Invoke a call operation.
109	fn call(
110		&mut self,
111		code_address: H160,
112		transfer: Option<Transfer>,
113		input: Vec<u8>,
114		target_gas: Option<u64>,
115		is_static: bool,
116		context: Context,
117	) -> Capture<(ExitReason, Vec<u8>), Self::CallInterrupt>;
118	/// Feed in call feedback.
119	fn call_feedback(&mut self, _feedback: Self::CallFeedback) -> Result<(), ExitError> {
120		Ok(())
121	}
122
123	/// Pre-validation step for the runtime.
124	fn pre_validate(
125		&mut self,
126		context: &Context,
127		opcode: Opcode,
128		stack: &Stack,
129	) -> Result<(), ExitError>;
130	/// Handle other unknown external opcodes.
131	fn other(&mut self, opcode: Opcode, _stack: &mut Machine) -> Result<(), ExitError> {
132		Err(ExitError::InvalidCode(opcode))
133	}
134
135	/// Records some associated `ExternalOperation`.
136	fn record_external_operation(&mut self, op: crate::ExternalOperation) -> Result<(), ExitError>;
137}
evm_runtime/handler.rs

evm_runtime/
handler.rs
