arb_stylus/
evm_api.rs

1use crate::ink::{Gas, Ink};
2use alloy_primitives::{Address, B256, U256};
3
4/// Status codes returned by EVM API operations.
5#[derive(Clone, Copy, Debug, PartialEq, Eq)]
6#[repr(u8)]
7pub enum EvmApiStatus {
8    Success = 0,
9    Failure = 1,
10    OutOfGas = 2,
11    WriteProtection = 3,
12}
13
14/// Outcome kind from a user program or call.
15#[derive(Clone, Copy, Debug, PartialEq, Eq)]
16#[repr(u8)]
17pub enum UserOutcomeKind {
18    Success = 0,
19    Revert = 1,
20    Failure = 2,
21    OutOfInk = 3,
22    OutOfStack = 4,
23}
24
25/// Response from a CREATE operation.
26pub enum CreateResponse {
27    Success(Address),
28    Fail(String),
29}
30
31/// The EVM API trait that Stylus programs use to interact with EVM state.
32///
33/// This is the bridge between the WASM runtime and the EVM execution environment.
34/// Implementations are provided by the block executor.
35pub trait EvmApi: Send + 'static {
36    /// Read a storage slot. Returns the value and access cost.
37    fn get_bytes32(&mut self, key: B256, evm_api_gas_to_use: Gas) -> eyre::Result<(B256, Gas)>;
38
39    /// Cache a storage value for later flushing.
40    fn cache_bytes32(&mut self, key: B256, value: B256) -> eyre::Result<Gas>;
41
42    /// Flush the storage cache to EVM state.
43    fn flush_storage_cache(
44        &mut self,
45        clear: bool,
46        gas_left: Gas,
47    ) -> eyre::Result<(Gas, UserOutcomeKind)>;
48
49    /// Read a transient storage slot.
50    fn get_transient_bytes32(&mut self, key: B256) -> eyre::Result<B256>;
51
52    /// Write a transient storage slot.
53    fn set_transient_bytes32(&mut self, key: B256, value: B256) -> eyre::Result<UserOutcomeKind>;
54
55    /// Execute a CALL. Returns return data length, gas cost, and outcome.
56    fn contract_call(
57        &mut self,
58        contract: Address,
59        calldata: &[u8],
60        gas_left: Gas,
61        gas_req: Gas,
62        value: U256,
63    ) -> eyre::Result<(u32, Gas, UserOutcomeKind)>;
64
65    /// Execute a DELEGATECALL.
66    fn delegate_call(
67        &mut self,
68        contract: Address,
69        calldata: &[u8],
70        gas_left: Gas,
71        gas_req: Gas,
72    ) -> eyre::Result<(u32, Gas, UserOutcomeKind)>;
73
74    /// Execute a STATICCALL.
75    fn static_call(
76        &mut self,
77        contract: Address,
78        calldata: &[u8],
79        gas_left: Gas,
80        gas_req: Gas,
81    ) -> eyre::Result<(u32, Gas, UserOutcomeKind)>;
82
83    /// Deploy via CREATE.
84    fn create1(
85        &mut self,
86        code: Vec<u8>,
87        endowment: U256,
88        gas: Gas,
89    ) -> eyre::Result<(CreateResponse, u32, Gas)>;
90
91    /// Deploy via CREATE2.
92    fn create2(
93        &mut self,
94        code: Vec<u8>,
95        endowment: U256,
96        salt: B256,
97        gas: Gas,
98    ) -> eyre::Result<(CreateResponse, u32, Gas)>;
99
100    /// Get the return data from the last call.
101    fn get_return_data(&self) -> Vec<u8>;
102
103    /// Emit a log with the given data and number of topics.
104    fn emit_log(&mut self, data: Vec<u8>, topics: u32) -> eyre::Result<()>;
105
106    /// Get an account's balance. Returns balance and access cost.
107    fn account_balance(&mut self, address: Address) -> eyre::Result<(U256, Gas)>;
108
109    /// Get an account's code. Returns code and access cost.
110    fn account_code(
111        &mut self,
112        arbos_version: u64,
113        address: Address,
114        gas_left: Gas,
115    ) -> eyre::Result<(Vec<u8>, Gas)>;
116
117    /// Get an account's code hash. Returns hash and access cost.
118    fn account_codehash(&mut self, address: Address) -> eyre::Result<(B256, Gas)>;
119
120    /// Determine cost of allocating additional WASM pages.
121    fn add_pages(&mut self, pages: u16) -> eyre::Result<Gas>;
122
123    /// Capture tracing information for host I/O calls.
124    fn capture_hostio(
125        &mut self,
126        name: &str,
127        args: &[u8],
128        outs: &[u8],
129        start_ink: Ink,
130        end_ink: Ink,
131    );
132}
arb_stylus/evm_api.rs

arb_stylus/
evm_api.rs
