Runtime API versioning (#11779)

* 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>
2026-04-26 11:07:56 +00:00 · 2022-08-13 14:56:40 +03:00
parent 8e927daa77
commit 2bff2f84e3
32 changed files with 944 additions and 862 deletions
@@ -18,7 +18,6 @@
 use sp_api::{
 	decl_runtime_apis, impl_runtime_apis, mock_impl_runtime_apis, ApiError, ApiExt, RuntimeApiInfo,
 };
-use sp_core::NativeOrEncoded;
 use sp_runtime::{
 	generic::BlockId,
 	traits::{Block as BlockT, GetNodeBlockType},
@@ -47,6 +46,15 @@ decl_runtime_apis! {
 		#[changed_in(2)]
 		fn same_name() -> String;
 	}
+
+	#[api_version(2)]
+	pub trait ApiWithMultipleVersions {
+		fn stable_one(data: u64);
+		#[api_version(3)]
+		fn new_one();
+		#[api_version(4)]
+		fn glory_one();
+	}
 }

 impl_runtime_apis! {
@@ -72,6 +80,13 @@ impl_runtime_apis! {
 		fn same_name() {}
 	}

+	#[api_version(3)]
+	impl self::ApiWithMultipleVersions<Block> for Runtime {
+		fn stable_one(_: u64) {}
+
+		fn new_one() {}
+	}
+
 	impl sp_api::Core<Block> for Runtime {
 		fn version() -> sp_version::RuntimeVersion {
 			unimplemented!()
@@ -104,22 +119,12 @@ mock_impl_runtime_apis! {
 		}

 		#[advanced]
-		fn same_name(_: &BlockId<Block>) ->
-			Result<
-				NativeOrEncoded<()>,
-				ApiError
-			>
-		{
+		fn same_name(_: &BlockId<Block>) -> Result<(), ApiError> {
 			Ok(().into())
 		}

 		#[advanced]
-		fn wild_card(at: &BlockId<Block>, _: u32) ->
-			Result<
-				NativeOrEncoded<()>,
-				ApiError
-			>
-		{
+		fn wild_card(at: &BlockId<Block>, _: u32) -> Result<(), ApiError> {
 			if let BlockId::Number(1337) = at {
 				// yeah
 				Ok(().into())
@@ -176,6 +181,9 @@ fn check_runtime_api_info() {
 		&runtime_decl_for_ApiWithCustomVersion::ID,
 	);
 	assert_eq!(<dyn ApiWithCustomVersion::<Block>>::VERSION, 2);
+
+	// The stable version of the API
+	assert_eq!(<dyn ApiWithMultipleVersions::<Block>>::VERSION, 2);
 }

 fn check_runtime_api_versions_contains<T: RuntimeApiInfo + ?Sized>() {
@@ -186,6 +194,9 @@ fn check_runtime_api_versions_contains<T: RuntimeApiInfo + ?Sized>() {
 fn check_runtime_api_versions() {
 	check_runtime_api_versions_contains::<dyn Api<Block>>();
 	check_runtime_api_versions_contains::<dyn ApiWithCustomVersion<Block>>();
+	assert!(RUNTIME_API_VERSIONS
+		.iter()
+		.any(|v| v == &(<dyn ApiWithMultipleVersions<Block>>::ID, 3)));
 	check_runtime_api_versions_contains::<dyn sp_api::Core<Block>>();
 }

@@ -198,7 +209,7 @@ fn mock_runtime_api_has_api() {
 }

 #[test]
-#[should_panic(expected = "Mocked runtime apis don't support calling deprecated api versions")]
+#[should_panic(expected = "Calling deprecated methods is not supported by mocked runtime api.")]
 fn mock_runtime_api_panics_on_calling_old_version() {
 	let mock = MockApi { block: None };