feat: initialize Kurdistan SDK - independent fork of Polkadot SDK

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

@@ -0,0 +1,154 @@
+// This file is part of Substrate.
+
+// Copyright (C) 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::{
+		error::Error,
+		event::{FollowEvent, MethodResponse},
+	},
+	common::events::StorageQuery,
+};
+use jsonrpsee::{proc_macros::rpc, server::ResponsePayload};
+pub use sp_rpc::list::ListOrValue;
+
+#[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_v1_follow" => "chainHead_v1_followEvent",
+		unsubscribe = "chainHead_v1_unfollow",
+		item = FollowEvent<Hash>,
+	)]
+	fn chain_head_unstable_follow(&self, with_runtime: bool);
+
+	/// Retrieves the body (list of transactions) of a pinned block.
+	///
+	/// This method should be seen as a complement to `chainHead_v1_follow`,
+	/// allowing the JSON-RPC client to retrieve more information about a block
+	/// that has been reported.
+	///
+	/// Use `archive_v1_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.
+	#[method(name = "chainHead_v1_body", with_extensions)]
+	async fn chain_head_unstable_body(
+		&self,
+		follow_subscription: String,
+		hash: Hash,
+	) -> ResponsePayload<'static, MethodResponse>;
+
+	/// Retrieves the header of a pinned block.
+	///
+	/// This method should be seen as a complement to `chainHead_v1_follow`,
+	/// allowing the JSON-RPC client to retrieve more information about a block
+	/// that has been reported.
+	///
+	/// Use `archive_v1_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_v1_header", with_extensions)]
+	async fn chain_head_unstable_header(
+		&self,
+		follow_subscription: String,
+		hash: Hash,
+	) -> Result<Option<String>, Error>;
+
+	/// Returns storage entries at a specific block's state.
+	///
+	/// # Unstable
+	///
+	/// This method is unstable and subject to change in the future.
+	#[method(name = "chainHead_v1_storage", with_extensions)]
+	async fn chain_head_unstable_storage(
+		&self,
+		follow_subscription: String,
+		hash: Hash,
+		items: Vec<StorageQuery<String>>,
+		child_trie: Option<String>,
+	) -> ResponsePayload<'static, MethodResponse>;
+
+	/// Call into the Runtime API at a specified block's state.
+	///
+	/// # Unstable
+	///
+	/// This method is unstable and subject to change in the future.
+	#[method(name = "chainHead_v1_call", with_extensions)]
+	async fn chain_head_unstable_call(
+		&self,
+		follow_subscription: String,
+		hash: Hash,
+		function: String,
+		call_parameters: String,
+	) -> ResponsePayload<'static, MethodResponse>;
+
+	/// Unpin a block or multiple blocks reported by the `follow` method.
+	///
+	/// Ongoing operations that require the provided block
+	/// will continue normally.
+	///
+	/// When this method returns an error, it is guaranteed that no blocks have been unpinned.
+	///
+	/// # Unstable
+	///
+	/// This method is unstable and subject to change in the future.
+	#[method(name = "chainHead_v1_unpin", with_extensions)]
+	async fn chain_head_unstable_unpin(
+		&self,
+		follow_subscription: String,
+		hash_or_hashes: ListOrValue<Hash>,
+	) -> Result<(), Error>;
+
+	/// Resumes a storage fetch started with `chainHead_storage` after it has generated an
+	/// `operationWaitingForContinue` event.
+	///
+	/// # Unstable
+	///
+	/// This method is unstable and subject to change in the future.
+	#[method(name = "chainHead_v1_continue", with_extensions)]
+	async fn chain_head_unstable_continue(
+		&self,
+		follow_subscription: String,
+		operation_id: String,
+	) -> Result<(), Error>;
+
+	/// Stops an operation started with chainHead_v1_body, chainHead_v1_call, or
+	/// chainHead_v1_storage. If the operation was still in progress, this interrupts it. If
+	/// the operation was already finished, this call has no effect.
+	///
+	/// # Unstable
+	///
+	/// This method is unstable and subject to change in the future.
+	#[method(name = "chainHead_v1_stopOperation", with_extensions)]
+	async fn chain_head_unstable_stop_operation(
+		&self,
+		follow_subscription: String,
+		operation_id: String,
+	) -> Result<(), Error>;
+}