Crate pallet_revive

Revive Pallet

This is an experimental module that provides functionality for the runtime to deploy and execute PolkaVM smart-contracts. It is a heavily modified pallet_contracts fork.

Overview

This module extends accounts based on the [frame_support::traits::fungible] traits to have smart-contract functionality. It can be used with other modules that implement accounts based on [frame_support::traits::fungible]. These “smart-contract accounts” have the ability to instantiate smart-contracts and make calls to other contract and non-contract accounts.

The smart-contract code is stored once, and later retrievable via its code_hash. This means that multiple smart-contracts can be instantiated from the same code, without replicating the code each time.

When a smart-contract is called, its associated code is retrieved via the code hash and gets executed. This call can alter the storage entries of the smart-contract account, instantiate new smart-contracts, or call other smart-contracts.

Finally, when an account is reaped, its associated code and storage of the smart-contract account will also be deleted.

Weight

Senders must specify a Weight limit with every call, as all instructions invoked by the smart-contract require weight. Unused weight is refunded after the call, regardless of the execution outcome.

If the weight limit is reached, then all calls and state changes (including balance transfers) are only reverted at the current call’s contract level. For example, if contract A calls B and B runs out of weight mid-call, then all of B’s calls are reverted. Assuming correct error handling by contract A, A’s other calls and state changes still persist.

One ref_time Weight is defined as one picosecond of execution time on the runtime’s reference machine.

Revert Behaviour

Contract call failures are not cascading. When failures occur in a sub-call, they do not “bubble up”, and the call will only revert at the specific contract level. For example, if contract A calls contract B, and B fails, A can decide how to handle that failure, either proceeding or reverting A’s changes.

Interface

Dispatchable functions

Those are documented in the reference documentation.

Usage

This module executes PolkaVM smart contracts. These can potentially be written in any language that compiles to RISC-V. For now, the only officially supported languages are Solidity (via revive) and Rust (check the fixtures directory for Rust examples).

Host function tracing

For contract authors, it can be a helpful debugging tool to see which host functions are called, with which arguments, and what the result was.

In order to see these messages on the node console, the log level for the runtime::revive::strace target needs to be raised to the trace level.

Example:

cargo run --release -- --dev -lerror,runtime::revive::strace=trace,runtime::revive=debug

Unstable Interfaces

Driven by the desire to have an iterative approach in developing new contract interfaces this pallet contains the concept of an unstable interface. Akin to the rust nightly compiler it allows us to add new interfaces but mark them as unstable so that contract languages can experiment with them and give feedback before we stabilize those.

In order to access interfaces which don’t have a stable #[stable] in runtime.rs one need to set pallet_revive::Config::UnsafeUnstableInterface to ConstU32<true>. It should be obvious that any production runtime should never be compiled with this feature: In addition to be subject to change or removal those interfaces might not have proper weights associated with them and are therefore considered unsafe.

New interfaces are generally added as unstable and might go through several iterations before they are promoted to a stable interface.

License: Apache-2.0

Re-exports

pub use crate::pallet::genesis;

pub use weights::WeightInfo;

pub use codec;

pub use frame_support;

pub use frame_system;

pub use pallet_transaction_payment;

pub use sp_runtime;

pub use crate::pallet::*;

Modules

evm

Types, and traits to integrate pallet-revive with EVM.

migrations

pallet

The pallet module in each FRAME pallet hosts the most important items needed to construct this pallet.

precompiles

Exposes types that can be used to extend pallet_revive with additional functionality.

test_utils

Shared utilities for testing contracts. This is not part of the tests module because it is made public for other crates to use.

tracing

weights

Autogenerated weights for pallet_revive

Macros

as_isize_saturated

Converts a U256 value to a isize, saturating to isize::MAX if the value is too large.

as_u64_saturated

Converts a U256 value to a u64, saturating to MAX if the value is too large.

as_usize_or_fail

Converts a U256 value to a usize, failing the instruction if the value is too large.

as_usize_or_fail_ret

Converts a U256 value to a usize and returns ret, failing the instruction if the value is too large.

as_usize_saturated

Converts a U256 value to a usize, saturating to MAX if the value is too large.

check

Check if the SPEC is enabled, and fail the instruction if it is not.

gas

gas_legacy

Records a gas cost and fails the instruction if it would exceed the available gas.

gas_or_fail_legacy

Same as gas_legacy!, but with gas as an option.

impl_runtime_apis_plus_revive

This macro wraps substrate’s impl_runtime_apis! and implements pallet_revive runtime APIs.

otry

Macro for optional try - returns early if the expression evaluates to None. Similar to the ? operator but for use in instruction implementations.

popn

Pops n values from the stack. Fails the instruction if n values can’t be popped.

popn_top

Pops n values from the stack and returns the top value. Fails the instruction if n values can’t be popped.

push

Pushes a B256 value onto the stack. Fails the instruction if the stack is full.

require_eof

Error if the current call is executing EOF.

require_non_staticcall

Fails the instruction if the current call is static.

resize_memory

Resizes the interpreterreter memory if necessary. Fails the instruction if the memory or gas limit is exceeded.

tri

const Option ?.

Structs

AccountId32Mapper

The mapper to be used if the account id is AccountId32.

AccountInfo

Represents the account information for a contract or an externally owned account (EOA).

BalanceWithDust

A Balance amount along with some “dust” to represent the lowest decimals that can’t be expressed in the native currency

BlockWeights

Block weight limits & base values configuration.

CodeUploadReturnValue

The result of successfully uploading a contract.

ContractInfo

Information for managing an account and its sub trie abstraction. This is the required info to cache for an account.

ContractResult

Result type of a bare_call or bare_instantiate call as well as ContractsApi::call and ContractsApi::instantiate.

DispatchInfo

A bundle of static information collected from the #[pallet::weight] attributes.

EthTransactInfo

The result of the execution of a eth_transact call.

ExecReturnValue

Output of a contract call or instantiation which ran to completion.

H160

Fixed-size uninterpreted hash type with 20 bytes (160 bits) size.

H256

Fixed-size uninterpreted hash type with 32 bytes (256 bits) size.

InstantiateReturnValue

The result of a successful contract instantiation.

TestAccountMapper

An account mapper that can be used for testing u64 account ids.

U256

Little-endian large integer type 256-bit unsigned integer.

Weight

Enums

BumpNonce

Indicates whether the account nonce should be incremented after instantiating a new contract.

Code

Reference to an existing code hash or a new vm module.

CodeRemoved

Indicates whether the code was removed after the last refcount was decremented.

ContractAccessError

The possible errors that can happen querying the storage of a contract.

DepositLimit

EthTransactError

Error type of a eth_transact call.

Key

Combined key type for both fixed and variable sized storage keys.

Origin

The type of origins supported by the revive pallet.

StorageDeposit

The amount of balance that was either charged or refunded in order to pay for storage.

Constants

RUNTIME_PALLETS_ADDR

The address used to call the runtime’s pallets dispatchables

Traits

AddressMapper

Map between the native chain account id T and an Ethereum H160.

ReviveApi

The API used to dry-run contract interactions.

SyscallDoc

Documentation of the syscalls (host functions) available to contracts.

Functions

create1

Determine the address of a contract using CREATE semantics.

create2

Determine the address of a contract using the CREATE2 semantics.

is_eth_derived

Returns true if the passed account id is controlled by an eth key.

Type Aliases

BalanceOf

CodeUploadResult

Result type of a bare_code_upload call.

GetStorageResult

Result type of a get_storage call.

MomentOf