pallet_revive_uapi/host.rs
1// Copyright (C) Parity Technologies (UK) Ltd.
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7// http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14use crate::{CallFlags, Result, ReturnFlags, StorageFlags};
15
16#[cfg(target_arch = "riscv64")]
17mod riscv64;
18
19/// Implements [`HostFn`] when compiled on supported architectures (RISC-V).
20pub enum HostFnImpl {}
21
22/// Defines all the host apis available to contracts.
23pub trait HostFn: private::Sealed {
24 /// Stores the address of the current contract into the supplied buffer.
25 ///
26 /// # Parameters
27 ///
28 /// - `output`: A reference to the output data buffer to write the address.
29 fn address(output: &mut [u8; 20]);
30
31 /// Get the contract immutable data.
32 ///
33 /// Traps if:
34 /// - Called from within the deploy export.
35 /// - Called by contracts that didn't set immutable data by calling `set_immutable_data` during
36 /// their constructor execution.
37 ///
38 /// # Parameters
39 /// - `output`: A reference to the output buffer to write the immutable bytes.
40 fn get_immutable_data(output: &mut &mut [u8]);
41
42 /// Set the contract immutable data.
43 ///
44 /// It is only valid to set non-empty immutable data in the constructor once.
45 ///
46 /// Traps if:
47 /// - Called from within the call export.
48 /// - Called more than once.
49 /// - The provided data was empty.
50 ///
51 /// # Parameters
52 /// - `data`: A reference to the data to be stored as immutable bytes.
53 fn set_immutable_data(data: &[u8]);
54
55 /// Stores the **reducible** balance of the current account into the supplied buffer.
56 ///
57 /// # Parameters
58 ///
59 /// - `output`: A reference to the output data buffer to write the balance.
60 fn balance(output: &mut [u8; 32]);
61
62 /// Stores the **reducible** balance of the supplied address into the supplied buffer.
63 ///
64 /// # Parameters
65 ///
66 /// - `addr`: The target address of which to retreive the free balance.
67 /// - `output`: A reference to the output data buffer to write the balance.
68 fn balance_of(addr: &[u8; 20], output: &mut [u8; 32]);
69
70 /// Returns the [EIP-155](https://eips.ethereum.org/EIPS/eip-155) chain ID.
71 fn chain_id(output: &mut [u8; 32]);
72
73 /// Returns the price per ref_time, akin to the EVM
74 /// [GASPRICE](https://www.evm.codes/?fork=cancun#3a) opcode.
75 fn gas_price() -> u64;
76
77 /// Returns the base fee, akin to the EVM
78 /// [BASEFEE](https://www.evm.codes/?fork=cancun#48) opcode.
79 fn base_fee(output: &mut [u8; 32]);
80
81 /// Returns the call data size.
82 fn call_data_size() -> u64;
83
84 /// Call (possibly transferring some amount of funds) into the specified account.
85 ///
86 /// # Parameters
87 ///
88 /// - `flags`: See [`CallFlags`] for a documentation of the supported flags.
89 /// - `callee`: The address of the callee. Should be decodable as an `T::AccountId`. Traps
90 /// otherwise.
91 /// - `ref_time_limit`: how much *ref_time* Weight to devote to the execution, capped at the
92 /// callee's share under the EIP-150 63/64 rule.
93 /// - `proof_size_limit`: how much *proof_size* Weight to devote to the execution, capped at the
94 /// callee's share under the EIP-150 63/64 rule.
95 /// - `deposit`: The storage deposit limit for the call. The callee gets the smaller of this
96 /// limit and 63/64 of the storage deposit the caller has left.
97 /// - `value`: The value to transfer into the contract.
98 /// - `input`: The input data buffer used to call the contract.
99 /// - `output`: A reference to the output data buffer to write the call output buffer. If `None`
100 /// is provided then the output buffer is not copied.
101 ///
102 /// # Errors
103 ///
104 /// An error means that the call wasn't successful output buffer is returned unless
105 /// stated otherwise.
106 ///
107 /// - [CalleeReverted][`crate::ReturnErrorCode::CalleeReverted]: Output buffer is returned.
108 /// - [CalleeTrapped][`crate::ReturnErrorCode::CalleeTrapped]
109 /// - [TransferFailed][`crate::ReturnErrorCode::TransferFailed]
110 /// - [OutOfResources][`crate::ReturnErrorCode::OutOfResources]
111 fn call(
112 flags: CallFlags,
113 callee: &[u8; 20],
114 ref_time_limit: u64,
115 proof_size_limit: u64,
116 deposit: &[u8; 32],
117 value: &[u8; 32],
118 input_data: &[u8],
119 output: Option<&mut &mut [u8]>,
120 ) -> Result;
121
122 /// Same as [HostFn::call] but receives the one-dimensional EVM gas argument.
123 ///
124 /// Adds the EVM gas stipend for non-zero value calls.
125 ///
126 /// If gas is `u64::MAX`, the call sets no gas limit of its own.
127 fn call_evm(
128 flags: CallFlags,
129 callee: &[u8; 20],
130 gas: u64,
131 value: &[u8; 32],
132 input_data: &[u8],
133 output: Option<&mut &mut [u8]>,
134 ) -> Result;
135
136 /// Stores the address of the caller into the supplied buffer.
137 ///
138 /// If this is a top-level call (i.e. initiated by an extrinsic) the origin address of the
139 /// extrinsic will be returned. Otherwise, if this call is initiated by another contract then
140 /// the address of the contract will be returned.
141 ///
142 /// If there is no address associated with the caller (e.g. because the caller is root) then
143 /// it traps with `BadOrigin`.
144 ///
145 /// # Parameters
146 ///
147 /// - `output`: A reference to the output data buffer to write the caller address.
148 fn caller(output: &mut [u8; 20]);
149
150 /// Stores the origin address (initator of the call stack) into the supplied buffer.
151 ///
152 /// If there is no address associated with the origin (e.g. because the origin is root) then
153 /// it traps with `BadOrigin`. This can only happen through on-chain governance actions or
154 /// customized runtimes.
155 ///
156 /// # Parameters
157 ///
158 /// - `output`: A reference to the output data buffer to write the origin's address.
159 fn origin(output: &mut [u8; 20]);
160
161 /// Retrieve the code hash for a specified contract address.
162 ///
163 /// # Parameters
164 ///
165 /// - `addr`: The address of the contract.
166 /// - `output`: A reference to the output data buffer to write the code hash.
167 ///
168 /// # Note
169 ///
170 /// If `addr` is not a contract but the account exists then the hash of empty data
171 /// `0xc5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470` is written,
172 /// otherwise `zero`.
173 fn code_hash(addr: &[u8; 20], output: &mut [u8; 32]);
174
175 /// Returns the code size for a specified contract address.
176 ///
177 /// # Parameters
178 ///
179 /// - `addr`: The address of the contract.
180 ///
181 /// # Note
182 ///
183 /// If `addr` is not a contract the `output` will be zero.
184 fn code_size(addr: &[u8; 20]) -> u64;
185
186 /// Execute code in the context (storage, caller, value) of the current contract.
187 ///
188 /// Reentrancy protection is always disabled since the callee is allowed
189 /// to modify the callers storage. This makes going through a reentrancy attack
190 /// unnecessary for the callee when it wants to exploit the caller.
191 ///
192 /// # Parameters
193 ///
194 /// - `flags`: See [`CallFlags`] for a documentation of the supported flags.
195 /// - `address`: The address of the code to be executed. Should be decodable as an
196 /// `T::AccountId`. Traps otherwise.
197 /// - `ref_time_limit`: how much *ref_time* Weight to devote to the execution, capped at the
198 /// callee's share under the EIP-150 63/64 rule.
199 /// - `proof_size_limit`: how much *proof_size* Weight to devote to the execution, capped at the
200 /// callee's share under the EIP-150 63/64 rule.
201 /// - `deposit_limit`: The storage deposit limit for the delegate call. The call gets the
202 /// smaller of this limit and 63/64 of the storage deposit the caller has left.
203 /// - `input`: The input data buffer used to call the contract.
204 /// - `output`: A reference to the output data buffer to write the call output buffer. If `None`
205 /// is provided then the output buffer is not copied.
206 ///
207 /// # Errors
208 ///
209 /// An error means that the call wasn't successful and no output buffer is returned unless
210 /// stated otherwise.
211 ///
212 /// - [CalleeReverted][`crate::ReturnErrorCode::CalleeReverted]: Output buffer is returned.
213 /// - [CalleeTrapped][`crate::ReturnErrorCode::CalleeTrapped]
214 /// - [OutOfResources][`crate::ReturnErrorCode::OutOfResources]
215 fn delegate_call(
216 flags: CallFlags,
217 address: &[u8; 20],
218 ref_time_limit: u64,
219 proof_size_limit: u64,
220 deposit_limit: &[u8; 32],
221 input_data: &[u8],
222 output: Option<&mut &mut [u8]>,
223 ) -> Result;
224
225 /// Same as [HostFn::delegate_call] but receives the one-dimensional EVM gas argument.
226 ///
227 /// If gas is `u64::MAX`, the call sets no gas limit of its own.
228 fn delegate_call_evm(
229 flags: CallFlags,
230 address: &[u8; 20],
231 gas: u64,
232 input_data: &[u8],
233 output: Option<&mut &mut [u8]>,
234 ) -> Result;
235
236 /// Deposit a contract event with the data buffer and optional list of topics.
237 ///
238 /// # Parameters
239 ///
240 /// - `topics`: At most 4 topics (`NUM_EVENT_TOPICS`).
241 /// - `data`: At most 64 KiB (`EVENT_BYTES`).
242 ///
243 /// # Traps
244 ///
245 /// Fails the calling frame if either bound is exceeded. Inside an Ethereum transaction
246 /// (`eth_transact`, `eth_substrate_call` and their dry runs) it also fails the frame if the
247 /// event would take the transaction's receipt logs past 2 MiB (`MAX_RECEIPT_LOGS_BYTES`). That
248 /// depends on the logs the transaction already kept, from any contract or mirrored by the
249 /// runtime, not only on this call's arguments. The caller can handle the failure. The receipt
250 /// limit does not apply outside an Ethereum transaction, such as under `Revive::call`.
251 fn deposit_event(topics: &[[u8; 32]], data: &[u8]);
252
253 /// Retrieve the value under the given key from storage.
254 ///
255 /// The key length must not exceed the maximum defined by the `pallet-revive` parameter.
256 ///
257 /// # Parameters
258 /// - `key`: The storage key.
259 /// - `output`: A reference to the output data buffer to write the storage entry.
260 ///
261 /// # Errors
262 ///
263 /// [KeyNotFound][`crate::ReturnErrorCode::KeyNotFound]
264 fn get_storage(flags: StorageFlags, key: &[u8], output: &mut &mut [u8]) -> Result;
265
266 /// Computes the keccak_256 32-bit hash on the given input buffer.
267 ///
268 /// - The `input` and `output` buffer may overlap.
269 /// - The output buffer is expected to hold at least 32 bits.
270 /// - It is the callers responsibility to provide an output buffer that is large enough to hold
271 /// the expected amount of bytes returned by the hash function.
272 ///
273 /// # Parameters
274 ///
275 /// - `input`: The input data buffer.
276 /// - `output`: The output buffer to write the hash result to.
277 fn hash_keccak_256(input: &[u8], output: &mut [u8; 32]);
278
279 /// Stores the input data passed by the caller into the supplied `output` buffer,
280 /// starting from the given input data `offset`.
281 ///
282 /// The `output` buffer is guaranteed to always be fully populated:
283 /// - If the call data (starting from the given `offset`) is larger than the `output` buffer,
284 /// only what fits into the `output` buffer is written.
285 /// - If the `output` buffer size exceeds the call data size (starting from `offset`), remaining
286 /// bytes in the `output` buffer are zeroed out.
287 /// - If the provided call data `offset` is out-of-bounds, the whole `output` buffer is zeroed
288 /// out.
289 ///
290 /// # Note
291 ///
292 /// This function traps if:
293 /// - the input was previously forwarded by a [`call()`][`Self::call()`].
294 /// - the `output` buffer is located in an PolkaVM invalid memory range.
295 ///
296 /// # Parameters
297 ///
298 /// - `output`: A reference to the output data buffer to write the call data.
299 /// - `offset`: The offset index into the call data from where to start copying.
300 fn call_data_copy(output: &mut [u8], offset: u32);
301
302 /// Stores the U256 value at given `offset` from the input passed by the caller
303 /// into the supplied buffer.
304 ///
305 /// # Note
306 /// - If `offset` is out of bounds, a value of zero will be returned.
307 /// - If `offset` is in bounds but there is not enough call data, the available data
308 /// is right-padded in order to fill a whole U256 value.
309 /// - The data written to `output` is a little endian U256 integer value.
310 ///
311 /// # Parameters
312 ///
313 /// - `output`: A reference to the fixed output data buffer to write the value.
314 /// - `offset`: The offset (index) into the call data.
315 fn call_data_load(output: &mut [u8; 32], offset: u32);
316
317 /// Instantiate a contract with the specified code hash.
318 ///
319 /// This function creates an account and executes the constructor defined in the code specified
320 /// by the code hash.
321 ///
322 /// # Parameters
323 ///
324 /// - `ref_time_limit`: how much *ref_time* Weight to devote to the execution, capped at the
325 /// callee's share under the EIP-150 63/64 rule.
326 /// - `proof_size_limit`: how much *proof_size* Weight to devote to the execution, capped at the
327 /// callee's share under the EIP-150 63/64 rule.
328 /// - `deposit`: The storage deposit limit for instantiation. The instantiation gets the smaller
329 /// of this limit and 63/64 of the storage deposit the caller has left.
330 /// - `value`: The value to transfer into the contract.
331 /// - `input`: The code hash and constructor input data buffer. The first 32 bytes are the code
332 /// hash of the code to be instantiated. The remaining bytes are the constructor call data.
333 /// - `address`: A reference to the address buffer to write the address of the contract. If
334 /// `None` is provided then the output buffer is not copied.
335 /// - `output`: A reference to the return value buffer to write the constructor output buffer.
336 /// If `None` is provided then the output buffer is not copied.
337 /// - `salt`: The salt bytes to use for this instantiation.
338 ///
339 /// # Errors
340 ///
341 /// Please consult the [ReturnErrorCode][`crate::ReturnErrorCode`] enum declaration for more
342 /// information on those errors. Here we only note things specific to this function.
343 ///
344 /// An error means that the account wasn't created and no address or output buffer
345 /// is returned unless stated otherwise.
346 ///
347 /// - [CalleeReverted][`crate::ReturnErrorCode::CalleeReverted]: Output buffer is returned.
348 /// - [CalleeTrapped][`crate::ReturnErrorCode::CalleeTrapped]
349 /// - [TransferFailed][`crate::ReturnErrorCode::TransferFailed]
350 /// - [OutOfResources][`crate::ReturnErrorCode::OutOfResources]
351 fn instantiate(
352 ref_time_limit: u64,
353 proof_size_limit: u64,
354 deposit: &[u8; 32],
355 value: &[u8; 32],
356 input: &[u8],
357 address: Option<&mut [u8; 20]>,
358 output: Option<&mut &mut [u8]>,
359 salt: Option<&[u8; 32]>,
360 ) -> Result;
361
362 /// Load the latest block timestamp in seconds into the supplied buffer
363 ///
364 /// # Parameters
365 ///
366 /// - `output`: A reference to the output data buffer to write the timestamp.
367 fn now(output: &mut [u8; 32]);
368
369 /// Returns the block ref_time limit.
370 fn gas_limit() -> u64;
371
372 /// Cease contract execution and save a data buffer as a result of the execution.
373 ///
374 /// This function never returns as it stops execution of the caller.
375 /// This is the only way to return a data buffer to the caller. Returning from
376 /// execution without calling this function is equivalent to calling:
377 /// ```nocompile
378 /// return_value(ReturnFlags::empty(), &[])
379 /// ```
380 ///
381 /// Using an unnamed non empty `ReturnFlags` triggers a trap.
382 ///
383 /// # Parameters
384 ///
385 /// - `flags`: Flag used to signal special return conditions to the supervisor. See
386 /// [`ReturnFlags`] for a documentation of the supported flags.
387 /// - `return_value`: The return value buffer.
388 fn return_value(flags: ReturnFlags, return_value: &[u8]) -> !;
389
390 /// Set the value at the given key in the contract storage.
391 ///
392 /// The key and value lengths must not exceed the maximums defined by the `pallet-revive`
393 /// parameters.
394 ///
395 /// # Parameters
396 ///
397 /// - `key`: The storage key.
398 /// - `encoded_value`: The storage value.
399 ///
400 /// # Return
401 ///
402 /// Returns the size of the pre-existing value at the specified key if any.
403 fn set_storage(flags: StorageFlags, key: &[u8], value: &[u8]) -> Option<u32>;
404
405 /// Sets the storage entry for a fixed 256‑bit key with a fixed 256‑bit value.
406 ///
407 /// If the provided 32‑byte value is all zeros then the key is cleared (i.e. deleted),
408 /// mimicking Ethereum’s SSTORE behavior.
409 ///
410 /// # Parameters
411 /// - `key`: The fixed 256‑bit storage key (32 bytes).
412 /// - `value`: The fixed 256‑bit storage value (32 bytes).
413 ///
414 /// # Return
415 /// Returns the size (in bytes) of the pre‑existing value at the specified key, if any.
416 fn set_storage_or_clear(flags: StorageFlags, key: &[u8; 32], value: &[u8; 32]) -> Option<u32>;
417
418 /// Retrieves the storage entry for a fixed 256‑bit key.
419 ///
420 /// If the key does not exist, the output buffer is filled with 32 zero bytes.
421 ///
422 /// # Parameters
423 /// - `key`: The fixed 256‑bit storage key (32 bytes).
424 /// - `output`: A mutable output buffer (32 bytes) where the storage entry is written.
425 fn get_storage_or_zero(flags: StorageFlags, key: &[u8; 32], output: &mut [u8; 32]);
426
427 /// Stores the value transferred along with this call/instantiate into the supplied buffer.
428 ///
429 /// # Parameters
430 ///
431 /// - `output`: A reference to the output data buffer to write the transferred value.
432 fn value_transferred(output: &mut [u8; 32]);
433
434 /// Returns the size of the returned data of the last contract call or instantiation.
435 fn return_data_size() -> u64;
436
437 /// Stores the returned data of the last contract call or contract instantiation.
438 ///
439 /// # Parameters
440 /// - `output`: A reference to the output buffer to write the data.
441 /// - `offset`: Byte offset into the returned data
442 fn return_data_copy(output: &mut &mut [u8], offset: u32);
443
444 /// Returns the amount of ethereum gas left.
445 fn gas_left() -> u64;
446
447 /// Stores the current block author of into the supplied buffer.
448 ///
449 /// # Parameters
450 ///
451 /// - `output`: A reference to the output data buffer to write the block author.
452 fn block_author(output: &mut [u8; 20]);
453
454 /// Stores the current block number of the current contract into the supplied buffer.
455 ///
456 /// # Parameters
457 ///
458 /// - `output`: A reference to the output data buffer to write the block number.
459 fn block_number(output: &mut [u8; 32]);
460
461 /// Stores the block hash of the given block number into the supplied buffer.
462 ///
463 /// # Parameters
464 ///
465 /// - `block_number`: A reference to the block number buffer.
466 /// - `output`: A reference to the output data buffer to write the block number.
467 fn block_hash(block_number: &[u8; 32], output: &mut [u8; 32]);
468
469 /// Reverts the execution and cedes all supplied gas,
470 /// akin to the `INVALID` EVM opcode.
471 fn consume_all_gas() -> !;
472
473 /// Remove the calling account and transfer remaining **free** balance.
474 ///
475 /// This function never returns. Either the termination was successful and the
476 /// execution of the destroyed contract is halted. Or it failed during the termination
477 /// which is considered fatal and results in a trap + rollback.
478 ///
479 /// # Parameters
480 ///
481 /// - `beneficiary`: The address of the beneficiary account
482 ///
483 /// # Traps
484 ///
485 /// - The contract is live i.e is already on the call stack.
486 /// - Failed to send the balance to the beneficiary.
487 /// - The deletion queue is full.
488 fn terminate(beneficiary: &[u8; 20]) -> !;
489}
490
491mod private {
492 pub trait Sealed {}
493 impl Sealed for super::HostFnImpl {}
494}