Extract RPC definitions from RPC crate. (#3502)

* Extract author API from the substrate-rpc crate.

* Split out API from RPC.

* Clean up naming.

* Fix tests.

* Shorten error translations.

* Update Cargo.lock

substrate/core/rpc/api/Cargo.toml

@@ -0,0 +1,21 @@
+[package]
+name = "substrate-rpc-api"
+version = "2.0.0"
+authors = ["Parity Technologies <admin@parity.io>"]
+edition = "2018"
+
+[dependencies]
+codec = { package = "parity-scale-codec", version = "1.0.0" }
+derive_more = "0.14.0"
+futures03 = { package = "futures-preview", version = "0.3.0-alpha.17", features = ["compat"] }
+jsonrpc-core = "13.0.0"
+jsonrpc-core-client = "13.0.0"
+jsonrpc-derive = "13.0.0"
+jsonrpc-pubsub = "13.0.0"
+log = "0.4"
+parking_lot = "0.9.0"
+primitives = { package = "substrate-primitives", path = "../../primitives" }
+runtime_version = { package = "sr-version", path = "../../sr-version" }
+serde = { version = "1.0", features = ["derive"] }
+serde_json = "1.0"
+txpool = { package = "substrate-transaction-graph", path = "../../transaction-pool/graph" }

substrate/core/rpc/api/src/author/error.rs

@@ -0,0 +1,150 @@
+// Copyright 2017-2019 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/>.
+
+//! Authoring RPC module errors.
+
+use crate::errors;
+use jsonrpc_core as rpc;
+
+/// Author RPC Result type.
+pub type Result<T> = std::result::Result<T, Error>;
+
+/// Author RPC errors.
+#[derive(Debug, derive_more::Display, derive_more::From)]
+pub enum Error {
+	/// Client error.
+	#[display(fmt="Client error: {}", _0)]
+	Client(Box<dyn std::error::Error + Send>),
+	/// Transaction pool error,
+	#[display(fmt="Transaction pool error: {}", _0)]
+	Pool(txpool::error::Error),
+	/// Verification error
+	#[display(fmt="Extrinsic verification error: {}", _0)]
+	Verification(Box<dyn std::error::Error + Send>),
+	/// Incorrect extrinsic format.
+	#[display(fmt="Invalid extrinsic format: {}", _0)]
+	BadFormat(codec::Error),
+	/// Incorrect seed phrase.
+	#[display(fmt="Invalid seed phrase/SURI")]
+	BadSeedPhrase,
+	/// Key type ID has an unknown format.
+	#[display(fmt="Invalid key type ID format (should be of length four)")]
+	BadKeyType,
+	/// Key type ID has some unsupported crypto.
+	#[display(fmt="The crypto of key type ID is unknown")]
+	UnsupportedKeyType,
+	/// Some random issue with the key store. Shouldn't happen.
+	#[display(fmt="The key store is unavailable")]
+	KeyStoreUnavailable,
+}
+
+impl std::error::Error for Error {
+	fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
+		match self {
+			Error::Client(ref err) => Some(&**err),
+			Error::Pool(ref err) => Some(err),
+			Error::Verification(ref err) => Some(&**err),
+			_ => None,
+		}
+	}
+}
+
+/// Base code for all authorship errors.
+const BASE_ERROR: i64 = 1000;
+/// Extrinsic has an invalid format.
+const BAD_FORMAT: i64 = BASE_ERROR + 1;
+/// Error during transaction verification in runtime.
+const VERIFICATION_ERROR: i64 = BASE_ERROR + 2;
+
+/// Pool rejected the transaction as invalid
+const POOL_INVALID_TX: i64 = BASE_ERROR + 10;
+/// Cannot determine transaction validity.
+const POOL_UNKNOWN_VALIDITY: i64 = POOL_INVALID_TX + 1;
+/// The transaction is temporarily banned.
+const POOL_TEMPORARILY_BANNED: i64 = POOL_INVALID_TX + 2;
+/// The transaction is already in the pool
+const POOL_ALREADY_IMPORTED: i64 = POOL_INVALID_TX + 3;
+/// Transaction has too low priority to replace existing one in the pool.
+const POOL_TOO_LOW_PRIORITY: i64 = POOL_INVALID_TX + 4;
+/// Including this transaction would cause a dependency cycle.
+const POOL_CYCLE_DETECTED: i64 = POOL_INVALID_TX + 5;
+/// The transaction was not included to the pool because of the limits.
+const POOL_IMMEDIATELY_DROPPED: i64 = POOL_INVALID_TX + 6;
+/// The key type crypto is not known.
+const UNSUPPORTED_KEY_TYPE: i64 = POOL_INVALID_TX + 7;
+
+impl From<Error> for rpc::Error {
+	fn from(e: Error) -> Self {
+		use txpool::error::{Error as PoolError};
+
+		match e {
+			Error::BadFormat(e) => rpc::Error {
+				code: rpc::ErrorCode::ServerError(BAD_FORMAT),
+				message: format!("Extrinsic has invalid format: {}", e).into(),
+				data: None,
+			},
+			Error::Verification(e) => rpc::Error {
+				code: rpc::ErrorCode::ServerError(VERIFICATION_ERROR),
+				message: format!("Verification Error: {}", e).into(),
+				data: Some(format!("{:?}", e).into()),
+			},
+			Error::Pool(PoolError::InvalidTransaction(code)) => rpc::Error {
+				code: rpc::ErrorCode::ServerError(POOL_INVALID_TX),
+				message: "Invalid Transaction".into(),
+				data: Some(code.into()),
+			},
+			Error::Pool(PoolError::UnknownTransactionValidity(code)) => rpc::Error {
+				code: rpc::ErrorCode::ServerError(POOL_UNKNOWN_VALIDITY),
+				message: "Unknown Transaction Validity".into(),
+				data: Some(code.into()),
+			},
+			Error::Pool(PoolError::TemporarilyBanned) => rpc::Error {
+				code: rpc::ErrorCode::ServerError(POOL_TEMPORARILY_BANNED),
+				message: "Transaction is temporarily banned".into(),
+				data: None,
+			},
+			Error::Pool(PoolError::AlreadyImported(hash)) => rpc::Error {
+				code: rpc::ErrorCode::ServerError(POOL_ALREADY_IMPORTED),
+				message: "Transaction Already Imported".into(),
+				data: Some(format!("{:?}", hash).into()),
+			},
+			Error::Pool(PoolError::TooLowPriority { old, new }) => rpc::Error {
+				code: rpc::ErrorCode::ServerError(POOL_TOO_LOW_PRIORITY),
+				message: format!("Priority is too low: ({} vs {})", old, new),
+				data: Some("The transaction has too low priority to replace another transaction already in the pool.".into()),
+			},
+			Error::Pool(PoolError::CycleDetected) => rpc::Error {
+				code: rpc::ErrorCode::ServerError(POOL_CYCLE_DETECTED),
+				message: "Cycle Detected".into(),
+				data: None,
+			},
+			Error::Pool(PoolError::ImmediatelyDropped) => rpc::Error {
+				code: rpc::ErrorCode::ServerError(POOL_IMMEDIATELY_DROPPED),
+				message: "Immediately Dropped" .into(),
+				data: Some("The transaction couldn't enter the pool because of the limit".into()),
+			},
+			Error::UnsupportedKeyType => rpc::Error {
+				code: rpc::ErrorCode::ServerError(UNSUPPORTED_KEY_TYPE),
+				message: "Unknown key type crypto" .into(),
+				data: Some(
+					"The crypto for the given key type is unknown, please add the public key to the \
+					request to insert the key successfully.".into()
+				),
+			},
+			e => errors::internal(e),
+		}
+	}
+}

