sc_rpc_api/statement/
mod.rs

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//! Substrate Statement Store RPC API.
20//!
21//! Exposes two JSON-RPC methods: `statement_subscribeStatement` (a subscription streaming matching
22//! statements as `StatementEvent` notifications on `statement_statement`) and `statement_submit`
23//! (submit a SCALE-encoded statement). See the `StatementApi` trait below for the wire-format
24//! examples.
25
26use jsonrpsee::{core::RpcResult, proc_macros::rpc};
27use sp_core::Bytes;
28use sp_statement_store::{StatementEvent, SubmitResult, TopicFilter};
29
30pub mod error;
31
32/// Substrate statement RPC API
33#[rpc(client, server)]
34pub trait StatementApi {
35	/// Subscribe to new statements that match the provided filters.
36	///
37	/// # Parameters
38	///
39	/// - `topic_filter` — Which topics to match. Use `TopicFilter::Any` to match all topics,
40	///   `TopicFilter::MatchAll(vec)` to match statements that include all provided topics, or
41	///   `TopicFilter::MatchAny(vec)` to match statements that include any of the provided topics.
42	///
43	/// # Returns
44	///
45	/// Returns a stream of `StatementEvent` values.
46	/// When a subscription is initiated the endpoint will first return all matching statements
47	/// already in the store in batches as `StatementEvent::NewStatements`.
48	///
49	/// NewStatements includes an Optional field `remaining` which indicates how many more
50	/// statements are left to be sent in the initial batch of existing statements. The field
51	/// guarantees to the client that it will receive at least this many more statements in the
52	/// subscription stream, but it may receive more if new statements are added to the store that
53	/// match the filter.
54	///
55	///  If there are no statements in the store matching the filter, an empty batch of statements
56	/// is sent.
57	///
58	/// # Examples
59	///
60	/// Subscribe, matching statements that include *all* of the given topics (use `"any"` to match
61	/// everything, or `{ "matchAny": [...] }` for any-of):
62	///
63	/// ```json
64	/// { "jsonrpc": "2.0", "id": 1, "method": "statement_subscribeStatement",
65	///   "params": [{ "matchAll": ["0xdede…", "0xadad…"] }] }
66	/// ```
67	///
68	/// Notifications arrive on `statement_statement`. The already-stored matches are delivered
69	/// first in batches, each carrying `remaining` (how many more are guaranteed to follow). An
70	/// empty initial batch is sent when nothing matches:
71	///
72	/// ```json
73	/// { "jsonrpc": "2.0", "method": "statement_statement",
74	///   "params": { "subscription": 4851578855668545,
75	///     "result": { "event": "newStatements", "data": { "statements": [], "remaining": 0 } } } }
76	/// ```
77	///
78	/// A non-empty batch from the initial set (each statement is hex-encoded SCALE):
79	///
80	/// ```json
81	/// { "jsonrpc": "2.0", "method": "statement_statement",
82	///   "params": { "subscription": 4851578855668545,
83	///     "result": { "event": "newStatements",
84	///       "data": { "statements": ["0x1000010000", "0x100001000000"], "remaining": 10 } } } }
85	/// ```
86	///
87	/// Statements arriving live, after the initial set is drained, carry no `remaining`:
88	///
89	/// ```json
90	/// { "jsonrpc": "2.0", "method": "statement_statement",
91	///   "params": { "subscription": 4851578855668545,
92	///     "result": { "event": "newStatements", "data": { "statements": ["0x1000010000"] } } } }
93	/// ```
94	#[subscription(
95		name = "statement_subscribeStatement" => "statement_statement",
96		unsubscribe = "statement_unsubscribeStatement",
97		item = StatementEvent,
98		with_extensions,
99	)]
100	fn subscribe_statement(&self, topic_filter: TopicFilter);
101
102	/// Submit a SCALE-encoded statement.
103	///
104	/// See `Statement` definition for more details.
105	///
106	/// Returns `SubmitResult` indicating success or failure reason.
107	///
108	/// # Examples
109	///
110	/// ```json
111	/// { "jsonrpc": "2.0", "id": 2, "method": "statement_submit", "params": ["0x…scale-encoded…"] }
112	/// ```
113	///
114	/// On success the result is `{ "status": "new" }`. Other outcomes are `known`, `knownExpired`,
115	/// `rejected` and `invalid` (each with a reason), and `internalError`.
116	#[method(name = "statement_submit")]
117	fn submit(&self, encoded: Bytes) -> RpcResult<SubmitResult>;
118}
sc_rpc_api/statement/mod.rs

sc_rpc_api/statement/
mod.rs
