sc_rpc_spec_v2/chain_head/
api.rs

Help
1// This file is part of Substrate.
2
3// Copyright (C) Parity Technologies (UK) Ltd.
4// SPDX-License-Identifier: GPL-3.0-or-later WITH Classpath-exception-2.0
5
6// This program is free software: you can redistribute it and/or modify
7// it under the terms of the GNU General Public License as published by
8// the Free Software Foundation, either version 3 of the License, or
9// (at your option) any later version.
10
11// This program is distributed in the hope that it will be useful,
12// but WITHOUT ANY WARRANTY; without even the implied warranty of
13// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14// GNU General Public License for more details.
15
16// You should have received a copy of the GNU General Public License
17// along with this program. If not, see <https://www.gnu.org/licenses/>.
18
19#![allow(non_snake_case)]
20
21//! API trait of the chain head.
22use crate::{
23	chain_head::{
24		error::Error,
25		event::{FollowEvent, MethodResponse},
26	},
27	common::events::StorageQuery,
28};
29use jsonrpsee::{proc_macros::rpc, server::ResponsePayload};
30pub use sp_rpc::list::ListOrValue;
31
32#[rpc(client, server)]
33pub trait ChainHeadApi<Hash> {
34	/// Track the state of the head of the chain: the finalized, non-finalized, and best blocks.
35	///
36	/// # Unstable
37	///
38	/// This method is unstable and subject to change in the future.
39	#[subscription(
40		name = "chainHead_v1_follow" => "chainHead_v1_followEvent",
41		unsubscribe = "chainHead_v1_unfollow",
42		item = FollowEvent<Hash>,
43	)]
44	fn chain_head_unstable_follow(&self, with_runtime: bool);
45
46	/// Retrieves the body (list of transactions) of a pinned block.
47	///
48	/// This method should be seen as a complement to `chainHead_v1_follow`,
49	/// allowing the JSON-RPC client to retrieve more information about a block
50	/// that has been reported.
51	///
52	/// Use `archive_v1_body` if instead you want to retrieve the body of an arbitrary block.
53	///
54	/// # Unstable
55	///
56	/// This method is unstable and subject to change in the future.
57	#[method(name = "chainHead_v1_body", with_extensions)]
58	async fn chain_head_unstable_body(
59		&self,
60		follow_subscription: String,
61		hash: Hash,
62	) -> ResponsePayload<'static, MethodResponse>;
63
64	/// Retrieves the header of a pinned block.
65	///
66	/// This method should be seen as a complement to `chainHead_v1_follow`,
67	/// allowing the JSON-RPC client to retrieve more information about a block
68	/// that has been reported.
69	///
70	/// Use `archive_v1_header` if instead you want to retrieve the header of an arbitrary
71	/// block.
72	///
73	/// # Unstable
74	///
75	/// This method is unstable and subject to change in the future.
76	#[method(name = "chainHead_v1_header", with_extensions)]
77	async fn chain_head_unstable_header(
78		&self,
79		follow_subscription: String,
80		hash: Hash,
81	) -> Result<Option<String>, Error>;
82
83	/// Returns storage entries at a specific block's state.
84	///
85	/// # Unstable
86	///
87	/// This method is unstable and subject to change in the future.
88	#[method(name = "chainHead_v1_storage", with_extensions)]
89	async fn chain_head_unstable_storage(
90		&self,
91		follow_subscription: String,
92		hash: Hash,
93		items: Vec<StorageQuery<String>>,
94		child_trie: Option<String>,
95	) -> ResponsePayload<'static, MethodResponse>;
96
97	/// Call into the Runtime API at a specified block's state.
98	///
99	/// # Unstable
100	///
101	/// This method is unstable and subject to change in the future.
102	#[method(name = "chainHead_v1_call", with_extensions)]
103	async fn chain_head_unstable_call(
104		&self,
105		follow_subscription: String,
106		hash: Hash,
107		function: String,
108		call_parameters: String,
109	) -> ResponsePayload<'static, MethodResponse>;
110
111	/// Unpin a block or multiple blocks reported by the `follow` method.
112	///
113	/// Ongoing operations that require the provided block
114	/// will continue normally.
115	///
116	/// When this method returns an error, it is guaranteed that no blocks have been unpinned.
117	///
118	/// # Unstable
119	///
120	/// This method is unstable and subject to change in the future.
121	#[method(name = "chainHead_v1_unpin", with_extensions)]
122	async fn chain_head_unstable_unpin(
123		&self,
124		follow_subscription: String,
125		hash_or_hashes: ListOrValue<Hash>,
126	) -> Result<(), Error>;
127
128	/// Resumes a storage fetch started with `chainHead_storage` after it has generated an
129	/// `operationWaitingForContinue` event.
130	///
131	/// # Unstable
132	///
133	/// This method is unstable and subject to change in the future.
134	#[method(name = "chainHead_v1_continue", with_extensions)]
135	async fn chain_head_unstable_continue(
136		&self,
137		follow_subscription: String,
138		operation_id: String,
139	) -> Result<(), Error>;
140
141	/// Stops an operation started with chainHead_v1_body, chainHead_v1_call, or
142	/// chainHead_v1_storage. If the operation was still in progress, this interrupts it. If
143	/// the operation was already finished, this call has no effect.
144	///
145	/// # Unstable
146	///
147	/// This method is unstable and subject to change in the future.
148	#[method(name = "chainHead_v1_stopOperation", with_extensions)]
149	async fn chain_head_unstable_stop_operation(
150		&self,
151		follow_subscription: String,
152		operation_id: String,
153	) -> Result<(), Error>;
154}
sc_rpc_spec_v2/chain_head/api.rs

sc_rpc_spec_v2/chain_head/
api.rs