substrate/core/rpc/api/src/author/hash.rs

@@ -0,0 +1,32 @@
+// Copyright 2019 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/>.
+
+//! Extrinsic helpers for author RPC module.
+
+use primitives::Bytes;
+use serde::{Serialize, Deserialize};
+
+/// RPC Extrinsic or hash
+///
+/// Allows to refer to extrinsic either by its raw representation or its hash.
+#[derive(Debug, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub enum ExtrinsicOrHash<Hash> {
+	/// The hash of the extrinsic.
+	Hash(Hash),
+	/// Raw extrinsic bytes.
+	Extrinsic(Bytes),
+}

substrate/core/rpc/api/src/author/mod.rs

@@ -0,0 +1,87 @@
+// Copyright 2017-2019 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/>.
+
+//! Substrate block-author/full-node API.
+
+pub mod error;
+pub mod hash;
+
+use jsonrpc_derive::rpc;
+use jsonrpc_pubsub::{typed::Subscriber, SubscriptionId};
+use primitives::{
+	Bytes
+};
+use self::error::Result;
+use txpool::watcher::Status;
+
+pub use self::gen_client::Client as AuthorClient;
+
+/// Substrate authoring RPC API
+#[rpc]
+pub trait AuthorApi<Hash, BlockHash> {
+	/// RPC metadata
+	type Metadata;
+
+	/// Submit hex-encoded extrinsic for inclusion in block.
+	#[rpc(name = "author_submitExtrinsic")]
+	fn submit_extrinsic(&self, extrinsic: Bytes) -> Result<Hash>;
+
+	/// Insert a key into the keystore.
+	#[rpc(name = "author_insertKey")]
+	fn insert_key(&self,
+		key_type: String,
+		suri: String,
+		maybe_public: Option<Bytes>
+	) -> Result<Bytes>;
+
+	/// Generate new session keys and returns the corresponding public keys.
+	#[rpc(name = "author_rotateKeys")]
+	fn rotate_keys(&self) -> Result<Bytes>;
+
+	/// Returns all pending extrinsics, potentially grouped by sender.
+	#[rpc(name = "author_pendingExtrinsics")]
+	fn pending_extrinsics(&self) -> Result<Vec<Bytes>>;
+
+	/// Remove given extrinsic from the pool and temporarily ban it to prevent reimporting.
+	#[rpc(name = "author_removeExtrinsic")]
+	fn remove_extrinsic(&self,
+		bytes_or_hash: Vec<hash::ExtrinsicOrHash<Hash>>
+	) -> Result<Vec<Hash>>;
+
+	/// Submit an extrinsic to watch.
+	#[pubsub(
+		subscription = "author_extrinsicUpdate",
+		subscribe,
+		name = "author_submitAndWatchExtrinsic"
+	)]
+	fn watch_extrinsic(&self,
+		metadata: Self::Metadata,
+		subscriber: Subscriber<Status<Hash, BlockHash>>,
+		bytes: Bytes
+	);
+
+	/// Unsubscribe from extrinsic watching.
+	#[pubsub(
+		subscription = "author_extrinsicUpdate",
+		unsubscribe,
+		name = "author_unwatchExtrinsic"
+	)]
+	fn unwatch_extrinsic(&self,
+		metadata: Option<Self::Metadata>,
+		id: SubscriptionId
+	) -> Result<bool>;
+}
+

