pezkuwichain
540661e02e
- Fix vendor/zombienet-sdk deprecated method doc links - Fix vendor/subxt doc links (eth::PublicKey, Client) - Fix vendor/ss58-registry TokenRegistry doc link - Fix pezpallet-presale event comment causing doc parse error - Fix pezframe-support broken Config trait link - Rebrand pezpallet-revive README with correct crate names and URLs
120 lines
6.5 KiB
Markdown
120 lines
6.5 KiB
Markdown
# Revive Pezpallet
|
|
|
|
This is an **experimental** module that provides functionality for the runtime to deploy and execute PolkaVM
|
|
smart-contracts. It is a heavily modified `pezpallet_contracts` fork.
|
|
|
|
## Overview
|
|
|
|
This module extends accounts based on the [`pezframe_support::traits::fungible`] traits to have smart-contract
|
|
functionality. It can be used with other modules that implement accounts based on [`pezframe_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`](https://docs.pezkuwichain.io/bizinikiwi/master/pezsp_weights/struct.Weight.html) 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 pezpallet 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:
|
|
|
|
```text
|
|
Total Weight = fixed_part +
|
|
Σ(per_tx_part(payload_i)) +
|
|
Σ(per_event_part(data_len_j))
|
|
```
|
|
|
|
**High-Level Weight API (`OnFinalizeBlockParts` trait):**
|
|
The pezpallet 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](https://docs.pezkuwichain.io/sdk/master/pezpallet_revive/pezpallet/dispatchables/index.html).
|
|
|
|
## 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`](https://github.com/pezkuwichain/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:
|
|
|
|
```bash
|
|
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 pezpallet 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`](src/vm/runtime.rs)
|
|
one need to set `pezpallet_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
|