Crate sp_api

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.