substrate/core/rpc/api/src/chain/error.rs

@@ -0,0 +1,59 @@
+// Copyright 2017-2019 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/>.
+
+
+//! Error helpers for Chain RPC module.
+
+use crate::errors;
+use jsonrpc_core as rpc;
+
+/// Chain RPC Result type.
+pub type Result<T> = std::result::Result<T, Error>;
+
+/// Chain RPC errors.
+#[derive(Debug, derive_more::Display, derive_more::From)]
+pub enum Error {
+	/// Client error.
+	#[display(fmt="Client error: {}", _0)]
+	Client(Box<dyn std::error::Error + Send>),
+	/// Other error type.
+	Other(String),
+}
+
+impl std::error::Error for Error {
+	fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
+		match self {
+			Error::Client(ref err) => Some(&**err),
+			_ => None,
+		}
+	}
+}
+
+/// Base error code for all chain errors.
+const BASE_ERROR: i64 = 3000;
+
+impl From<Error> for rpc::Error {
+	fn from(e: Error) -> Self {
+		match e {
+			Error::Other(message) => rpc::Error {
+				code: rpc::ErrorCode::ServerError(BASE_ERROR + 1),
+				message,
+				data: None,
+			},
+			e => errors::internal(e),
+		}
+	}
+}

substrate/core/rpc/api/src/chain/mod.rs

