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_info: PackageInfo,
        _extrinsics: Vec<Vec<u8>>,
    ) -> 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.