soil_rpc/api/system/
mod.rs

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

soil_rpc/api/system/
mod.rs
