referrerpolicy=no-referrer-when-downgrade

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}