@@ -0,0 +1,89 @@
+// Copyright 2017-2019 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/>.
+
+//! Substrate blockchain API.
+
+pub mod error;
+pub mod number;
+
+use jsonrpc_core::Result as RpcResult;
+use jsonrpc_core::futures::Future;
+use jsonrpc_derive::rpc;
+use jsonrpc_pubsub::{typed::Subscriber, SubscriptionId};
+use self::error::Result;
+
+pub use self::gen_client::Client as ChainClient;
+
+/// Substrate blockchain API
+#[rpc]
+pub trait ChainApi<Number, Hash, Header, SignedBlock> {
+	/// RPC metadata
+	type Metadata;
+
+	/// Get header of a relay chain block.
+	#[rpc(name = "chain_getHeader")]
+	fn header(&self, hash: Option<Hash>) -> Result<Option<Header>>;
+
+	/// Get header and body of a relay chain block.
+	#[rpc(name = "chain_getBlock")]
+	fn block(&self, hash: Option<Hash>) -> Result<Option<SignedBlock>>;
+
+	/// Get hash of the n-th block in the canon chain.
+	///
+	/// By default returns latest block hash.
+	#[rpc(name = "chain_getBlockHash", alias("chain_getHead"))]
+	fn block_hash(&self, hash: Option<number::NumberOrHex<Number>>) -> Result<Option<Hash>>;
+
+	/// Get hash of the last finalized block in the canon chain.
+	#[rpc(name = "chain_getFinalizedHead", alias("chain_getFinalisedHead"))]
+	fn finalized_head(&self) -> Result<Hash>;
+
+	/// New head subscription
+	#[pubsub(
+		subscription = "chain_newHead",
+		subscribe,
+		name = "chain_subscribeNewHeads",
+		alias("subscribe_newHead", "chain_subscribeNewHead")
+	)]
+	fn subscribe_new_heads(&self, metadata: Self::Metadata, subscriber: Subscriber<Header>);
+
+	/// Unsubscribe from new head subscription.
+	#[pubsub(
+		subscription = "chain_newHead",
+		unsubscribe,
+		name = "chain_unsubscribeNewHeads",
+		alias("unsubscribe_newHead", "chain_unsubscribeNewHead")
+	)]
+	fn unsubscribe_new_heads(&self, metadata: Option<Self::Metadata>, id: SubscriptionId) -> RpcResult<bool>;
+
+	/// New head subscription
+	#[pubsub(
+		subscription = "chain_finalizedHead",
+		subscribe,
+		name = "chain_subscribeFinalizedHeads",
+		alias("chain_subscribeFinalisedHeads")
+	)]
+	fn subscribe_finalized_heads(&self, metadata: Self::Metadata, subscriber: Subscriber<Header>);
+
+	/// Unsubscribe from new head subscription.
+	#[pubsub(
+		subscription = "chain_finalizedHead",
+		unsubscribe,
+		name = "chain_unsubscribeFinalizedHeads",
+		alias("chain_unsubscribeFinalisedHeads")
+	)]
+	fn unsubscribe_finalized_heads(&self, metadata: Option<Self::Metadata>, id: SubscriptionId) -> RpcResult<bool>;
+}

substrate/core/rpc/api/src/chain/number.rs

@@ -0,0 +1,74 @@
+// Copyright 2017-2019 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/>.
+
+//! Chain RPC Block number type.
+
+use serde::{Serialize, Deserialize};
+use std::{convert::TryFrom, fmt::Debug};
+use primitives::U256;
+
+/// RPC Block number type
+///
+/// We allow two representations of the block number as input.
+/// Either we deserialize to the type that is specified in the block type
+/// or we attempt to parse given hex value.
+/// We do that for consistency with the returned type, default generic header
+/// serializes block number as hex to avoid overflows in JavaScript.
+#[derive(Serialize, Deserialize)]
+#[serde(untagged)]
+pub enum NumberOrHex<Number> {
+	/// The original header number type of block.
+	Number(Number),
+	/// Hex representation of the block number.
+	Hex(U256),
+}
+
+impl<Number: TryFrom<u64> + From<u32> + Debug + PartialOrd> NumberOrHex<Number> {
+	/// Attempts to convert into concrete block number.
+	///
+	/// Fails in case hex number is too big.
+	pub fn to_number(self) -> Result<Number, String> {
+		let num = match self {
+			NumberOrHex::Number(n) => n,
+			NumberOrHex::Hex(h) => {
+				let l = h.low_u64();
+				if U256::from(l) != h {
+					return Err(format!("`{}` does not fit into u64 type; unsupported for now.", h))
+				} else {
+					Number::try_from(l)
+						.map_err(|_| format!("`{}` does not fit into block number type.", h))?
+				}
+			},
+		};
+		// FIXME <2329>: Database seems to limit the block number to u32 for no reason
+		if num > Number::from(u32::max_value()) {
+			return Err(format!("`{:?}` > u32::max_value(), the max block number is u32.", num))
+		}
+		Ok(num)
+	}
+}
+
+impl From<u64> for NumberOrHex<u64> {
+	fn from(n: u64) -> Self {
+		NumberOrHex::Number(n)
+	}
+}
+
+impl<Number> From<U256> for NumberOrHex<Number> {
+	fn from(n: U256) -> Self {
+		NumberOrHex::Hex(n)
+	}
+}

substrate/core/rpc/api/src/errors.rs

@@ -0,0 +1,26 @@
+// Copyright 2018-2019 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 log::warn;
+
+pub fn internal<E: ::std::fmt::Debug>(e: E) -> jsonrpc_core::Error {
+	warn!("Unknown error: {:?}", e);
+	jsonrpc_core::Error {
+		code: jsonrpc_core::ErrorCode::InternalError,
+		message: "Unknown error occured".into(),
+		data: Some(format!("{:?}", e).into()),
+	}
+}

