Crate jam_pvm_common

The main JAM PVM API for creating authorizers and services on JAM. This includes a trait-based invocation entry-point API as well as host-calls functions and types for working with them.

In order to create a PVM executable containing a JAM service or authorizer, you must implement the Service or Authorizer in some type and then pass your type into the declare_service! or declare_authorizer! macro, respectively. This will generate the necessary entry-points for the PVM to call into your implementation.

Example Service

extern crate alloc;
use alloc::vec::Vec;
use jam_pvm_common::{declare_service, Service, accumulate::set_storage};
use jam_types::*;

struct MyService;
declare_service!(MyService);

impl Service for MyService {
    fn refine(
        _id: ServiceId,
        payload: WorkPayload,
        _package_hash: WorkPackageHash,
        _context: RefineContext,
        _auth_code_hash: CodeHash,
    ) -> WorkOutput {
        [&b"Hello "[..], payload.take().as_slice()].concat().into()
    }
    fn accumulate(_slot: Slot, _id: ServiceId, items: Vec<AccumulateItem>) -> Option<Hash> {
        for item in items.into_iter() {
            if let Ok(data) = item.result {
                set_storage(item.package.as_slice(), &data).expect("not enough balance?!");
            }
        }
        None
    }
    fn on_transfer(_slot: Slot, _id: ServiceId, _items: Vec<TransferRecord>) {}
}

Host-calls

The host-calls available to a service or authorizer are split into four modules:

• is_authorized for authorizers, to be called from the Authorizer::is_authorized function.
• refine for services, to be called from the Service::refine function.
• accumulate for services, to be called from the Service::accumulate function.
• on_transfer for services, to be called from the Service::on_transfer function.

Each module contains a set of functions that can be called from the respective entry-point function. These functions are used to interact with the PVM and the blockchain state.

Logging

Five logging macros are provided similar to those of the log crate, debug, info, warn, error, and trace. These macros are used with the non-standard PolkaJam log host-call and the format macro. The host environment is responsible for forwarding these logs to the appropriate destination.

Features

• authorizer: Enables the authorizer API.
• service: Enables the service API.
• logging: Enables the logging service; without the logging macros will evaluate any operands but otherwise have no effect.

Modules

accumulate

Host-call APIs available for the Service::accumulate entry-point.

is_authorized

Host-call APIs available for the Authorizer::is_authorized entry-point.

on_transfer

Host-call APIs available for the Service::on_transfer entry-point.

refine

Host-call APIs available for the Service::refine entry-point.

Macros

debug

Log a message with the debug level. Regular formatting may be used.

declare_authorizer

Declare that this crate is a JAM authorizer characterized by $auth_impl and create necessary entry points.

declare_service

Declare that this crate is a JAM service characterized by $service_impl and create necessary entry points.

error

Log a message with the error level. Regular formatting may be used.

info

Log a message with the info level. Regular formatting may be used.

trace

Log a message with the trace level. Regular formatting may be used.

warn

Log a message with the warn level. Regular formatting may be used.

Enums

ApiError

Error type for host-calls.

InvokeOutcome

The successful result of inner PVM invocations.

Traits

Authorizer

The invocation trait for a JAM authorizer.

Service

The invocation trait for a JAM service.

Type Aliases

ApiResult

Result type for host-calls, parameterized by the type of the successful result.

InvokeResult

The result of the crate::refine::invoke host-call.