Crate sp_virtualization 

This crate is intended for use by runtime code (e.g. pallet-contracts) to spawn PolkaVM instances and execute calls into them. Its purpose is to add one layer of abstraction so that it works transparently from the actual runtime (via the host functions defined in this crate) but also from tests (which run natively).

The crate exposes the runtime-side forwarder API and the [#[runtime_interface]] declaration plus the VirtManagerBackend trait that backs it. The concrete polkavm-driven backend lives in the sc-virtualization client crate, which registers a VirtManager via VirtManagerExt before dispatching runtime calls.

Please keep in mind that the interface is kept simple because it has to match the interface of the host function so that the abstraction works. It will never expose the whole PolkaVM interface.

⚠️ Unstable API — Do Not Use in Production ⚠️

This crate’s API is unstable and subject to breaking changes without notice.

The virtualization host functions exposed by this crate have not been stabilized and are not available on Polkadot (or any other production relay/parachain) until they are. Using them in a production runtime will cause your runtime to break when the API changes.

This crate should only be used for:

• Local testing and development
• Experimentation on test networks

Do not ship runtimes that depend on this crate to any chain you care about. There is no stability guarantee and no deprecation period — the interface may change at any time.

Re-exports

pub use crate::tests::run as run_tests;

Modules

tests

Shared test driver for the virtualization forwarder API.

Structs

ExecBuffer

Buffer shared between runtime and executor for passing syscall data across the host function boundary.

Execution

A prepared or suspended virtualization execution.

HostFunctions

Aggregate of all host functions exposed by this crate.

Instance

An idle virtualization instance.

InstanceId

Opaque handle to a virtualization instance.

Module

A compiled module handle.

ModuleId

Opaque handle to a compiled module.

SyscallSymbol

A syscall symbol with a maximum length of MAX_SYSCALL_SYMBOL_LEN bytes.

VirtManagerExt

Extension wrapping a VirtManagerBackend so it can be accessed through the externalities by the virtualization host functions.

Enums

CompileStatus

Status returned by the compile_* host functions.

DestroyError

Errors that can be emitted when destroying a virtualization instance.

ExecError

Errors that can be emitted when executing a new virtualization instance.

ExecResult

The result of running a virtualization instance.

ExecStatus

Status returned by the run host function.

InstantiateError

Errors that can be emitted when instantiating a new virtualization instance.

MemoryError

Errors that can be emitted when accessing a virtualization instance’s memory.

ModuleError

Errors that can be emitted when compiling a program into a module.

Constants

LOG_TARGET

The target we use for all logging.

MAX_SYSCALL_SYMBOL_LEN

Maximum length of a syscall symbol in bytes.

Traits

VirtManagerBackend

The host-side operations driven by the virtualization host functions.