substrate/core/rpc/api/src/helpers.rs

@@ -0,0 +1,31 @@
+// Copyright 2018-2019 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 jsonrpc_core::futures::prelude::*;
+use futures03::{channel::oneshot, compat::Compat};
+
+/// Wraps around `oneshot::Receiver` and adjusts the error type to produce an internal error if the
+/// sender gets dropped.
+pub struct Receiver<T>(pub Compat<oneshot::Receiver<T>>);
+
+impl<T> Future for Receiver<T> {
+	type Item = T;
+	type Error = jsonrpc_core::Error;
+
+	fn poll(&mut self) -> Poll<Self::Item, Self::Error> {
+		self.0.poll().map_err(|_| jsonrpc_core::Error::internal_error())
+	}
+}

substrate/core/rpc/api/src/lib.rs

@@ -0,0 +1,34 @@
+// Copyright 2019 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/>.
+
+//! Substrate RPC interfaces.
+//!
+//! A collection of RPC methods and subscriptions supported by all substrate clients.
+
+#![warn(missing_docs)]
+
+mod errors;
+mod helpers;
+mod subscriptions;
+
+pub use jsonrpc_core::IoHandlerExtension as RpcExtension;
+pub use subscriptions::Subscriptions;
+pub use helpers::Receiver;
+
+pub mod author;
+pub mod chain;
+pub mod state;
+pub mod system;

substrate/core/rpc/api/src/state/error.rs

@@ -0,0 +1,66 @@
+// Copyright 2017-2019 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/>.
+
+//! State RPC errors.
+
+use crate::errors;
+use jsonrpc_core as rpc;
+
+/// State RPC Result type.
+pub type Result<T> = std::result::Result<T, Error>;
+
+/// State RPC errors.
+#[derive(Debug, derive_more::Display, derive_more::From)]
+pub enum Error {
+	/// Client error.
+	#[display(fmt="Client error: {}", _0)]
+	Client(Box<dyn std::error::Error + Send>),
+	/// Provided block range couldn't be resolved to a list of blocks.
+	#[display(fmt = "Cannot resolve a block range ['{:?}' ... '{:?}]. {}", from, to, details)]
+	InvalidBlockRange {
+		/// Beginning of the block range.
+		from: String,
+		/// End of the block range.
+		to: String,
+		/// Details of the error message.
+		details: String,
+	},
+}
+
+impl std::error::Error for Error {
+	fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
+		match self {
+			Error::Client(ref err) => Some(&**err),
+			_ => None,
+		}
+	}
+}
+
+/// Base code for all state errors.
+const BASE_ERROR: i64 = 4000;
+
+impl From<Error> for rpc::Error {
+	fn from(e: Error) -> Self {
+		match e {
+			Error::InvalidBlockRange { .. } => rpc::Error {
+				code: rpc::ErrorCode::ServerError(BASE_ERROR + 1),
+				message: format!("{}", e),
+				data: None,
+			},
+			e => errors::internal(e),
+		}
+	}
+}

substrate/core/rpc/api/src/state/mod.rs

