Crate pallet_revive

Expand description

§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.

§Event-Aware Weight Accounting

The pallet includes event-aware weight accounting for finalize_block() operations through the OnFinalizeBlockParts trait. The weight model uses differential benchmarking to precisely account for the computational cost of processing events during Ethereum block construction:

Total Weight = fixed_part +
               Σ(per_tx_part(payload_i)) +
               Σ(per_event_part(data_len_j))

High-Level Weight API (OnFinalizeBlockParts trait): The pallet exposes these weight calculation methods for runtime use:

Fixed cost: on_finalize_block_fixed() - Base overhead regardless of transaction/event count
Per-transaction cost: on_finalize_block_per_tx(payload_size) - Applied incrementally during each eth_call()
Per-event cost: on_finalize_block_per_event(data_len) - Applied dynamically during each deposit_event()

Underlying Benchmark Functions (WeightInfo trait): These low-level benchmarks measure raw computational costs and are used to derive the high-level weights:

Per-transaction overhead: on_finalize_per_transaction(n) - Measures cost scaling with n transaction count
Per-transaction data: on_finalize_per_transaction_data(d) - Measures cost scaling with d bytes of transaction payload
Per-event overhead: on_finalize_per_event(e) - Measures cost scaling with e event count
Per-event data: on_finalize_per_event_data(d) - Measures cost scaling with d bytes of event data

Weight Derivation Methodology: The high-level API methods use differential calculation to isolate marginal costs from benchmarks:

Per-transaction base: on_finalize_per_transaction(1) - on_finalize_per_transaction(0)
Per-transaction byte: on_finalize_per_transaction_data(1) - on_finalize_per_transaction_data(0)
Per-event base: on_finalize_per_event(1) - on_finalize_per_event(0)
Per-byte of event data: on_finalize_per_event_data(data_len) - on_finalize_per_event_data(0)

This comprehensive weight model ensures that:

Transactions emitting many events are properly weighted based on event count and data size
Resource exhaustion attacks via oversized event data are prevented through proactive weight enforcement
Accurate block packing calculations include all processing costs (bloom filters, RLP encoding, log conversion)
Gas limit enforcement occurs early in eth_call() to prevent block overruns

§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::evm::Block as EthBlock;
pub use crate::evm::DryRunConfig;
pub use crate::evm::ReceiptInfo;
pub use crate::pallet::genesis;
pub use weights::WeightInfo;
pub use codec;
pub use frame_support;
pub use frame_system;
pub use sp_runtime;
pub use crate::pallet::*;

Modules§

evm: Types, and traits to integrate pallet-revive with EVM.
migrations
mock: Helper interfaces and functions, that help with controlling the execution of EVM contracts. It is mostly used to help with the implementation of foundry cheatscodes for forge test integration.
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§

impl_runtime_apis_plus_revive_traits: This macro wraps substrate’s impl_runtime_apis! and implements pallet_revive runtime APIs and other required traits.

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.
ContractBlob: Validated Vm module ready for execution. This data structure is immutable once created and stored.
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.
DebugSettings: Debugging settings that can be configured when DebugEnabled config is true.
DelegateInfo: This structure is used to represent the arguments in a delegate call frame in order to distinguish who delegated the call and where it was delegated to.
DispatchInfo: A bundle of static information collected from the #[pallet::weight] attributes.
EthTransactInfo: The result of the execution of a eth_transact call.
EthTxInfo: Ethereum transaction context for gas conversions.
ExecConfig: Stack wide configuration options.
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.
ReceiptGasInfo: Details needed to reconstruct the receipt info in the RPC layer without losing accuracy.
ResourceMeter: Resource meter tracking weight and storage deposit consumption.
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§

BalanceConversionError: Error encountered while creating a BalanceWithDust from a U256 balance.
BytecodeType
CallResources: Argument passed by a contact to describe the amount of resources allocated to a cross contact call.
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.
EthTransactError: Error type of a eth_transact call.
ExecOrigin: The type of origins supported by the revive pallet.
Key: Combined key type for both fixed and variable sized storage keys.
StorageDeposit: The amount of balance that was either charged or refunded in order to pay for storage.
TransactionLimits: Transaction-wide resource limit configuration.

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.
Executable: A trait that represents something that can be executed.
ReviveApi: The API used to dry-run contract interactions.
SyscallDoc: Documentation of the syscalls (host functions) available to contracts.
Time
WeightToken: This trait represents a token that can be used for charging WeightMeter. There is no other way of charging it.

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.
keccak_256: Do a keccak 256-bit hash and return result.

Type Aliases§

BalanceOf
CodeUploadResult: Result type of a bare_code_upload call.
EthAddress
FrameMeter: The type of resource meter used for an execution frame.
GetStorageResult: Result type of a get_storage call.
MomentOf
SetStorageResult: Result type of a set_storage call.
TransactionMeter: The type of resource meter used at the root level for transactions as a whole.