Rewrite impl_runtime_apis! and decl_runtime_apis! as proc-macro (#1174)

* Rewrites `impl_runtime_apis!` macro as `proc-macro`

* Adds some documentation

* Require the `impl_runtime_apis` to use a path for accessing the trait

* Make the runtime implement `GetNodeBlockType`

* Moves first chunk of runtime api code into the `impl_runtime_apis` macro

This also renames `ClientWithApi` into `RuntimeApi`.

* Make `impl_runtime_apis` use `runtime` api version automatically

* `decl_runtime_apis` automatically adds `Block: BlockT` as generic parameter

* Remove function generic arguments in block builder api

* Remove some unnused stuff from the `decl_runtime_apis` macro

* Make `InherentData` working again

* Make `impl_runtime_apis!` implement the `RuntimeApi` side as well

* Make it compile again after rebasing with master

* Split `sr-api-macros` into multiple files

* Reimplement `decl_runtime_apis!` as proc_macro

* Use `decl_runtime_apis!` for `Core` as well and improve error reporting

* Adds documentation for `decl_runtime_apis!` and `impl_runtime_apis!`

* Move some code

* Adds compile fail tests

* Adds a test and fixes some bugs

* Make `impl_runtime_apis!` support `_` as parameter name

* Fixes build errors with wasm

* Wasm rebuild after master rebase

* Apply suggestions from code review

Co-Authored-By: bkchr <bkchr@users.noreply.github.com>

* Addresses some grumbles

* Adds test to ensure that method signatures need to match

* New wasm files

substrate/core/sr-api-macros/src/compile_fail_tests.rs

@@ -0,0 +1,408 @@
+// Copyright 2018 Parity Technologies (UK) Ltd.
+// This file is part of Substrate.
+
+// Substrate is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Substrate is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Substrate.  If not, see <http://www.gnu.org/licenses/>.
+
+//! Compile fail tests.
+
+mod declaring_own_block {
+	/*!
+	```compile_fail
+		#[macro_use]
+		extern crate substrate_client;
+		extern crate sr_primitives as runtime_primitives;
+
+		use runtime_primitives::traits::Block as BlockT;
+
+		decl_runtime_apis! {
+			pub trait Api<Block: BlockT> {
+				fn test();
+			}
+		}
+
+		fn main() {}
+	```
+	*/
+}
+
+mod declaring_own_block_with_different_name {
+	/*!
+	```compile_fail
+		#[macro_use]
+		extern crate substrate_client;
+		extern crate sr_primitives as runtime_primitives;
+
+		use runtime_primitives::traits::Block as BlockT;
+
+		decl_runtime_apis! {
+			pub trait Api<B: BlockT> {
+				fn test();
+			}
+		}
+
+		fn main() {}
+	```
+	*/
+}
+
+mod adding_self_parameter {
+	/*!
+	```compile_fail
+		#[macro_use]
+		extern crate substrate_client;
+		extern crate sr_primitives as runtime_primitives;
+
+		decl_runtime_apis! {
+			pub trait Api {
+				fn test(&self);
+			}
+		}
+
+		fn main() {}
+	```
+	*/
+}
+
+mod adding_at_parameter {
+	/*!
+	```compile_fail
+		#[macro_use]
+		extern crate substrate_client;
+		extern crate sr_primitives as runtime_primitives;
+
+		decl_runtime_apis! {
+			pub trait Api {
+				fn test(at: u64);
+			}
+		}
+
+		fn main() {}
+	```
+	*/
+}
+
+mod adding_parameter_with_type_reference {
+	/*!
+	```compile_fail
+		#[macro_use]
+		extern crate substrate_client;
+		extern crate sr_primitives as runtime_primitives;
+
+		decl_runtime_apis! {
+			pub trait Api {
+				fn test(data: &u64);
+			}
+		}
+
+		fn main() {}
+	```
+	*/
+}
+
+mod missing_block_generic_parameter {
+	/*!
+	```compile_fail
+		#[macro_use]
+		extern crate substrate_client;
+		extern crate sr_primitives as runtime_primitives;
+		extern crate substrate_primitives as primitives;
+		#[macro_use]
+		extern crate parity_codec_derive;
+		extern crate serde;
+		extern crate core;
+
+		use primitives::hash::H256;
+		use runtime_primitives::traits::{BlakeTwo256, GetNodeBlockType, Extrinsic as ExtrinsicT};
+
+		// All the stuff we need to declare our `Block`
+		pub type BlockNumber = u64;
+		pub type DigestItem = runtime_primitives::generic::DigestItem<H256, u64>;
+		pub type Digest = runtime_primitives::generic::Digest<DigestItem>;
+		#[derive(Clone, PartialEq, Eq, Encode, Decode, Debug)]
+		pub struct Extrinsic {}
+
+		impl serde::Serialize for Extrinsic {
+			fn serialize<S>(&self, seq: S) -> Result<S::Ok, S::Error> where S: ::serde::Serializer {
+				unimplemented!()
+			}
+		}
+		impl ExtrinsicT for Extrinsic {
+			fn is_signed(&self) -> Option<bool> {
+				unimplemented!()
+			}
+		}
+		pub type Header = runtime_primitives::generic::Header<BlockNumber, BlakeTwo256, DigestItem>;
+		pub type Block = runtime_primitives::generic::Block<Header, Extrinsic>;
+
+		/// The declaration of the `Runtime` type and the implementation of the `GetNodeBlockType`
+		/// trait are done by the `construct_runtime!` macro in a real runtime.
+		struct Runtime {}
+		impl GetNodeBlockType for Runtime {
+			type NodeBlock = Block;
+		}
+
+		decl_runtime_apis! {
+			pub trait Api {
+				fn test(data: u64);
+			}
+		}
+
+		impl_runtime_apis! {
+			impl self::Api for Runtime {
+				fn test(data: u64) {
+					unimplemented!()
+				}
+			}
+		}
+
+		fn main() {}
+	```
+	*/
+}
+
+mod missing_path_for_trait {
+	/*!
+	```compile_fail
+		#[macro_use]
+		extern crate substrate_client;
+		extern crate sr_primitives as runtime_primitives;
+		extern crate substrate_primitives as primitives;
+		#[macro_use]
+		extern crate parity_codec_derive;
+		extern crate serde;
+		extern crate core;
+
+		use primitives::hash::H256;
+		use runtime_primitives::traits::{BlakeTwo256, GetNodeBlockType, Extrinsic as ExtrinsicT};
+
+		// All the stuff we need to declare our `Block`
+		pub type BlockNumber = u64;
+		pub type DigestItem = runtime_primitives::generic::DigestItem<H256, u64>;
+		pub type Digest = runtime_primitives::generic::Digest<DigestItem>;
+		#[derive(Clone, PartialEq, Eq, Encode, Decode, Debug)]
+		pub struct Extrinsic {}
+		impl serde::Serialize for Extrinsic
+		{
+			fn serialize<S>(&self, seq: S) -> Result<S::Ok, S::Error> where S: ::serde::Serializer {
+				unimplemented!()
+			}
+		}
+		impl ExtrinsicT for Extrinsic {
+			fn is_signed(&self) -> Option<bool> {
+				unimplemented!()
+			}
+		}
+		pub type Header = runtime_primitives::generic::Header<BlockNumber, BlakeTwo256, DigestItem>;
+		pub type Block = runtime_primitives::generic::Block<Header, Extrinsic>;
+
+		/// The declaration of the `Runtime` type and the implementation of the `GetNodeBlockType`
+		/// trait are done by the `construct_runtime!` macro in a real runtime.
+		struct Runtime {}
+		impl GetNodeBlockType for Runtime {
+			type NodeBlock = Block;
+		}
+
+		decl_runtime_apis! {
+			pub trait Api {
+				fn test(data: u64);
+			}
+		}
+
+		impl_runtime_apis! {
+			impl Api<Block> for Runtime {
+				fn test(data: u64) {
+					unimplemented!()
+				}
+			}
+		}
+
+		fn main() {}
+	```
+	*/
+}
+
+mod empty_impl_runtime_apis_call {
+	/*!
+	```compile_fail
+		#[macro_use]
+		extern crate substrate_client;
+		extern crate sr_primitives as runtime_primitives;
+		extern crate substrate_primitives as primitives;
+		#[macro_use]
+		extern crate parity_codec_derive;
+		extern crate serde;
+		extern crate core;
+
+		use primitives::hash::H256;
+		use runtime_primitives::traits::{BlakeTwo256, GetNodeBlockType, Extrinsic as ExtrinsicT};
+
+		// All the stuff we need to declare our `Block`
+		pub type BlockNumber = u64;
+		pub type DigestItem = runtime_primitives::generic::DigestItem<H256, u64>;
+		pub type Digest = runtime_primitives::generic::Digest<DigestItem>;
+		#[derive(Clone, PartialEq, Eq, Encode, Decode, Debug)]
+		pub struct Extrinsic {}
+		impl serde::Serialize for Extrinsic
+		{
+			fn serialize<S>(&self, seq: S) -> Result<S::Ok, S::Error> where S: ::serde::Serializer {
+				unimplemented!()
+			}
+		}
+		impl ExtrinsicT for Extrinsic {
+			fn is_signed(&self) -> Option<bool> {
+				unimplemented!()
+			}
+		}
+		pub type Header = runtime_primitives::generic::Header<BlockNumber, BlakeTwo256, DigestItem>;
+		pub type Block = runtime_primitives::generic::Block<Header, Extrinsic>;
+
+		/// The declaration of the `Runtime` type and the implementation of the `GetNodeBlockType`
+		/// trait are done by the `construct_runtime!` macro in a real runtime.
+		struct Runtime {}
+		impl GetNodeBlockType for Runtime {
+			type NodeBlock = Block;
+		}
+
+		decl_runtime_apis! {
+			pub trait Api {
+				fn test(data: u64);
+			}
+		}
+
+		impl_runtime_apis! {}
+
+		fn main() {}
+	```
+	*/
+}
+
+mod type_reference_in_impl_runtime_apis_call {
+	/*!
+	```compile_fail
+		#[macro_use]
+		extern crate substrate_client;
+		extern crate sr_primitives as runtime_primitives;
+		extern crate substrate_primitives as primitives;
+		#[macro_use]
+		extern crate parity_codec_derive;
+		extern crate serde;
+		extern crate core;
+
+		use primitives::hash::H256;
+		use runtime_primitives::traits::{BlakeTwo256, GetNodeBlockType, Extrinsic as ExtrinsicT};
+
+		// All the stuff we need to declare our `Block`
+		pub type BlockNumber = u64;
+		pub type DigestItem = runtime_primitives::generic::DigestItem<H256, u64>;
+		pub type Digest = runtime_primitives::generic::Digest<DigestItem>;
+		#[derive(Clone, PartialEq, Eq, Encode, Decode, Debug)]
+		pub struct Extrinsic {}
+		impl serde::Serialize for Extrinsic
+		{
+			fn serialize<S>(&self, seq: S) -> Result<S::Ok, S::Error> where S: ::serde::Serializer {
+				unimplemented!()
+			}
+		}
+		impl ExtrinsicT for Extrinsic {
+			fn is_signed(&self) -> Option<bool> {
+				unimplemented!()
+			}
+		}
+		pub type Header = runtime_primitives::generic::Header<BlockNumber, BlakeTwo256, DigestItem>;
+		pub type Block = runtime_primitives::generic::Block<Header, Extrinsic>;
+
+		/// The declaration of the `Runtime` type and the implementation of the `GetNodeBlockType`
+		/// trait are done by the `construct_runtime!` macro in a real runtime.
+		struct Runtime {}
+		impl GetNodeBlockType for Runtime {
+			type NodeBlock = Block;
+		}
+
+		decl_runtime_apis! {
+			pub trait Api {
+				fn test(data: u64);
+			}
+		}
+
+		impl_runtime_apis! {
+			impl self::Api<Block> for Runtime {
+				fn test(data: &u64) {
+					unimplemented!()
+				}
+			}
+		}
+
+		fn main() {}
+	```
+	*/
+}
+
+mod impl_incorrect_method_signature {
+	/*!
+	```compile_fail
+		#[macro_use]
+		extern crate substrate_client;
+		extern crate sr_primitives as runtime_primitives;
+		extern crate substrate_primitives as primitives;
+		#[macro_use]
+		extern crate parity_codec_derive;
+		extern crate serde;
+		extern crate core;
+
+		use primitives::hash::H256;
+		use runtime_primitives::traits::{BlakeTwo256, GetNodeBlockType, Extrinsic as ExtrinsicT};
+
+		// All the stuff we need to declare our `Block`
+		pub type BlockNumber = u64;
+		pub type DigestItem = runtime_primitives::generic::DigestItem<H256, u64>;
+		pub type Digest = runtime_primitives::generic::Digest<DigestItem>;
+		#[derive(Clone, PartialEq, Eq, Encode, Decode, Debug)]
+		pub struct Extrinsic {}
+		impl serde::Serialize for Extrinsic
+		{
+			fn serialize<S>(&self, seq: S) -> Result<S::Ok, S::Error> where S: ::serde::Serializer {
+				unimplemented!()
+			}
+		}
+		impl ExtrinsicT for Extrinsic {
+			fn is_signed(&self) -> Option<bool> {
+				unimplemented!()
+			}
+		}
+		pub type Header = runtime_primitives::generic::Header<BlockNumber, BlakeTwo256, DigestItem>;
+		pub type Block = runtime_primitives::generic::Block<Header, Extrinsic>;
+
+		/// The declaration of the `Runtime` type and the implementation of the `GetNodeBlockType`
+		/// trait are done by the `construct_runtime!` macro in a real runtime.
+		struct Runtime {}
+		impl GetNodeBlockType for Runtime {
+			type NodeBlock = Block;
+		}
+
+		decl_runtime_apis! {
+			pub trait Api {
+				fn test(data: u64);
+			}
+		}
+
+		impl_runtime_apis! {
+			impl self::Api<Block> for Runtime {
+				fn test(data: String) {}
+			}
+		}
+
+		fn main() {}
+	```
+	*/
+}

substrate/core/sr-api-macros/src/decl_runtime_apis.rs

@@ -0,0 +1,278 @@
+// Copyright 2018 Parity Technologies (UK) Ltd.
+// This file is part of Substrate.
+
+// Substrate is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Substrate is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Substrate.  If not, see <http://www.gnu.org/licenses/>.
+
+use utils::{
+	generate_crate_access, generate_hidden_includes, generate_runtime_mod_name_for_trait,
+	fold_fn_decl_for_client_side
+};
+
+use proc_macro;
+use proc_macro2::TokenStream;
+
+use quote::quote;
+
+use syn::{
+	spanned::Spanned, parse_macro_input, parse::{Parse, ParseStream, Result, Error},
+	fold::{self, Fold}, FnDecl, parse_quote, ItemTrait, Generics, GenericParam, Attribute,
+	visit::{Visit, self}, FnArg, Pat, TraitBound, Type
+};
+
+/// Unique identifier used to make the hidden includes unique for this macro.
+const HIDDEN_INCLUDES_ID: &str = "DECL_RUNTIME_APIS";
+
+/// The structure used for parsing the runtime api declarations.
+struct RuntimeApiDecls {
+	decls: Vec<ItemTrait>,
+}
+
+impl Parse for RuntimeApiDecls {
+	fn parse(input: ParseStream) -> Result<Self> {
+		let mut decls = Vec::new();
+
+		while !input.is_empty() {
+			decls.push(ItemTrait::parse(input)?);
+		}
+
+		Ok(Self { decls })
+	}
+}
+
+/// Extend the given generics with `Block: BlockT` as first generic parameter.
+fn extend_generics_with_block(generics: &mut Generics) {
+	let c = generate_crate_access(HIDDEN_INCLUDES_ID);
+
+	generics.lt_token = Some(parse_quote!(<));
+	generics.params.insert(0, parse_quote!( Block: #c::runtime_api::BlockT ));
+	generics.gt_token = Some(parse_quote!(>));
+}
+
+// Check if `core_trait` attribute is present and remove it. Returns if the attribute was found.
+fn remove_core_trait_attribute(attrs: &mut Vec<Attribute>) -> bool {
+	let mut found = false;
+	attrs.retain(|v| {
+		let res = v.path.is_ident("core_trait");
+		found |= res;
+		!res
+	});
+	found
+}
+
+/// Generate the decleration of the trait for the runtime.
+fn generate_runtime_decls(decls: &[ItemTrait]) -> TokenStream {
+	let mut result = Vec::new();
+
+	for decl in decls {
+		let mut decl = decl.clone();
+		extend_generics_with_block(&mut decl.generics);
+		let mod_name = generate_runtime_mod_name_for_trait(&decl.ident);
+		remove_core_trait_attribute(&mut decl.attrs);
+
+		result.push(quote!(
+			#[doc(hidden)]
+			pub mod #mod_name {
+				use super::*;
+
+				#decl
+			}
+		));
+	}
+
+	quote!( #( #result )* )
+}
+
+/// Modify the given runtime api declaration to be usable on the client side.
+struct ToClientSideDecl<'a> {
+	block_id: &'a TokenStream,
+	crate_: &'a TokenStream,
+}
+
+impl<'a> Fold for ToClientSideDecl<'a> {
+	fn fold_fn_decl(&mut self, input: FnDecl) -> FnDecl {
+		let input = fold_fn_decl_for_client_side(
+			input,
+			&self.block_id,
+			&self.crate_
+		);
+
+		fold::fold_fn_decl(self, input)
+	}
+
+	fn fold_item_trait(&mut self, mut input: ItemTrait) -> ItemTrait {
+		extend_generics_with_block(&mut input.generics);
+
+		// Check if this is the `Core` runtime api trait.
+		let is_core_trait = remove_core_trait_attribute(&mut input.attrs);
+
+		if is_core_trait {
+			// Add all the supertraits we want to have for `Core`.
+			let crate_ = &self.crate_;
+			input.supertraits = parse_quote!(
+				'static
+				+ Send
+				+ Sync
+				+ #crate_::runtime_api::ConstructRuntimeApi<Block>
+				+ #crate_::runtime_api::ApiExt
+			);
+		} else {
+			// Add the `Core` runtime api as super trait.
+			let crate_ = &self.crate_;
+			input.supertraits.push(parse_quote!( #crate_::runtime_api::Core<Block> ));
+		}
+
+		// The client side trait is only required when compiling with the feature `std` or `test`.
+		input.attrs.push(parse_quote!( #[cfg(any(feature = "std", test))] ));
+
+		fold::fold_item_trait(self, input)
+	}
+}
+
+/// Generate the decleration of the trait for the client side.
+fn generate_client_side_decls(decls: &[ItemTrait]) -> TokenStream {
+	let mut result = Vec::new();
+
+	for decl in decls {
+		let mut decl = decl.clone();
+
+		let crate_ = generate_crate_access(HIDDEN_INCLUDES_ID);
+		let block_id = quote!( #crate_::runtime_api::BlockId<Block> );
+		let mut to_client_side = ToClientSideDecl { crate_: &crate_, block_id: &block_id };
+
+		result.push(to_client_side.fold_item_trait(decl));
+	}
+
+	quote!( #( #result )* )
+}
+
+/// Checks that a trait declaration is in the format we expect.
+struct CheckTraitDecl {
+	errors: Vec<Error>,
+}
+
+impl<'ast> Visit<'ast> for CheckTraitDecl {
+	fn visit_fn_arg(&mut self, input: &'ast FnArg) {
+		match input {
+			FnArg::Captured(ref arg) => {
+				match arg.pat {
+					Pat::Ident(ref pat) if pat.ident == "at" => {
+						self.errors.push(
+							Error::new(
+								pat.span(),
+								"`decl_runtime_apis!` adds automatically a parameter \
+								`at: &BlockId<Block>`. Please rename/remove your parameter."
+							)
+						)
+					},
+					_ => {}
+				}
+
+				match arg.ty {
+					Type::Reference(ref reference) => {
+						self.errors.push(
+							Error::new(
+								reference.span(),
+								"Do not use type references as arguments. The client side \
+								declaration will take all arguments as reference automatically."
+							)
+						)
+					},
+					_ => {},
+				}
+			},
+			FnArg::SelfRef(_) | FnArg::SelfValue(_) => {
+				self.errors.push(Error::new(input.span(), "Self values are not supported."))
+			}
+			_ => {
+				self.errors.push(
+					Error::new(
+						input.span(),
+						"Only function arguments in the form `pat: type` are supported."
+					)
+				)
+			}
+		}
+
+		visit::visit_fn_arg(self, input);
+	}
+
+	fn visit_generic_param(&mut self, input: &'ast GenericParam) {
+		match input {
+			GenericParam::Type(ty) if &ty.ident == "Block" => {
+				self.errors.push(
+					Error::new(
+						input.span(),
+						"`Block: BlockT` generic parameter will be added automatically by the \
+						`decl_runtime_apis!` macro!"
+					)
+				)
+			},
+			_ => {}
+		}
+
+		visit::visit_generic_param(self, input);
+	}
+
+	fn visit_trait_bound(&mut self, input: &'ast TraitBound) {
+		if let Some(last_ident) = input.path.segments.last().map(|v| &v.value().ident) {
+			if last_ident == "BlockT" || last_ident == "Block" {
+				self.errors.push(
+					Error::new(
+						input.span(),
+						"`Block: BlockT` generic parameter will be added automatically by the \
+						`decl_runtime_apis!` macro! If you try to use a different trait than the \
+						substrate `Block` trait, please rename it locally."
+					)
+				)
+			}
+		}
+
+		visit::visit_trait_bound(self, input)
+	}
+}
+
+/// Check that the trait declarations are in the format we expect.
+fn check_trait_decls(decls: &[ItemTrait]) -> Option<TokenStream> {
+	let mut checker = CheckTraitDecl { errors: Vec::new() };
+	decls.iter().for_each(|decl| visit::visit_item_trait(&mut checker, &decl));
+
+	if checker.errors.is_empty() {
+		None
+	} else {
+		let errors = checker.errors.into_iter().map(|e| e.to_compile_error());
+		Some(quote!( #( #errors )* ))
+	}
+}
+
+/// The implementation of the `decl_runtime_apis!` macro.
+pub fn decl_runtime_apis_impl(input: proc_macro::TokenStream) -> proc_macro::TokenStream {
+	// Parse all trait declarations
+	let RuntimeApiDecls { decls: api_decls } = parse_macro_input!(input as RuntimeApiDecls);
+
+	if let Some(errors) = check_trait_decls(&api_decls) {
+		return errors.into();
+	}
+
+	let hidden_includes = generate_hidden_includes(HIDDEN_INCLUDES_ID);
+	let runtime_decls = generate_runtime_decls(&api_decls);
+	let client_side_decls = generate_client_side_decls(&api_decls);
+
+	quote!(
+		#hidden_includes
+
+		#runtime_decls
+
+		#client_side_decls
+	).into()
+}

substrate/core/sr-api-macros/src/impl_runtime_apis.rs

@@ -0,0 +1,528 @@
+// Copyright 2018 Parity Technologies (UK) Ltd.
+// This file is part of Substrate.
+
+// Substrate is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Substrate is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Substrate.  If not, see <http://www.gnu.org/licenses/>.
+
+use utils::{
+	unwrap_or_error, generate_crate_access, generate_hidden_includes,
+	generate_runtime_mod_name_for_trait, fold_fn_decl_for_client_side
+};
+
+use proc_macro;
+use proc_macro2::{Span, TokenStream};
+
+use quote::quote;
+
+use syn::{
+	spanned::Spanned, parse_macro_input, Ident, Type, ItemImpl, MethodSig, FnArg, Path,
+	ImplItem, parse::{Parse, ParseStream, Result, Error}, PathArguments, GenericArgument, TypePath,
+	fold::{self, Fold}, FnDecl, parse_quote, Pat
+};
+
+use std::iter;
+
+/// Unique identifier used to make the hidden includes unique for this macro.
+const HIDDEN_INCLUDES_ID: &str = "IMPL_RUNTIME_APIS";
+
+/// The structure used for parsing the runtime api implementations.
+struct RuntimeApiImpls {
+	impls: Vec<ItemImpl>,
+}
+
+impl Parse for RuntimeApiImpls {
+	fn parse(input: ParseStream) -> Result<Self> {
+		let mut impls = Vec::new();
+
+		while !input.is_empty() {
+			impls.push(ItemImpl::parse(input)?);
+		}
+
+		Ok(Self { impls })
+	}
+}
+
+/// Generates the call to the implementation of the requested function.
+/// The generated code includes decoding of the input arguments and encoding of the output.
+fn generate_impl_call(
+	signature: &MethodSig,
+	runtime: &Type,
+	input: &Ident,
+	impl_trait: &Path
+) -> Result<TokenStream> {
+	let mut pnames = Vec::new();
+	let mut ptypes = Vec::new();
+	let mut generated_pattern_counter = 0;
+	for input in signature.decl.inputs.iter() {
+		match input {
+			FnArg::Captured(arg) => {
+				match &arg.ty {
+					Type::Reference(_) => {
+						return Err(
+							Error::new(
+								arg.ty.span(),
+								"No type references are allowed in the api traits!"
+							)
+						)
+					},
+					_ => {},
+				}
+
+				pnames.push(
+					generate_unique_pattern(arg.pat.clone(), &mut generated_pattern_counter)
+				);
+				ptypes.push(&arg.ty);
+			},
+			_ => {
+				return Err(
+					Error::new(
+						input.span(),
+						"Only function arguments with the following \
+						pattern are accepted: `name: type`!"
+					)
+				)
+			}
+		}
+	}
+
+	let c = generate_crate_access(HIDDEN_INCLUDES_ID);
+	let c_iter = iter::repeat(&c);
+	let fn_name = &signature.ident;
+	let fn_name_str = iter::repeat(fn_name.to_string());
+	let input = iter::repeat(input);
+	let pnames2 = pnames.clone();
+
+	Ok(
+		quote!(
+			#(
+				let #pnames : #ptypes = match #c_iter::runtime_api::Decode::decode(&mut #input) {
+					Some(input) => input,
+					None => panic!("Bad input data provided to {}", #fn_name_str),
+				};
+			)*
+
+			let output = <#runtime as #impl_trait>::#fn_name(#( #pnames2 ),*);
+			#c::runtime_api::Encode::encode(&output)
+		).into()
+	)
+}
+
+/// Extract the trait that is implemented in the given `ItemImpl`.
+fn extract_impl_trait<'a>(impl_: &'a ItemImpl) -> Result<&'a Path> {
+	impl_.trait_.as_ref().map(|v| &v.1).ok_or_else(
+		|| Error::new(impl_.span(), "Only implementation of traits are supported!")
+	).and_then(|p| {
+		if p.segments.len() > 1 {
+			Ok(p)
+		} else {
+			Err(
+				Error::new(
+					p.span(),
+					"The implemented trait has to be referenced with a path, \
+					e.g. `impl client::Core for Runtime`."
+				)
+			)
+		}
+	})
+}
+
+/// Extracts the runtime block identifier.
+fn extract_runtime_block_ident(trait_: &Path) -> Result<&TypePath> {
+	let span = trait_.span();
+	let segment = trait_
+		.segments
+		.last()
+		.ok_or_else(
+			|| Error::new(span, "Empty path not supported")
+		)?;
+	let generics = segment.value();
+
+	match &generics.arguments {
+		PathArguments::AngleBracketed(ref args) => {
+			args.args.first().and_then(|v| match v.value() {
+			GenericArgument::Type(Type::Path(block)) => Some(block),
+				_ => None
+			}).ok_or_else(|| Error::new(args.span(), "Missing `Block` generic parameter."))
+		},
+		PathArguments::None => {
+			let span = trait_.segments.last().as_ref().unwrap().value().span();
+			Err(Error::new(span, "Missing `Block` generic parameter."))
+		},
+		PathArguments::Parenthesized(_) => {
+			Err(Error::new(generics.arguments.span(), "Unexpected parentheses in path!"))
+		}
+	}
+}
+
+/// Generate all the implementation calls for the given functions.
+fn generate_impl_calls(impls: &[ItemImpl], input: &Ident) -> Result<Vec<(Ident, TokenStream)>> {
+	let mut impl_calls = Vec::new();
+
+	for impl_ in impls {
+		let impl_trait = extend_with_runtime_decl_path(extract_impl_trait(impl_)?.clone());
+
+		for item in &impl_.items {
+			match item {
+				ImplItem::Method(method) => {
+					let impl_call = generate_impl_call(
+						&method.sig,
+						&impl_.self_ty,
+						input,
+						&impl_trait
+					)?;
+
+					impl_calls.push((method.sig.ident.clone(), impl_call));
+				},
+				_ => {},
+			}
+		}
+	}
+
+	Ok(impl_calls)
+}
+
+/// Generate the dispatch function that is used in native to call into the runtime.
+fn generate_dispatch_function(impls: &[ItemImpl]) -> Result<TokenStream> {
+	let data = Ident::new("data", Span::call_site());
+	let impl_calls = generate_impl_calls(impls, &data)?.into_iter().map(|(fn_name, impl_)| {
+		let fn_name = fn_name.to_string();
+		quote!( #fn_name => Some({ #impl_ }), )
+	});
+
+	Ok(quote!(
+		#[cfg(feature = "std")]
+		pub fn dispatch(method: &str, mut #data: &[u8]) -> Option<Vec<u8>> {
+			match method {
+				#( #impl_calls )*
+				_ => None,
+			}
+		}
+	).into())
+}
+
+/// Generate the interface functions that are used to call into the runtime in wasm.
+fn generate_wasm_interface(impls: &[ItemImpl]) -> Result<TokenStream> {
+	let input = Ident::new("input", Span::call_site());
+	let c = generate_crate_access(HIDDEN_INCLUDES_ID);
+	let impl_calls = generate_impl_calls(impls, &input)?.into_iter().map(|(fn_name, impl_)| {
+		quote!(
+			#[cfg(not(feature = "std"))]
+			#[no_mangle]
+			pub fn #fn_name(input_data: *mut u8, input_len: usize) -> u64 {
+				let mut #input = if input_len == 0 {
+					&[0u8; 0]
+				} else {
+					unsafe {
+						#c::runtime_api::slice::from_raw_parts(input_data, input_len)
+					}
+				};
+
+				let output = { #impl_ };
+				let res = output.as_ptr() as u64 + ((output.len() as u64) << 32);
+
+				// Leak the output vector to avoid it being freed.
+				// This is fine in a WASM context since the heap
+				// will be discarded after the call.
+				::core::mem::forget(output);
+				res
+			}
+		)
+	});
+
+	Ok(quote!( #( #impl_calls )* ))
+}
+
+fn generate_block_and_block_id_ty(
+	runtime: &Type,
+	trait_: &'static str,
+	assoc_type: &'static str,
+) -> (TokenStream, TokenStream) {
+	let crate_ = generate_crate_access(HIDDEN_INCLUDES_ID);
+	let trait_ = Ident::new(trait_, Span::call_site());
+	let assoc_type = Ident::new(assoc_type, Span::call_site());
+
+	let block = quote!( <#runtime as #crate_::runtime_api::#trait_>::#assoc_type );
+	let block_id = quote!( #crate_::runtime_api::BlockId<#block> );
+
+	(block, block_id)
+}
+
+fn generate_node_block_and_block_id_ty(runtime: &Type) -> (TokenStream, TokenStream) {
+	generate_block_and_block_id_ty(runtime, "GetNodeBlockType", "NodeBlock")
+}
+
+fn generate_runtime_api_base_structures(impls: &[ItemImpl]) -> Result<TokenStream> {
+	let crate_ = generate_crate_access(HIDDEN_INCLUDES_ID);
+	let runtime = &impls.get(0).ok_or_else(||
+		Error::new(Span::call_site(), "No api implementation given!")
+	)?.self_ty;
+	let (block, block_id) = generate_node_block_and_block_id_ty(runtime);
+
+	Ok(quote!(
+		/// Implements all runtime apis for the client side.
+		#[cfg(any(feature = "std", test))]
+		pub struct RuntimeApi {
+			call: ::std::ptr::NonNull<#crate_::runtime_api::CallApiAt<#block>>,
+			commit_on_success: ::std::cell::RefCell<bool>,
+			initialised_block: ::std::cell::RefCell<Option<#block_id>>,
+			changes: ::std::cell::RefCell<#crate_::runtime_api::OverlayedChanges>,
+		}
+
+		// `RuntimeApi` itself is not threadsafe. However, an instance is only available in a
+		// `ApiRef` object and `ApiRef` also has an associated lifetime. This lifetimes makes it
+		// impossible to move `RuntimeApi` into another thread.
+		#[cfg(any(feature = "std", test))]
+		unsafe impl Send for RuntimeApi {}
+		#[cfg(any(feature = "std", test))]
+		unsafe impl Sync for RuntimeApi {}
+
+		#[cfg(any(feature = "std", test))]
+		impl #crate_::runtime_api::ApiExt for RuntimeApi {
+			fn map_api_result<F: FnOnce(&Self) -> ::std::result::Result<R, E>, R, E>(
+				&self,
+				map_call: F
+			) -> ::std::result::Result<R, E> {
+				*self.commit_on_success.borrow_mut() = false;
+				let res = map_call(self);
+				*self.commit_on_success.borrow_mut() = true;
+
+				self.commit_on_ok(&res);
+
+				res
+			}
+		}
+
+		#[cfg(any(feature = "std", test))]
+		impl #crate_::runtime_api::ConstructRuntimeApi<#block> for RuntimeApi {
+			fn construct_runtime_api<'a, T: #crate_::runtime_api::CallApiAt<#block>>(
+				call: &'a T
+			) -> #crate_::runtime_api::ApiRef<'a, Self> {
+				RuntimeApi {
+					call: unsafe {
+						::std::ptr::NonNull::new_unchecked(
+							call as &#crate_::runtime_api::CallApiAt<#block> as *const _ as *mut _
+						)
+					},
+					commit_on_success: true.into(),
+					initialised_block: None.into(),
+					changes: Default::default(),
+				}.into()
+			}
+		}
+
+		#[cfg(any(feature = "std", test))]
+		impl RuntimeApi {
+			fn call_api_at<A: #crate_::runtime_api::Encode, R: #crate_::runtime_api::Decode>(
+				&self,
+				at: &#block_id,
+				function: &'static str,
+				args: &A
+			) -> #crate_::error::Result<R> {
+				let res = unsafe {
+					self.call.as_ref().call_api_at(
+						at,
+						function,
+						args.encode(),
+						&mut *self.changes.borrow_mut(),
+						&mut *self.initialised_block.borrow_mut()
+					).and_then(|r|
+						R::decode(&mut &r[..])
+							.ok_or_else(||
+								#crate_::error::ErrorKind::CallResultDecode(function).into()
+							)
+					)
+				};
+
+				self.commit_on_ok(&res);
+				res
+			}
+
+			fn commit_on_ok<R, E>(&self, res: &::std::result::Result<R, E>) {
+				if *self.commit_on_success.borrow() {
+					if res.is_err() {
+						self.changes.borrow_mut().discard_prospective();
+					} else {
+						self.changes.borrow_mut().commit_prospective();
+					}
+				}
+			}
+		}
+	))
+}
+
+/// Extend the given trait path with module that contains the declaration of the trait for the
+/// runtime.
+fn extend_with_runtime_decl_path(mut trait_: Path) -> Path {
+	let runtime = {
+		let trait_name = &trait_
+			.segments
+			.last()
+			.as_ref()
+			.expect("Trait path should always contain at least one item; qed")
+			.value()
+			.ident;
+
+		generate_runtime_mod_name_for_trait(trait_name)
+	};
+
+	let pos = trait_.segments.len() - 1;
+	trait_.segments.insert(pos, runtime.clone().into());
+	trait_
+}
+
+/// Generates the implementations of the apis for the runtime.
+fn generate_api_impl_for_runtime(impls: &[ItemImpl]) -> Result<TokenStream> {
+	let mut impls_prepared = Vec::new();
+
+	// We put `runtime` before each trait to get the trait that is intended for the runtime and
+	// we put the `RuntimeBlock` as first argument for the trait generics.
+	for impl_ in impls.iter() {
+		let mut impl_ = impl_.clone();
+		let trait_ = extract_impl_trait(&impl_)?.clone();
+		let trait_ = extend_with_runtime_decl_path(trait_);
+
+		impl_.trait_.as_mut().unwrap().1 = trait_;
+		impls_prepared.push(impl_);
+	}
+
+	Ok(quote!( #( #impls_prepared )* ))
+}
+
+/// Generate an unique pattern based on the given counter, if the given pattern is a `_`.
+fn generate_unique_pattern(pat: Pat, counter: &mut u32) -> Pat {
+	match pat {
+		Pat::Wild(_) => {
+			let generated_name = Ident::new(
+				&format!("impl_runtime_api_generated_name_{}", counter),
+				pat.span()
+			);
+			*counter += 1;
+
+			parse_quote!( #generated_name )
+		},
+		_ => pat,
+	}
+}
+
+/// Auxilariy data structure that is used to convert `impl Api for Runtime` to
+/// `impl Api for RuntimeApi`.
+/// This requires us to replace the runtime `Block` with the node `Block`,
+/// `impl Api for Runtime` with `impl Api for RuntimeApi` and replace the method implementations
+/// with code that calls into the runtime.
+struct ApiRuntimeImplToApiRuntimeApiImpl<'a> {
+	node_block: &'a TokenStream,
+	runtime_block: &'a TypePath,
+	node_block_id: &'a TokenStream,
+}
+
+impl<'a> Fold for ApiRuntimeImplToApiRuntimeApiImpl<'a> {
+	fn fold_type_path(&mut self, input: TypePath) -> TypePath {
+		let new_ty_path = if input == *self.runtime_block {
+			let node_block = self.node_block;
+			parse_quote!( #node_block )
+		} else {
+			input
+		};
+
+		fold::fold_type_path(self, new_ty_path)
+	}
+
+	fn fold_fn_decl(&mut self, input: FnDecl) -> FnDecl {
+		let input = fold_fn_decl_for_client_side(
+			input,
+			&self.node_block_id,
+			&generate_crate_access(HIDDEN_INCLUDES_ID)
+		);
+
+		fold::fold_fn_decl(self, input)
+	}
+
+	fn fold_impl_item_method(&mut self, mut input: syn::ImplItemMethod) -> syn::ImplItemMethod {
+		{
+			let mut generated_name_counter = 0;
+			let arg_names = input.sig.decl.inputs.iter_mut().filter_map(|i| match i {
+				FnArg::Captured(ref mut arg) => Some(&mut arg.pat),
+				_ => None,
+			}).map(|p| {
+				*p = generate_unique_pattern(p.clone(), &mut generated_name_counter);
+				p
+			});
+			let name = input.sig.ident.to_string();
+
+			// Generate the new method implementation that calls into the runime.
+			input.block = parse_quote!( { self.call_api_at(at, #name, &( #( #arg_names ),* )) } );
+		}
+
+		fold::fold_impl_item_method(self, input)
+	}
+
+	fn fold_item_impl(&mut self, mut input: ItemImpl) -> ItemImpl {
+		// Implement the trait for the `RuntimeApi`
+		input.self_ty = Box::new(parse_quote!( RuntimeApi ));
+
+		// The implementation for the `RuntimeApi` is only required when compiling with the feature
+		// `std` or `test`.
+		input.attrs.push(parse_quote!( #[cfg(any(feature = "std", test))] ));
+
+		fold::fold_item_impl(self, input)
+	}
+}
+
+fn generate_api_impl_for_runtime_api(impls: &[ItemImpl]) -> Result<TokenStream> {
+	let mut result = Vec::with_capacity(impls.len());
+
+	for impl_ in impls {
+		let runtime_block = extract_runtime_block_ident(extract_impl_trait(&impl_)?)?;
+		let (node_block, node_block_id) = generate_node_block_and_block_id_ty(&impl_.self_ty);
+
+		let mut visitor = ApiRuntimeImplToApiRuntimeApiImpl {
+			runtime_block,
+			node_block: &node_block,
+			node_block_id: &node_block_id,
+		};
+
+		result.push(visitor.fold_item_impl(impl_.clone()));
+	}
+
+	Ok(quote!( #( #result )* ))
+}
+
+/// The implementation of the `impl_runtime_apis!` macro.
+pub fn impl_runtime_apis_impl(input: proc_macro::TokenStream) -> proc_macro::TokenStream {
+	// Parse all impl blocks
+	let RuntimeApiImpls { impls: api_impls } = parse_macro_input!(input as RuntimeApiImpls);
+	let dispatch_impl = unwrap_or_error(generate_dispatch_function(&api_impls));
+	let wasm_interface = unwrap_or_error(generate_wasm_interface(&api_impls));
+	let hidden_includes = generate_hidden_includes(HIDDEN_INCLUDES_ID);
+	let base_runtime_api = unwrap_or_error(generate_runtime_api_base_structures(&api_impls));
+	let api_impls_for_runtime = unwrap_or_error(generate_api_impl_for_runtime(&api_impls));
+	let api_impls_for_runtime_api = unwrap_or_error(generate_api_impl_for_runtime_api(&api_impls));
+
+	quote!(
+		#hidden_includes
+
+		#base_runtime_api
+
+		#api_impls_for_runtime
+
+		#api_impls_for_runtime_api
+
+		pub mod api {
+			use super::*;
+
+			#dispatch_impl
+
+			#wasm_interface
+		}
+	).into()
+}

substrate/core/sr-api-macros/src/lib.rs

@@ -0,0 +1,164 @@
+// Copyright 2018 Parity Technologies (UK) Ltd.
+// This file is part of Substrate.
+
+// Substrate is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Substrate is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Substrate.  If not, see <http://www.gnu.org/licenses/>.
+
+//! Macros for declaring and implementing runtime apis.
+
+#![recursion_limit = "128"]
+extern crate proc_macro;
+extern crate proc_macro2;
+extern crate quote;
+extern crate syn;
+
+use proc_macro::TokenStream;
+
+mod impl_runtime_apis;
+mod decl_runtime_apis;
+mod utils;
+mod compile_fail_tests;
+
+/// Tags given trait implementations as runtime apis.
+///
+/// All traits given to this macro, need to be declared with the `decl_runtime_apis!` macro.
+/// The implementation of the trait should follow the declaration given to the `decl_runtime_apis!`
+/// macro, besides the `Block` type that is required as first generic parameter for each runtime
+/// api trait. When implementing a runtime api trait, it is required that the trait is referenced
+/// by a path, e.g. `impl my_trait::MyTrait for Runtime`. The macro will use this path to access
+/// the declaration of the trait for the runtime side.
+///
+/// The macro also generates the implementation of the apis for the client side by generating the
+/// `RuntimeApi` type. The `RuntimeApi` is hidden behind a `feature` called `std`.
+///
+/// # Example
+///
+/// ```rust
+/// #[macro_use]
+/// extern crate substrate_client;
+/// # extern crate sr_primitives as runtime_primitives;
+/// # extern crate substrate_primitives as primitives;
+/// # #[macro_use]
+/// # extern crate parity_codec_derive;
+/// # extern crate serde;
+/// # extern crate core;
+/// #
+/// # use primitives::hash::H256;
+/// # use runtime_primitives::traits::{BlakeTwo256, GetNodeBlockType, Extrinsic as ExtrinsicT};
+/// #
+/// # // All the stuff we need to declare our `Block`
+/// # pub type BlockNumber = u64;
+/// # pub type DigestItem = runtime_primitives::generic::DigestItem<H256, u64>;
+/// # pub type Digest = runtime_primitives::generic::Digest<DigestItem>;
+/// # #[derive(Clone, PartialEq, Eq, Encode, Decode, Debug)]
+/// # pub struct Extrinsic {}
+/// #
+/// # impl serde::Serialize for Extrinsic {
+/// #     fn serialize<S>(&self, seq: S) -> Result<S::Ok, S::Error> where S: ::serde::Serializer {
+/// #         unimplemented!()
+/// #     }
+/// # }
+/// # impl ExtrinsicT for Extrinsic {
+/// #     fn is_signed(&self) -> Option<bool> {
+/// #         unimplemented!()
+/// #     }
+/// # }
+/// # pub type Header = runtime_primitives::generic::Header<BlockNumber, BlakeTwo256, DigestItem>;
+/// # pub type Block = runtime_primitives::generic::Block<Header, Extrinsic>;
+/// #
+/// # /// The declaration of the `Runtime` type and the implementation of the `GetNodeBlockType`
+/// # /// trait are done by the `construct_runtime!` macro in a real runtime.
+/// # struct Runtime {}
+/// # impl GetNodeBlockType for Runtime {
+/// #     type NodeBlock = Block;
+/// # }
+/// #
+/// # 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);
+/// #     }
+/// #     pub trait BlockBuilder {
+/// #        fn build_block() -> Block;
+/// #    }
+/// # }
+///
+/// /// All runtime api implementations need to be done in one call of the macro!
+/// impl_runtime_apis! {
+///     impl self::Balance<Block> for Runtime {
+///         fn get_balance() -> u64 {
+///             1
+///         }
+///         fn set_balance(_bal: u64) {
+///             // Store the balance
+///         }
+///     }
+///
+///     impl self::BlockBuilder<Block> for Runtime {
+///         fn build_block() -> Block {
+///              unimplemented!("Please implement me!")
+///         }
+///     }
+/// }
+///
+/// # fn main() {}
+/// ```
+#[proc_macro]
+pub fn impl_runtime_apis(input: TokenStream) -> TokenStream {
+	impl_runtime_apis::impl_runtime_apis_impl(input)
+}
+
+/// 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
+///
+/// ```rust
+/// #[macro_use]
+/// extern crate substrate_client;
+///
+/// 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;
+///     }
+/// }
+///
+/// # fn main() {}
+/// ```
+#[proc_macro]
+pub fn decl_runtime_apis(input: TokenStream) -> TokenStream {
+	decl_runtime_apis::decl_runtime_apis_impl(input)
+}

substrate/core/sr-api-macros/src/utils.rs

@@ -0,0 +1,97 @@
+// Copyright 2018 Parity Technologies (UK) Ltd.
+// This file is part of Substrate.
+
+// Substrate is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Substrate is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Substrate.  If not, see <http://www.gnu.org/licenses/>.
+
+use proc_macro2::{TokenStream, Span};
+use syn::{Result, Ident, FnDecl, parse_quote, Type, FnArg};
+use quote::quote;
+use std::env;
+
+/// Unwrap the given result, if it is an error, `compile_error!` will be generated.
+pub fn unwrap_or_error(res: Result<TokenStream>) -> TokenStream {
+	res.unwrap_or_else(|e| e.to_compile_error())
+}
+
+fn generate_hidden_includes_mod_name(unique_id: &'static str) -> Ident {
+	Ident::new(&format!("sr_api_hidden_includes_{}", unique_id), Span::call_site())
+}
+
+/// Generates the hidden includes that are required to make the macro independent from its scope.
+pub fn generate_hidden_includes(unique_id: &'static str) -> TokenStream {
+	if env::var("CARGO_PKG_NAME").unwrap() == "substrate-client" {
+		TokenStream::new()
+	} else {
+		let mod_name = generate_hidden_includes_mod_name(unique_id);
+		quote!(
+			#[doc(hidden)]
+			mod #mod_name {
+				pub extern crate substrate_client as sr_api_client;
+			}
+		)
+	}.into()
+}
+
+/// Generates the access to the `subtrate_client` crate.
+pub fn generate_crate_access(unique_id: &'static str) -> TokenStream {
+	if env::var("CARGO_PKG_NAME").unwrap() == "substrate-client" {
+		quote!( crate )
+	} else {
+		let mod_name = generate_hidden_includes_mod_name(unique_id);
+		quote!( self::#mod_name::sr_api_client )
+	}.into()
+}
+
+/// Generates the name of the module that contains the trait declaration for the runtime.
+pub fn generate_runtime_mod_name_for_trait(trait_: &Ident) -> Ident {
+	Ident::new(&format!("runtime_decl_for_{}", trait_.to_string()), Span::call_site())
+}
+
+/// Fold the given `FnDecl` to make it usable on the client side.
+pub fn fold_fn_decl_for_client_side(
+	mut input: FnDecl,
+	block_id: &TokenStream,
+	crate_: &TokenStream
+) -> FnDecl {
+	// Add `&` to all parameter types.
+	input.inputs
+		.iter_mut()
+		.filter_map(|i| match i {
+			FnArg::Captured(ref mut arg) => Some(&mut arg.ty),
+			_ => None,
+		})
+		.filter_map(|i| match i {
+			Type::Reference(_) => None,
+			r => Some(r),
+		})
+		.for_each(|i| *i = parse_quote!( &#i ));
+
+	// Add `&self, at:& BlockId` as parameters to each function at the beginning.
+	input.inputs.insert(0, parse_quote!( at: &#block_id ));
+	input.inputs.insert(0, parse_quote!( &self ));
+
+	// Wrap the output in a `Result`
+	input.output = {
+		let generate_result = |ty: &Type| {
+			parse_quote!( -> ::std::result::Result<#ty, #crate_::error::Error> )
+		};
+
+		match &input.output {
+			syn::ReturnType::Default => generate_result(&parse_quote!( () )),
+			syn::ReturnType::Type(_, ref ty) => generate_result(&ty),
+		}
+	};
+
+	input
+}