@@ -0,0 +1,143 @@
+// Copyright 2017-2019 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/>.
+
+//! Substrate state API.
+
+pub mod error;
+
+use jsonrpc_core::Result as RpcResult;
+use jsonrpc_core::futures::Future;
+use jsonrpc_derive::rpc;
+use jsonrpc_pubsub::{typed::Subscriber, SubscriptionId};
+use primitives::Bytes;
+use primitives::storage::{StorageKey, StorageData, StorageChangeSet};
+use runtime_version::RuntimeVersion;
+use self::error::Result;
+
+pub use self::gen_client::Client as StateClient;
+
+/// Substrate state API
+#[rpc]
+pub trait StateApi<Hash> {
+	/// RPC Metadata
+	type Metadata;
+
+	/// Call a contract at a block's state.
+	#[rpc(name = "state_call", alias("state_callAt"))]
+	fn call(&self, name: String, bytes: Bytes, hash: Option<Hash>) -> Result<Bytes>;
+
+	/// Returns the keys with prefix, leave empty to get all the keys
+	#[rpc(name = "state_getKeys")]
+	fn storage_keys(&self, prefix: StorageKey, hash: Option<Hash>) -> Result<Vec<StorageKey>>;
+
+	/// Returns a storage entry at a specific block's state.
+	#[rpc(name = "state_getStorage", alias("state_getStorageAt"))]
+	fn storage(&self, key: StorageKey, hash: Option<Hash>) -> Result<Option<StorageData>>;
+
+	/// Returns the hash of a storage entry at a block's state.
+	#[rpc(name = "state_getStorageHash", alias("state_getStorageHashAt"))]
+	fn storage_hash(&self, key: StorageKey, hash: Option<Hash>) -> Result<Option<Hash>>;
+
+	/// Returns the size of a storage entry at a block's state.
+	#[rpc(name = "state_getStorageSize", alias("state_getStorageSizeAt"))]
+	fn storage_size(&self, key: StorageKey, hash: Option<Hash>) -> Result<Option<u64>>;
+
+	/// Returns the keys with prefix from a child storage, leave empty to get all the keys
+	#[rpc(name = "state_getChildKeys")]
+	fn child_storage_keys(
+		&self,
+		child_storage_key: StorageKey,
+		prefix: StorageKey,
+		hash: Option<Hash>
+	) -> Result<Vec<StorageKey>>;
+
+	/// Returns a child storage entry at a specific block's state.
+	#[rpc(name = "state_getChildStorage")]
+	fn child_storage(
+		&self,
+		child_storage_key: StorageKey,
+		key: StorageKey,
+		hash: Option<Hash>
+	) -> Result<Option<StorageData>>;
+
+	/// Returns the hash of a child storage entry at a block's state.
+	#[rpc(name = "state_getChildStorageHash")]
+	fn child_storage_hash(
+		&self,
+		child_storage_key: StorageKey,
+		key: StorageKey,
+		hash: Option<Hash>
+	) -> Result<Option<Hash>>;
+
+	/// Returns the size of a child storage entry at a block's state.
+	#[rpc(name = "state_getChildStorageSize")]
+	fn child_storage_size(
+		&self,
+		child_storage_key: StorageKey,
+		key: StorageKey,
+		hash: Option<Hash>
+	) -> Result<Option<u64>>;
+
+	/// Returns the runtime metadata as an opaque blob.
+	#[rpc(name = "state_getMetadata")]
+	fn metadata(&self, hash: Option<Hash>) -> Result<Bytes>;
+
+	/// Get the runtime version.
+	#[rpc(name = "state_getRuntimeVersion", alias("chain_getRuntimeVersion"))]
+	fn runtime_version(&self, hash: Option<Hash>) -> Result<RuntimeVersion>;
+
+	/// Query historical storage entries (by key) starting from a block given as the second parameter.
+	///
+	/// NOTE This first returned result contains the initial state of storage for all keys.
+	/// Subsequent values in the vector represent changes to the previous state (diffs).
+	#[rpc(name = "state_queryStorage")]
+	fn query_storage(
+		&self,
+		keys: Vec<StorageKey>,
+		block: Hash,
+		hash: Option<Hash>
+	) -> Result<Vec<StorageChangeSet<Hash>>>;
+
+	/// New runtime version subscription
+	#[pubsub(
+		subscription = "state_runtimeVersion",
+		subscribe,
+		name = "state_subscribeRuntimeVersion",
+		alias("chain_subscribeRuntimeVersion")
+	)]
+	fn subscribe_runtime_version(&self, metadata: Self::Metadata, subscriber: Subscriber<RuntimeVersion>);
+
+	/// Unsubscribe from runtime version subscription
+	#[pubsub(
+		subscription = "state_runtimeVersion",
+		unsubscribe,
+		name = "state_unsubscribeRuntimeVersion",
+		alias("chain_unsubscribeRuntimeVersion")
+	)]
+	fn unsubscribe_runtime_version(&self, metadata: Option<Self::Metadata>, id: SubscriptionId) -> RpcResult<bool>;
+
+	/// New storage subscription
+	#[pubsub(subscription = "state_storage", subscribe, name = "state_subscribeStorage")]
+	fn subscribe_storage(
+		&self, metadata: Self::Metadata, subscriber: Subscriber<StorageChangeSet<Hash>>, keys: Option<Vec<StorageKey>>
+	);
+
+	/// Unsubscribe from storage subscription
+	#[pubsub(subscription = "state_storage", unsubscribe, name = "state_unsubscribeStorage")]
+	fn unsubscribe_storage(
+		&self, metadata: Option<Self::Metadata>, id: SubscriptionId
+	) -> RpcResult<bool>;
+}

substrate/core/rpc/api/src/subscriptions.rs

