Crate sp_api

Substrate runtime api

The Substrate runtime api is the interface between the node and the runtime. There isn’t a fixed set of runtime apis, instead it is up to the user to declare and implement these runtime apis. The declaration of a runtime api is normally done outside of a runtime, while the implementation of it has to be done in the runtime. We provide the decl_runtime_apis! macro for declaring a runtime api and the impl_runtime_apis! for implementing them. The macro docs provide more information on how to use them and what kind of attributes we support.

It is required that each runtime implements at least the Core runtime api. This runtime api provides all the core functions that Substrate expects from a runtime.

Versioning

Runtime apis support versioning. Each runtime api itself has a version attached. It is also supported to change function signatures or names in a non-breaking way. For more information on versioning check the decl_runtime_apis! macro.

All runtime apis and their versions are returned as part of the RuntimeVersion. This can be used to check which runtime api version is currently provided by the on-chain runtime.

Testing

For testing we provide the mock_impl_runtime_apis! macro that lets you implement a runtime api for a mocked object to use it in tests.

Logging

Substrate supports logging from the runtime in native and in wasm. For that purpose it provides the RuntimeLogger. This runtime logger is automatically enabled for each call into the runtime through the runtime api. As logging introduces extra code that isn’t actually required for the logic of your runtime and also increases the final wasm blob size, it is recommended to disable the logging for on-chain wasm blobs. This can be done by enabling the disable-logging feature of this crate. Be aware that this feature instructs log and tracing to disable logging at compile time by setting the max_level_off feature for these crates. So, you should not enable this feature for a native build as otherwise the node will not output any log messages.

How does it work?

Each runtime api is declared as a trait with functions. When compiled to WASM, each implemented runtime api function is exported as a function with the following naming scheme ${TRAIT_NAME}_${FUNCTION_NAME}. Such a function has the following signature (ptr: *u8, length: u32) -> u64. It takes a pointer to an u8 array and its length as an argument. This u8 array is expected to be the SCALE encoded parameters of the function as defined in the trait. The return value is an u64 that represents length << 32 | pointer of an u8 array. This return value u8 array contains the SCALE encoded return value as defined by the trait function. The macros take care to encode the parameters and to decode the return value.

Macros

_frame_metadata_enabled

_std_disabled

_std_enabled

decl_runtime_apis

Declares given traits as runtime apis.

frame_metadata_enabled

Enable/disable the given code depending on feature = "frame-metadata" being enabled for the crate or not.

impl_runtime_apis

Tags given trait implementations as runtime apis.

mock_impl_runtime_apis

Mocks given trait implementations as runtime apis.

std_disabled

Enable/disable the given code depending on not(feature = "std") being enabled for the crate or not.

std_enabled

Enable/disable the given code depending on feature = "std" being enabled for the crate or not.

Structs

ApiRef

Auxiliary wrapper that holds an api instance and binds it to the given lifetime.

CallApiAtParams

Parameters for CallApiAt::call_api_at.

StorageProof

A proof that some set of key-value pairs are included in the storage trie. The proof contains the storage values so that the partial storage backend can be reconstructed by a verifier that does not already have access to the key-value pairs.

Enums

ApiError

An error describing which API call failed.

CallContext

The context in which a call is done.

TransactionOutcome

Describes on what should happen with a storage transaction.

Constants

MAX_EXTRINSIC_DEPTH

Maximum nesting level for extrinsics.

RUNTIME_API_INFO_SIZE

The number of bytes required to encode a RuntimeApiInfo.

Traits

ApiExt

Extends the runtime api implementation with some common functionality.

CallApiAt

Something that can call into an api at a given block.

ConstructRuntimeApi

Something that can be constructed to a runtime api.

Core

The Core runtime api that every Substrate runtime needs to implement.

Metadata

The Metadata api trait that returns metadata for the runtime.

ProvideRuntimeApi

Something that provides a runtime api.

RuntimeApiInfo

Something that provides information about a runtime api.

Functions

deserialize_runtime_api_info

Deserialize the runtime API info serialized by serialize_runtime_api_info.

init_runtime_logger

Init the RuntimeLogger.

serialize_runtime_api_info

Crude and simple way to serialize the RuntimeApiInfo into a bunch of bytes.

Type Aliases

ProofRecorder

A type that records all accessed trie nodes and generates a proof out of it.

StorageChanges