rpc: Implement chainHead RPC API (#12544)

* rpc/chain_head: Add event structure for serialization Signed-off-by: Alexandru Vasile <[email protected]> * rpc/chain_head: Add tests for events Signed-off-by: Alexandru Vasile <[email protected]> * rpc/chain_head: Add API trait for `chainHead` Signed-off-by: Alexandru Vasile <[email protected]> * rpc/chain_head: Add RPC errors Signed-off-by: Alexandru Vasile <[email protected]> * rpc/chain_head: Manage subscription ID tracking for pinned blocks Signed-off-by: Alexandru Vasile <[email protected]> * rpc/chain_head: Add tests for subscription management Signed-off-by: Alexandru Vasile <[email protected]> * rpc/chain_head: Constructor for the API Signed-off-by: Alexandru Vasile <[email protected]> * rpc/chain_head: Placeholders for API implementation Signed-off-by: Alexandru Vasile <[email protected]> * rpc/chain_head: Accept RPC subscription sink Signed-off-by: Alexandru Vasile <[email protected]> * rpc/chain_head: Generate the runtime API event Signed-off-by: Alexandru Vasile <[email protected]> * rpc/chain_head: Implement the `follow` method Signed-off-by: Alexandru Vasile <[email protected]> * rpc/chain_head: Implement the `body` method Signed-off-by: Alexandru Vasile <[email protected]> * rpc/chain_head: Implement the `header` method Signed-off-by: Alexandru Vasile <[email protected]> * rpc/chain_head: Implement the `storage` method Signed-off-by: Alexandru Vasile <[email protected]> * rpc/chain_head: Implement the `call` method Signed-off-by: Alexandru Vasile <[email protected]> * rpc/chain_head: Implement the `unpin` method Signed-off-by: Alexandru Vasile <[email protected]> * Update `Cargo.lock` Signed-off-by: Alexandru Vasile <[email protected]> * rpc/chain_head: Implement `getGenesis` method Signed-off-by: Alexandru Vasile <[email protected]> * rpc/chain_head: Fix clippy Signed-off-by: Alexandru Vasile <[email protected]> * rpc/chain_head: Parse params from hex string Signed-off-by: Alexandru Vasile <[email protected]> * rpc/chain_head: Constuct API with genesis hash Signed-off-by: Alexandru Vasile <[email protected]> * rpc/chain_head: Add the finalized block to reported tree route Signed-off-by: Alexandru Vasile <[email protected]> * rpc/chain_head: Export the API and events for better ergonomics Signed-off-by: Alexandru Vasile <[email protected]> * chain_head/tests: Add test module with helper functions Signed-off-by: Alexandru Vasile <[email protected]> * chain_head/tests: Test block events from the `follow` pubsub Signed-off-by: Alexandru Vasile <[email protected]> * chain_head/tests: Test `genesisHash` getter Signed-off-by: Alexandru Vasile <[email protected]> * chain_head/tests: Test `header` method Signed-off-by: Alexandru Vasile <[email protected]> * chain_head/tests: Test `body` method Signed-off-by: Alexandru Vasile <[email protected]> * chain_head/tests: Test calling into the runtime API Signed-off-by: Alexandru Vasile <[email protected]> * chain_head/tests: Test runtime for the `follow` method Signed-off-by: Alexandru Vasile <[email protected]> * chain_head/tests: Add runtime code changes for `follow` method Signed-off-by: Alexandru Vasile <[email protected]> * rpc/chain_head: Remove space from rustdoc Signed-off-by: Alexandru Vasile <[email protected]> * rpc/chain_head: Use the `child_key` for storage queries Signed-off-by: Alexandru Vasile <[email protected]> * rpc/chain_head: Test `storage` method Signed-off-by: Alexandru Vasile <[email protected]> * rpc/chain_head: Test child trie query for `storage` method Signed-off-by: Alexandru Vasile <[email protected]> * rpc/chain_head: Event serialization typo Signed-off-by: Alexandru Vasile <[email protected]> * rpc/chain_head: Remove subscription aliases Signed-off-by: Alexandru Vasile <[email protected]> * rpc/chain_head: Add `NetworkConfig` parameter Signed-off-by: Alexandru Vasile <[email protected]> * rpc/chain_head: Named parameters as camelCase if present Signed-off-by: Alexandru Vasile <[email protected]> * rpc/chain_head: Implement From<ApiError> for RuntimeEvents Signed-off-by: Alexandru Vasile <[email protected]> * rpc/chain_head: Handle pruning of the best block in finalization window Signed-off-by: Alexandru Vasile <[email protected]> * rpc/chain_head: Generate initial block events Signed-off-by: Alexandru Vasile <[email protected]> * chain_head/tests: Verify that initial in-memory blocks are reported Signed-off-by: Alexandru Vasile <[email protected]> * chain_head/tests: Verify the finalized event with forks and pruned blocks Signed-off-by: Alexandru Vasile <[email protected]> * rpc/chain_head: Fix clippy Signed-off-by: Alexandru Vasile <[email protected]> * rpc/chain_head: Separate logic for generating initial events Signed-off-by: Alexandru Vasile <[email protected]> * rpc/chain_head: Handle stopping a subscription ID Signed-off-by: Alexandru Vasile <[email protected]> * rpc/chain_head: Submit events until the "Stop" event is triggered Signed-off-by: Alexandru Vasile <[email protected]> * rpc/chain_head: Separate logic for handling new and finalized blocks Signed-off-by: Alexandru Vasile <[email protected]> * rpc/chain_head: Extend subscription logic with subId handle Signed-off-by: Alexandru Vasile <[email protected]> * rpc/chain_head: Adjust to the new subscription mngmt API Signed-off-by: Alexandru Vasile <[email protected]> * rpc/chain_head: Refuse RuntimeAPI calls without the runtime flag Signed-off-by: Alexandru Vasile <[email protected]> * chain_head/tests: Verify RuntimeAPI calls without runtime flag Signed-off-by: Alexandru Vasile <[email protected]> * rpc/chain_head: Add best block per subscription Signed-off-by: Alexandru Vasile <[email protected]> * rpc/chain_head: Check storage keys for prefixes Signed-off-by: Alexandru Vasile <[email protected]> * chain_head/tests: Check storage queries with invalid prefixes Signed-off-by: Alexandru Vasile <[email protected]> * rpc/chain_head: Allow maximum number of pinned blocks Signed-off-by: Alexandru Vasile <[email protected]> * chain_head/tests: Test the maximum number of pinned blocks Signed-off-by: Alexandru Vasile <[email protected]> * rpc/chain_head: Adjust to origin/master and apply clippy Signed-off-by: Alexandru Vasile <[email protected]> * client/service: Enable the `chainHead` API Signed-off-by: Alexandru Vasile <[email protected]> * rpc/chain_head: Stop subscription on client disconnect and add debug logs Signed-off-by: Alexandru Vasile <[email protected]> * rpc/chain_head: Fix sending `Stop` on subscription exit Signed-off-by: Alexandru Vasile <[email protected]> * rpc/chain_head: Check best block is descendent of latest finalized Signed-off-by: Alexandru Vasile <[email protected]> * chain_head/tests: Report events before pruning the best block Signed-off-by: Alexandru Vasile <[email protected]> * rpc/chain_head: Nonrecursive initial block generation Signed-off-by: Alexandru Vasile <[email protected]> * rpc/chain_head: Generate initial events on subscription executor Signed-off-by: Alexandru Vasile <[email protected]> * rpc/chain_head: Reduce dev-dependencies for tokio Signed-off-by: Alexandru Vasile <[email protected]> * Apply suggestions from code review Co-authored-by: Sebastian Kunert <[email protected]> * rpc/chain_head: Accept empty parameters Signed-off-by: Alexandru Vasile <[email protected]> * rpc/chain_head: Use debug of `HexDisplay` for full format Signed-off-by: Alexandru Vasile <[email protected]> * rpc/chain_head: Enable subscription ID Signed-off-by: Alexandru Vasile <[email protected]> * rpc/chain_head: Use jsonrpsee 16.2 camelCase feature for paramaters Signed-off-by: Alexandru Vasile <[email protected]> * rpc/chain_head: Use `NonZeroUsize` for `NetworkConfig` param Signed-off-by: Alexandru Vasile <[email protected]> * rpc/chain_head: Rename `runtime_updates` to `has_runtime_updates` Signed-off-by: Alexandru Vasile <[email protected]> Signed-off-by: Alexandru Vasile <[email protected]> Co-authored-by: Sebastian Kunert <[email protected]>
paritytech · Dec 19, 2022 · e118df5 · e118df5
1 parent cad470b
commit e118df5
Show file tree

Hide file tree

Showing 11 changed files with 2,885 additions and 9 deletions.
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/client/rpc-spec-v2/Cargo.toml b/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"
diff --git a/client/rpc-spec-v2/src/chain_head/api.rs b/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<()>;
+}