@@ -0,0 +1,106 @@
+// Copyright 2017-2019 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 std::collections::HashMap;
+use std::sync::{Arc, atomic::{self, AtomicUsize}};
+
+use log::{error, warn};
+use jsonrpc_pubsub::{SubscriptionId, typed::{Sink, Subscriber}};
+use parking_lot::Mutex;
+use jsonrpc_core::futures::sync::oneshot;
+use jsonrpc_core::futures::{Future, future};
+
+type Id = u64;
+
+/// Generate unique ids for subscriptions.
+#[derive(Clone, Debug)]
+pub struct IdProvider {
+	next_id: Arc<AtomicUsize>,
+}
+impl Default for IdProvider {
+	fn default() -> Self {
+		IdProvider {
+			next_id: Arc::new(AtomicUsize::new(1)),
+		}
+	}
+}
+
+impl IdProvider {
+	/// Returns next id for the subscription.
+	pub fn next_id(&self) -> Id {
+		self.next_id.fetch_add(1, atomic::Ordering::AcqRel) as u64
+	}
+}
+
+/// Subscriptions manager.
+///
+/// Takes care of assigning unique subscription ids and
+/// driving the sinks into completion.
+#[derive(Clone)]
+pub struct Subscriptions {
+	next_id: IdProvider,
+	active_subscriptions: Arc<Mutex<HashMap<Id, oneshot::Sender<()>>>>,
+	executor: Arc<dyn future::Executor<Box<dyn Future<Item = (), Error = ()> + Send>> + Send + Sync>,
+}
+
+impl Subscriptions {
+	/// Creates new `Subscriptions` object.
+	pub fn new(executor: Arc<dyn future::Executor<Box<dyn Future<Item = (), Error = ()> + Send>> + Send + Sync>) -> Self {
+		Subscriptions {
+			next_id: Default::default(),
+			active_subscriptions: Default::default(),
+			executor,
+		}
+	}
+
+	/// Creates new subscription for given subscriber.
+	///
+	/// Second parameter is a function that converts Subscriber sink into a future.
+	/// This future will be driven to completion by the underlying event loop
+	/// or will be cancelled in case #cancel is invoked.
+	pub fn add<T, E, G, R, F>(&self, subscriber: Subscriber<T, E>, into_future: G) where
+		G: FnOnce(Sink<T, E>) -> R,
+		R: future::IntoFuture<Future=F, Item=(), Error=()>,
+		F: future::Future<Item=(), Error=()> + Send + 'static,
+	{
+		let id = self.next_id.next_id();
+		if let Ok(sink) = subscriber.assign_id(id.into()) {
+			let (tx, rx) = oneshot::channel();
+			let future = into_future(sink)
+				.into_future()
+				.select(rx.map_err(|e| warn!("Error timeing out: {:?}", e)))
+				.then(|_| Ok(()));
+
+			self.active_subscriptions.lock().insert(id, tx);
+			if self.executor.execute(Box::new(future)).is_err() {
+				error!("Failed to spawn RPC subscription task");
+			}
+		}
+	}
+
+	/// Cancel subscription.
+	///
+	/// Returns true if subscription existed or false otherwise.
+	pub fn cancel(&self, id: SubscriptionId) -> bool {
+		if let SubscriptionId::Number(id) = id {
+			if let Some(tx) = self.active_subscriptions.lock().remove(&id) {
+				let _ = tx.send(());
+				return true;
+			}
+		}
+		false
+	}
+}

substrate/core/rpc/api/src/system/error.rs

@@ -0,0 +1,48 @@
+// Copyright 2017-2019 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/>.
+
+//! System RPC module errors.
+
+use crate::system::helpers::Health;
+use jsonrpc_core as rpc;
+
+/// System RPC Result type.
+pub type Result<T> = std::result::Result<T, Error>;
+
+/// System RPC errors.
+#[derive(Debug, derive_more::Display, derive_more::From)]
+pub enum Error {
+	/// Provided block range couldn't be resolved to a list of blocks.
+	#[display(fmt = "Node is not fully functional: {}", _0)]
+	NotHealthy(Health),
+}
+
+impl std::error::Error for Error {}
+
+/// Base code for all system errors.
+const BASE_ERROR: i64 = 2000;
+
+impl From<Error> for rpc::Error {
+	fn from(e: Error) -> Self {
+		match e {
+			Error::NotHealthy(ref h) => rpc::Error {
+				code: rpc::ErrorCode::ServerError(BASE_ERROR + 1),
+				message: format!("{}", e),
+				data: serde_json::to_value(h).ok(),
+			},
+		}
+	}
+}

substrate/core/rpc/api/src/system/helpers.rs

