pezkuwichain/pezkuwi-subxt
1
0
Fork 0
mirror of https://github.com/pezkuwichain/pezkuwi-subxt.git synced 2026-04-26 18:07:58 +00:00
Code Issues Packages Projects Releases Wiki Activity

Runtime API versioning (#11779)

Browse Source 
* Runtime API versioning

Related to issue #11577

Add support for multiple versions of a Runtime API. The purpose is to
have one main version of the API, which is considered stable and
multiple unstable (aka staging) ones.

How it works
===========
Some methods of the API trait can be tagged with `#[api_version(N)]`
attribute where N is version number bigger than the main one. Let's call
them **staging methods** for brevity.

The implementor of the API decides which version to implement.

Example (from https://github.com/paritytech/substrate/issues/11577#issuecomment-1145347025):

```
decl_runtime_apis! {
    #{api_version(10)]
    trait Test {
         fn something() -> Vec<u8>;
         #[api_version(11)]
         fn new_cool_function() -> u32;
    }
}
```

```
impl_runtime_apis! {
    #[api_version(11)]
    impl Test for Runtime {
         fn something() -> Vec<u8> { vec![1, 2, 3] }

         fn new_cool_function() -> u32 {
             10
         }
    }
}
```

Version safety checks (currently not implemented)
=================================================
By default in the API trait all staging methods has got default
implementation calling `unimplemented!()`. This is a problem because if
the developer wants to implement version 11 in the example above and
forgets to add `fn new_cool_function()` in `impl_runtime_apis!` the
runtime will crash when the function is executed.

Ideally a compilation error should be generated in such cases.

TODOs
=====

Things not working well at the moment:
[ ] Version safety check
[ ] Integration tests of `primitives/api` are messed up a bit. More
specifically `primitives/api/test/tests/decl_and_impl.rs`
[ ] Integration test covering the new functionality.
[ ] Some duplicated code

* Update primitives/api/proc-macro/src/impl_runtime_apis.rs

Code review feedback and formatting

Co-authored-by: asynchronous rob <rphmeier@gmail.com>

* Code review feedback

Applying suggestions from @bkchr

* fmt

* Apply suggestions from code review

Co-authored-by: Bastian Köcher <bkchr@users.noreply.github.com>

* Code review feedback

* dummy trait -> versioned trait

* Implement only versioned traits (not compiling)

* Remove native API calls (still not compiling)

* fmt

* Fix compilation

* Comments

* Remove unused code

* Remove native runtime tests

* Remove unused code

* Fix UI tests

* Code review feedback

* Code review feedback

* attribute_names -> common

* Rework `append_api_version`

* Code review feedback

* Apply suggestions from code review

Co-authored-by: Bastian Köcher <bkchr@users.noreply.github.com>

* Code review feedback

* Code review feedback

* Code review feedback

* Use type alias for the default trait - doesn't compile

* Fixes

* Better error for `method_api_ver < trait_api_version`

* fmt

* Rework how we call runtime functions

* Update UI tests

* Fix warnings

* Fix doctests

* Apply suggestions from code review

Co-authored-by: Bastian Köcher <bkchr@users.noreply.github.com>

* Apply suggestions from code review

Co-authored-by: Bastian Köcher <bkchr@users.noreply.github.com>

* Fix formatting and small compilation errors

* Update primitives/api/proc-macro/src/impl_runtime_apis.rs

Co-authored-by: Bastian Köcher <bkchr@users.noreply.github.com>

Co-authored-by: asynchronous rob <rphmeier@gmail.com>
Co-authored-by: Bastian Köcher <bkchr@users.noreply.github.com>
Co-authored-by: Bastian Köcher <info@kchr.de>
This commit is contained in:
Tsvetomir Dimitrov
2022-08-13 14:56:40 +03:00
committed by GitHub
parent 8e927daa77
commit 2bff2f84e3
32 changed files with 944 additions and 862 deletions
Download Patch File Download Diff File Expand all files Collapse all files
substrate/primitives/api/src/lib.rs
+73 -9
View File
@@ -78,12 +78,12 @@ pub use hash_db::Hasher;
#[doc(hidden)]
#[cfg(not(feature = "std"))]
pub use sp_core::to_substrate_wasm_fn_return_value;
#[doc(hidden)]
#[cfg(feature = "std")]
pub use sp_core::NativeOrEncoded;
use sp_core::OpaqueMetadata;
#[doc(hidden)]
pub use sp_core::{offchain, ExecutionContext};
#[doc(hidden)]
#[cfg(feature = "std")]
pub use sp_core::{NativeOrEncoded, NeverNativeValue};
#[cfg(feature = "std")]
pub use sp_runtime::StateVersion;
#[doc(hidden)]
@@ -187,6 +187,56 @@ pub const MAX_EXTRINSIC_DEPTH: u32 = 256;
/// 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.
///
/// # Declaring multiple api versions
///
/// Optionally multiple versions of the same api can be declared. This is useful for
/// development purposes. For example you want to have a testing version of the api which is
/// available only on a testnet. You can define one stable and one development version. This
/// can be done like this:
/// ```rust
/// sp_api::decl_runtime_apis! {
/// /// Declare the api trait.
/// #[api_version(2)]
/// pub trait Balance {
/// /// Get the balance.
/// fn get_balance() -> u64;
/// /// Set the balance.
/// fn set_balance(val: u64);
/// /// Transfer the balance to another user id
/// #[api_version(3)]
/// fn transfer_balance(uid: u64);
/// }
/// }
///
/// # fn main() {}
/// ```
/// The example above defines two api versions - 2 and 3. Version 2 contains `get_balance` and
/// `set_balance`. Version 3 additionally contains `transfer_balance`, which is not available
/// in version 2. Version 2 in this case is considered the default/base version of the api.
/// More than two versions can be defined this way. For example:
/// ```rust
/// sp_api::decl_runtime_apis! {
/// /// Declare the api trait.
/// #[api_version(2)]
/// pub trait Balance {
/// /// Get the balance.
/// fn get_balance() -> u64;
/// /// Set the balance.
/// fn set_balance(val: u64);
/// /// Transfer the balance to another user id
/// #[api_version(3)]
/// fn transfer_balance(uid: u64);
/// /// Clears the balance
/// #[api_version(4)]
/// fn clear_balance();
/// }
/// }
///
/// # fn main() {}
/// ```
/// Note that the latest version (4 in our example above) always contains all methods from all
/// the versions before.
pub use sp_api_proc_macro::decl_runtime_apis;
/// Tags given trait implementations as runtime apis.
@@ -276,6 +326,22 @@ pub use sp_api_proc_macro::decl_runtime_apis;
///
/// # fn main() {}
/// ```
///
/// # Implementing specific api version
///
/// If `decl_runtime_apis!` declares multiple versions for an api `impl_runtime_apis!`
/// should specify which version it implements by adding `api_version` attribute to the
/// `impl` block. If omitted - the base/default version is implemented. Here is an example:
/// ```ignore
/// sp_api::impl_runtime_apis! {
/// #[api_version(3)]
/// impl self::Balance<Block> for Runtime {
/// // implementation
/// }
/// }
/// ```
/// In this case `Balance` api version 3 is being implemented for `Runtime`. The `impl` block
/// must contain all methods declared in version 3 and below.
pub use sp_api_proc_macro::impl_runtime_apis;
/// Mocks given trait implementations as runtime apis.
@@ -341,15 +407,13 @@ pub use sp_api_proc_macro::impl_runtime_apis;
/// using the `advanced` attribute, the macro expects that the first parameter of the function
/// is this `at` parameter. Besides that the macro also doesn't do the automatic return value
/// rewrite, which means that full return value must be specified. The full return value is
/// constructed like [`Result`]`<`[`NativeOrEncoded`](sp_api::NativeOrEncoded)`<ReturnValue>,
/// Error>` while `ReturnValue` being the return value that is specified in the trait
/// declaration.
/// constructed like [`Result`]`<<ReturnValue>, Error>` while `ReturnValue` being the return
/// value that is specified in the trait declaration.
///
/// ## Example
/// ```rust
/// # use sp_runtime::{traits::Block as BlockT, generic::BlockId};
/// # use sp_test_primitives::Block;
/// # use sp_core::NativeOrEncoded;
/// # use codec;
/// #
/// # sp_api::decl_runtime_apis! {
@@ -368,13 +432,13 @@ pub use sp_api_proc_macro::impl_runtime_apis;
/// sp_api::mock_impl_runtime_apis! {
/// impl Balance<Block> for MockApi {
/// #[advanced]
/// fn get_balance(&self, at: &BlockId<Block>) -> Result<NativeOrEncoded<u64>, sp_api::ApiError> {
/// fn get_balance(&self, at: &BlockId<Block>) -> Result<u64, sp_api::ApiError> {
/// println!("Being called at: {}", at);
///
/// Ok(self.balance.into())
/// }
/// #[advanced]
/// fn set_balance(at: &BlockId<Block>, val: u64) -> Result<NativeOrEncoded<()>, sp_api::ApiError> {
/// fn set_balance(at: &BlockId<Block>, val: u64) -> Result<(), sp_api::ApiError> {
/// if let BlockId::Number(1) = at {
/// println!("Being called to set balance to: {}", val);
/// }