52 releases (32 major breaking)
34.0.0 | Jul 18, 2024 |
---|---|
33.0.0 | Jun 21, 2024 |
32.0.0 | May 23, 2024 |
31.0.0 | Apr 30, 2024 |
2.0.0-alpha.5 | Mar 24, 2020 |
#6 in #done
152,443 downloads per month
Used in 594 crates
(179 directly)
1MB
17K
SLoC
Substrate runtime api
The Substrate runtime api is the crucial interface between the node and the runtime.
Every call that goes into the runtime is done with a runtime api. The runtime apis are not fixed.
Every Substrate user can define its own apis with
decl_runtime_apis
and implement them in
the runtime with impl_runtime_apis
.
Every Substrate runtime needs to implement the Core
runtime api. This api provides the basic
functionality that every runtime needs to export.
Besides the macros and the Core
runtime api, this crates provides the Metadata
runtime
api, the ApiExt
trait, the CallApiAt
trait and the ConstructRuntimeApi
trait.
On a meta level this implies, the client calls the generated API from the client perspective.
License: Apache-2.0
lib.rs
:
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.
Dependencies
~15–28MB
~453K SLoC