sc_rpc_api/system/
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 system API.
20
21pub mod error;
22pub mod helpers;
23
24use jsonrpsee::{core::JsonValue, proc_macros::rpc};
25
26pub use self::helpers::{Health, NodeRole, PeerInfo, SyncState, SystemInfo};
27pub use error::Error;
28
29/// Substrate system RPC API
30#[rpc(client, server)]
31pub trait SystemApi<Hash, Number> {
32	/// Get the node's implementation name. Plain old string.
33	#[method(name = "system_name")]
34	fn system_name(&self) -> Result<String, Error>;
35
36	/// Get the node implementation's version. Should be a semver string.
37	#[method(name = "system_version")]
38	fn system_version(&self) -> Result<String, Error>;
39
40	/// Get the chain's name. Given as a string identifier.
41	#[method(name = "system_chain")]
42	fn system_chain(&self) -> Result<String, Error>;
43
44	/// Get the chain's type.
45	#[method(name = "system_chainType")]
46	fn system_type(&self) -> Result<sc_chain_spec::ChainType, Error>;
47
48	/// Get a custom set of properties as a JSON object, defined in the chain spec.
49	#[method(name = "system_properties")]
50	fn system_properties(&self) -> Result<sc_chain_spec::Properties, Error>;
51
52	/// Return health status of the node.
53	///
54	/// Node is considered healthy if it is:
55	/// - connected to some peers (unless running in dev mode)
56	/// - not performing a major sync
57	#[method(name = "system_health")]
58	async fn system_health(&self) -> Result<Health, Error>;
59
60	/// Returns the base58-encoded PeerId of the node.
61	#[method(name = "system_localPeerId")]
62	async fn system_local_peer_id(&self) -> Result<String, Error>;
63
64	/// Returns the multi-addresses that the local node is listening on
65	///
66	/// The addresses include a trailing `/p2p/` with the local PeerId, and are thus suitable to
67	/// be passed to `addReservedPeer` or as a bootnode address for example.
68	#[method(name = "system_localListenAddresses")]
69	async fn system_local_listen_addresses(&self) -> Result<Vec<String>, Error>;
70
71	/// Returns currently connected peers
72	#[method(name = "system_peers", with_extensions)]
73	async fn system_peers(&self) -> Result<Vec<PeerInfo<Hash, Number>>, Error>;
74
75	/// Returns current state of the network.
76	///
77	/// **Warning**: This API is not stable. Please do not programmatically interpret its output,
78	/// as its format might change at any time.
79	// TODO: the future of this call is uncertain: https://github.com/paritytech/substrate/issues/1890
80	// https://github.com/paritytech/substrate/issues/5541
81	#[method(name = "system_unstable_networkState", with_extensions)]
82	async fn system_network_state(&self) -> Result<JsonValue, Error>;
83
84	/// Adds a reserved peer. Returns the empty string or an error. The string
85	/// parameter should encode a `p2p` multiaddr.
86	///
87	/// `/ip4/198.51.100.19/tcp/30333/p2p/QmSk5HQbn6LhUwDiNMseVUjuRYhEtYj4aUZ6WfWoGURpdV`
88	/// is an example of a valid, passing multiaddr with PeerId attached.
89	#[method(name = "system_addReservedPeer", with_extensions)]
90	async fn system_add_reserved_peer(&self, peer: String) -> Result<(), Error>;
91
92	/// Remove a reserved peer. Returns the empty string or an error. The string
93	/// should encode only the PeerId e.g. `QmSk5HQbn6LhUwDiNMseVUjuRYhEtYj4aUZ6WfWoGURpdV`.
94	#[method(name = "system_removeReservedPeer", with_extensions)]
95	async fn system_remove_reserved_peer(&self, peer_id: String) -> Result<(), Error>;
96
97	/// Returns the list of reserved peers
98	#[method(name = "system_reservedPeers")]
99	async fn system_reserved_peers(&self) -> Result<Vec<String>, Error>;
100
101	/// Returns the roles the node is running as.
102	#[method(name = "system_nodeRoles")]
103	async fn system_node_roles(&self) -> Result<Vec<NodeRole>, Error>;
104
105	/// Returns the state of the syncing of the node: starting block, current best block, highest
106	/// known block.
107	#[method(name = "system_syncState")]
108	async fn system_sync_state(&self) -> Result<SyncState<Number>, Error>;
109
110	/// Adds the supplied directives to the current log filter
111	///
112	/// The syntax is identical to the CLI `<target>=<level>`:
113	///
114	/// `sync=debug,state=trace`
115	#[method(name = "system_addLogFilter", with_extensions)]
116	fn system_add_log_filter(&self, directives: String) -> Result<(), Error>;
117
118	/// Resets the log filter to Substrate defaults
119	#[method(name = "system_resetLogFilter", with_extensions)]
120	fn system_reset_log_filter(&self) -> Result<(), Error>;
121}
sc_rpc_api/system/mod.rs

sc_rpc_api/system/
mod.rs
