rpc: Implement chainHead RPC API

client/rpc-spec-v2/Cargo.toml

@@ -22,12 +22,25 @@ sp-core = { version = "7.0.0", path = "../../primitives/core" }
 sp-runtime = { version = "7.0.0", path = "../../primitives/runtime" }
 sp-api = { version = "4.0.0-dev", path = "../../primitives/api" }
 sp-blockchain = { version = "4.0.0-dev", path = "../../primitives/blockchain" }
+sp-version = { version = "5.0.0", path = "../../primitives/version" }
+sc-client-api = { version = "4.0.0-dev", path = "../api" }
 codec = { package = "parity-scale-codec", version = "3.0.0" }
 thiserror = "1.0"
 serde = "1.0"
 hex = "0.4"
 futures = "0.3.21"
+parking_lot = "0.12.1"
+tokio-stream = { version = "0.1", features = ["sync"] }
+array-bytes = "4.1"
+log = "0.4.17"
+futures-util = { version = "0.3.19", default-features = false }
 
 [dev-dependencies]
 serde_json = "1.0"
 tokio = { version = "1.22.0", features = ["macros"] }
+substrate-test-runtime-client = { version = "2.0.0", path = "../../test-utils/runtime/client" }
+substrate-test-runtime = { version = "2.0.0", path = "../../test-utils/runtime" }
+sp-consensus = { version = "0.10.0-dev", path = "../../primitives/consensus/common" }
+sp-maybe-compressed-blob = { version = "4.1.0-dev", path = "../../primitives/maybe-compressed-blob" }
+sc-block-builder = { version = "0.10.0-dev", path = "../block-builder" }
+assert_matches = "1.3.0"

client/rpc-spec-v2/src/chain_head/api.rs

@@ -0,0 +1,137 @@
+// This file is part of Substrate.
+
+// Copyright (C) 2022 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: GPL-3.0-or-later WITH Classpath-exception-2.0
+
+// This program 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.
+
+// This program 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 this program. If not, see <https://www.gnu.org/licenses/>.
+
+#![allow(non_snake_case)]
+
+//! API trait of the chain head.
+use crate::chain_head::event::{ChainHeadEvent, FollowEvent, NetworkConfig};
+use jsonrpsee::{core::RpcResult, proc_macros::rpc};
+
+#[rpc(client, server)]
+pub trait ChainHeadApi<Hash> {
+	/// Track the state of the head of the chain: the finalized, non-finalized, and best blocks.
+	///
+	/// # Unstable
+	///
+	/// This method is unstable and subject to change in the future.
+	#[subscription(
+		name = "chainHead_unstable_follow",
+		unsubscribe = "chainHead_unstable_unfollow",
+		item = FollowEvent<Hash>,
+	)]
+	fn chain_head_unstable_follow(&self, runtime_updates: bool);
+
+	/// Retrieves the body (list of transactions) of a pinned block.
+	///
+	/// This method should be seen as a complement to `chainHead_unstable_follow`,
+	/// allowing the JSON-RPC client to retrieve more information about a block
+	/// that has been reported.
+	///
+	/// Use `archive_unstable_body` if instead you want to retrieve the body of an arbitrary block.
+	///
+	/// # Unstable
+	///
+	/// This method is unstable and subject to change in the future.
+	#[subscription(
+		name = "chainHead_unstable_body",
+		unsubscribe = "chainHead_unstable_stopBody",
+		item = ChainHeadEvent<String>,
+	)]
+	fn chain_head_unstable_body(
+		&self,
+		follow_subscription: String,
+		hash: Hash,
+		network_config: Option<NetworkConfig>,
+	);
+
+	/// Retrieves the header of a pinned block.
+	///
+	/// This method should be seen as a complement to `chainHead_unstable_follow`,
+	/// allowing the JSON-RPC client to retrieve more information about a block
+	/// that has been reported.
+	///
+	/// Use `archive_unstable_header` if instead you want to retrieve the header of an arbitrary
+	/// block.
+	///
+	/// # Unstable
+	///
+	/// This method is unstable and subject to change in the future.
+	#[method(name = "chainHead_unstable_header", blocking)]
+	fn chain_head_unstable_header(
+		&self,
+		follow_subscription: String,
+		hash: Hash,
+	) -> RpcResult<Option<String>>;
+
+	/// Get the chain's genesis hash.
+	///
+	/// # Unstable
+	///
+	/// This method is unstable and subject to change in the future.
+	#[method(name = "chainHead_unstable_genesisHash", blocking)]
+	fn chain_head_unstable_genesis_hash(&self) -> RpcResult<String>;
+
+	/// Return a storage entry at a specific block's state.
+	///
+	/// # Unstable
+	///
+	/// This method is unstable and subject to change in the future.
+	#[subscription(
+		name = "chainHead_unstable_storage",
+		unsubscribe = "chainHead_unstable_stopStorage",
+		item = ChainHeadEvent<String>,
+	)]
+	fn chain_head_unstable_storage(
+		&self,
+		follow_subscription: String,
+		hash: Hash,
+		key: String,
+		child_key: Option<String>,
+		network_config: Option<NetworkConfig>,
+	);
+
+	/// Call into the Runtime API at a specified block's state.
+	///
+	/// # Unstable
+	///
+	/// This method is unstable and subject to change in the future.
+	#[subscription(
+		name = "chainHead_unstable_call",
+		unsubscribe = "chainHead_unstable_stopCall",
+		item = ChainHeadEvent<String>,
+	)]
+	fn chain_head_unstable_call(
+		&self,
+		follow_subscription: String,
+		hash: Hash,
+		function: String,
+		call_parameters: String,
+		network_config: Option<NetworkConfig>,
+	);
+
+	/// Unpin a block reported by the `follow` method.
+	///
+	/// Ongoing operations that require the provided block
+	/// will continue normally.
+	///
+	/// # Unstable
+	///
+	/// This method is unstable and subject to change in the future.
+	#[method(name = "chainHead_unstable_unpin", blocking)]
+	fn chain_head_unstable_unpin(&self, follow_subscription: String, hash: Hash) -> RpcResult<()>;
+}