@@ -0,0 +1,106 @@
+// Copyright 2017-2019 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/>.
+
+//! Substrate system API helpers.
+
+use std::fmt;
+use serde::{Serialize, Deserialize};
+use serde_json::{Value, map::Map};
+
+/// Node properties
+pub type Properties = Map<String, Value>;
+
+/// Running node's static details.
+#[derive(Clone, Debug)]
+pub struct SystemInfo {
+	/// Implementation name.
+	pub impl_name: String,
+	/// Implementation version.
+	pub impl_version: String,
+	/// Chain name.
+	pub chain_name: String,
+	/// A custom set of properties defined in the chain spec.
+	pub properties: Properties,
+}
+
+/// Health struct returned by the RPC
+#[derive(Debug, PartialEq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct Health {
+	/// Number of connected peers
+	pub peers: usize,
+	/// Is the node syncing
+	pub is_syncing: bool,
+	/// Should this node have any peers
+	///
+	/// Might be false for local chains or when running without discovery.
+	pub should_have_peers: bool,
+}
+
+/// Network Peer information
+#[derive(Debug, PartialEq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct PeerInfo<Hash, Number> {
+	/// Peer ID
+	pub peer_id: String,
+	/// Roles
+	pub roles: String,
+	/// Protocol version
+	pub protocol_version: u32,
+	/// Peer best block hash
+	pub best_hash: Hash,
+	/// Peer best block number
+	pub best_number: Number,
+}
+
+impl fmt::Display for Health {
+	fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
+		write!(fmt, "{} peers ({})", self.peers, if self.is_syncing {
+			"syncing"
+		} else { "idle" })
+	}
+}
+
+#[cfg(test)]
+mod tests {
+	use super::*;
+
+	#[test]
+	fn should_serialize_health() {
+		assert_eq!(
+			::serde_json::to_string(&Health {
+				peers: 1,
+				is_syncing: false,
+				should_have_peers: true,
+			}).unwrap(),
+			r#"{"peers":1,"isSyncing":false,"shouldHavePeers":true}"#,
+		);
+	}
+
+	#[test]
+	fn should_serialize_peer_info() {
+		assert_eq!(
+			::serde_json::to_string(&PeerInfo {
+				peer_id: "2".into(),
+				roles: "a".into(),
+				protocol_version: 2,
+				best_hash: 5u32,
+				best_number: 6u32,
+			}).unwrap(),
+			r#"{"peerId":"2","roles":"a","protocolVersion":2,"bestHash":5,"bestNumber":6}"#,
+		);
+	}
+}

substrate/core/rpc/api/src/system/mod.rs

@@ -0,0 +1,67 @@
+// Copyright 2017-2019 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/>.
+
+//! Substrate system API.
+
+pub mod error;
+pub mod helpers;
+
+use crate::helpers::Receiver;
+use jsonrpc_derive::rpc;
+
+use self::error::Result;
+
+pub use self::helpers::{Properties, SystemInfo, Health, PeerInfo};
+pub use self::gen_client::Client as SystemClient;
+
+/// Substrate system RPC API
+#[rpc]
+pub trait SystemApi<Hash, Number> {
+	/// Get the node's implementation name. Plain old string.
+	#[rpc(name = "system_name")]
+	fn system_name(&self) -> Result<String>;
+
+	/// Get the node implementation's version. Should be a semver string.
+	#[rpc(name = "system_version")]
+	fn system_version(&self) -> Result<String>;
+
+	/// Get the chain's type. Given as a string identifier.
+	#[rpc(name = "system_chain")]
+	fn system_chain(&self) -> Result<String>;
+
+	/// Get a custom set of properties as a JSON object, defined in the chain spec.
+	#[rpc(name = "system_properties")]
+	fn system_properties(&self) -> Result<Properties>;
+
+	/// Return health status of the node.
+	///
+	/// Node is considered healthy if it is:
+	/// - connected to some peers (unless running in dev mode)
+	/// - not performing a major sync
+	#[rpc(name = "system_health", returns = "Health")]
+	fn system_health(&self) -> Receiver<Health>;
+
+	/// Returns currently connected peers
+	#[rpc(name = "system_peers", returns = "Vec<PeerInfo<Hash, Number>>")]
+	fn system_peers(&self) -> Receiver<Vec<PeerInfo<Hash, Number>>>;
+
+	/// Returns current state of the network.
+	///
+	/// **Warning**: This API is not stable.
+	// TODO: make this stable and move structs https://github.com/paritytech/substrate/issues/1890
+	#[rpc(name = "system_networkState", returns = "jsonrpc_core::Value")]
+	fn system_network_state(&self) -> Receiver<jsonrpc_core::Value>;
+}