Crate sp_api

source ·
Expand description

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

  • _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.
  • decl_runtime_apis
    Declares given traits as runtime apis.
  • impl_runtime_apis
    Tags given trait implementations as runtime apis.
  • mock_impl_runtime_apis
    Mocks given trait implementations as runtime apis.

Structs

Enums

  • ApiError
    An error describing which API call failed.

Constants

Traits

  • ApiExt
    Extends the runtime api implementation with some common functionality.
  • CallApiAt
    Something that can call into the 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

Type Definitions