Macro sp_api::decl_runtime_apis

decl_runtime_apis!() { /* proc-macro */ }

Declares given traits as runtime apis.

The macro will create two declarations, one for using on the client side and one for using on the runtime side. The declaration for the runtime side is hidden in its own module. The client side declaration gets two extra parameters per function, &self and at: &BlockId<Block>. The runtime side declaration will match the given trait declaration. Besides one exception, the macro adds an extra generic parameter Block: BlockT to the client side and the runtime side. This generic parameter is usable by the user.

For implementing these macros you should use the impl_runtime_apis! macro.

Example

sp_api::decl_runtime_apis! {
    /// Declare the api trait.
    pub trait Balance {
        /// Get the balance.
        fn get_balance() -> u64;
        /// Set the balance.
        fn set_balance(val: u64);
    }

    /// You can declare multiple api traits in one macro call.
    /// In one module you can call the macro at maximum one time.
    pub trait BlockBuilder {
        /// The macro adds an explicit `Block: BlockT` generic parameter for you.
        /// You can use this generic parameter as you would defined it manually.
        fn build_block() -> Block;
    }
}

Runtime api trait versioning

To support versioning of the traits, the macro supports the attribute #[api_version(1)]. The attribute supports any u32 as version. By default, each trait is at version 1, if no version is provided. We also support changing the signature of a method. This signature change is highlighted with the #[changed_in(2)] attribute above a method. A method that is tagged with this attribute is callable by the name METHOD_before_version_VERSION. This method will only support calling into wasm, trying to call into native will fail (change the spec version!). Such a method also does not need to be implemented in the runtime. It is required that there exist the "default" of the method without the #[changed_in(_)] attribute, this method will be used to call the current default implementation.

sp_api::decl_runtime_apis! {
    /// Declare the api trait.
    #[api_version(2)]
    pub trait Balance {
        /// Get the balance.
        fn get_balance() -> u64;
        /// Set balance.
        fn set_balance(val: u64);
        /// Set balance, old version.
        ///
        /// Is callable by `set_balance_before_version_2`.
        #[changed_in(2)]
        fn set_balance(val: u16);
        /// In version 2, we added this new function.
        fn increase_balance(val: u64);
    }
}

To check if a given runtime implements a runtime api trait, the RuntimeVersion has the function has_api<A>(). Also the ApiExt provides a function has_api<A>(at: &BlockId) to check if the runtime at the given block id implements the requested runtime api trait.