ckb_jsonrpc_types/
net.rs

1use crate::{BlockNumber, Byte32, Timestamp, Uint64, Uint128};
2use ckb_types::H256;
3use schemars::JsonSchema;
4use serde::{Deserialize, Serialize};
5
6/// The information of the node itself.
7///
8/// ## Examples
9///
10/// ```
11/// # serde_json::from_str::<ckb_jsonrpc_types::LocalNode>(r#"
12/// {
13///   "active": true,
14///   "addresses": [
15///     {
16///       "address": "/ip4/192.168.0.2/tcp/8112/p2p/QmTRHCdrRtgUzYLNCin69zEvPvLYdxUZLLfLYyHVY3DZAS",
17///       "score": "0xff"
18///     },
19///     {
20///       "address": "/ip4/0.0.0.0/tcp/8112/p2p/QmTRHCdrRtgUzYLNCin69zEvPvLYdxUZLLfLYyHVY3DZAS",
21///       "score": "0x1"
22///     }
23///   ],
24///   "connections": "0xb",
25///   "node_id": "QmTRHCdrRtgUzYLNCin69zEvPvLYdxUZLLfLYyHVY3DZAS",
26///   "protocols": [
27///     {
28///       "id": "0x0",
29///       "name": "/ckb/ping",
30///       "support_versions": [
31///         "0.0.1"
32///       ]
33///     },
34///     {
35///       "id": "0x1",
36///       "name": "/ckb/discovery",
37///       "support_versions": [
38///         "0.0.1"
39///       ]
40///     }
41///   ],
42///   "version": "0.34.0 (f37f598 2020-07-17)"
43/// }
44/// # "#).unwrap();
45/// ```
46#[derive(Clone, Default, Serialize, Deserialize, PartialEq, Eq, Hash, Debug, JsonSchema)]
47pub struct LocalNode {
48    /// CKB node version.
49    ///
50    /// Example: "version": "0.34.0 (f37f598 2020-07-17)"
51    pub version: String,
52    /// The unique node ID derived from the p2p private key.
53    ///
54    /// The private key is generated randomly on the first boot.
55    pub node_id: String,
56    /// Whether this node is active.
57    ///
58    /// An inactive node ignores incoming p2p messages and drops outgoing messages.
59    pub active: bool,
60    /// P2P addresses of this node.
61    ///
62    /// A node can have multiple addresses.
63    pub addresses: Vec<NodeAddress>,
64    /// Supported protocols.
65    pub protocols: Vec<LocalNodeProtocol>,
66    /// Count of currently connected peers.
67    pub connections: Uint64,
68}
69
70/// The information of a P2P protocol that is supported by the local node.
71#[derive(Clone, Default, Serialize, Deserialize, PartialEq, Eq, Hash, Debug, JsonSchema)]
72pub struct LocalNodeProtocol {
73    /// Unique protocol ID.
74    pub id: Uint64,
75    /// Readable protocol name.
76    pub name: String,
77    /// Supported versions.
78    ///
79    /// See [Semantic Version](https://semver.org/) about how to specify a version.
80    pub support_versions: Vec<String>,
81}
82
83/// Information of a remote node.
84///
85/// A remote node connects to the local node via the P2P network. It is often called a peer.
86///
87/// ## Examples
88///
89/// ```
90/// # serde_json::from_str::<ckb_jsonrpc_types::RemoteNode>(r#"
91/// {
92///   "addresses": [
93///     {
94///       "address": "/ip6/::ffff:18.185.102.19/tcp/8115/p2p/QmXwUgF48ULy6hkgfqrEwEfuHW7WyWyWauueRDAYQHNDfN",
95///       "score": "0x64"
96///     },
97///     {
98///       "address": "/ip4/18.185.102.19/tcp/8115/p2p/QmXwUgF48ULy6hkgfqrEwEfuHW7WyWyWauueRDAYQHNDfN",
99///       "score": "0x64"
100///     }
101///   ],
102///   "connected_duration": "0x2f",
103///   "is_outbound": true,
104///   "last_ping_duration": "0x1a",
105///   "node_id": "QmXwUgF48ULy6hkgfqrEwEfuHW7WyWyWauueRDAYQHNDfN",
106///   "protocols": [
107///     {
108///       "id": "0x4",
109///       "version": "0.0.1"
110///     },
111///     {
112///       "id": "0x2",
113///       "version": "0.0.1"
114///     },
115///     {
116///       "id": "0x1",
117///       "version": "0.0.1"
118///     },
119///     {
120///       "id": "0x64",
121///       "version": "1"
122///     },
123///     {
124///       "id": "0x6e",
125///       "version": "1"
126///     },
127///     {
128///       "id": "0x66",
129///       "version": "1"
130///     },
131///     {
132///       "id": "0x65",
133///       "version": "1"
134///     },
135///     {
136///       "id": "0x0",
137///       "version": "0.0.1"
138///     }
139///   ],
140///   "sync_state": {
141///     "best_known_header_hash": null,
142///     "best_known_header_number": null,
143///     "can_fetch_count": "0x80",
144///     "inflight_count": "0xa",
145///     "last_common_header_hash": null,
146///     "last_common_header_number": null,
147///     "unknown_header_list_size": "0x20"
148///   },
149///   "version": "0.34.0 (f37f598 2020-07-17)"
150/// }
151/// # "#).unwrap();
152/// ```
153#[derive(Clone, Default, Serialize, Deserialize, PartialEq, Eq, Hash, Debug, JsonSchema)]
154pub struct RemoteNode {
155    /// The remote node version.
156    pub version: String,
157    /// The remote node ID which is derived from its P2P private key.
158    pub node_id: String,
159    /// The remote node addresses.
160    pub addresses: Vec<NodeAddress>,
161    /// Whether this is an outbound remote node.
162    ///
163    /// If the connection is established by the local node, `is_outbound` is true.
164    pub is_outbound: bool,
165    /// Elapsed time in milliseconds since the remote node is connected.
166    pub connected_duration: Uint64,
167    /// Elapsed time in milliseconds since receiving the ping response from this remote node.
168    ///
169    /// Null means no ping responses have been received yet.
170    pub last_ping_duration: Option<Uint64>,
171    /// Chain synchronization state.
172    ///
173    /// Null means chain sync has not started with this remote node yet.
174    pub sync_state: Option<PeerSyncState>,
175    /// Active protocols.
176    ///
177    /// CKB uses Tentacle multiplexed network framework. Multiple protocols are running
178    /// simultaneously in the connection.
179    pub protocols: Vec<RemoteNodeProtocol>,
180}
181
182/// The information about an active running protocol.
183#[derive(Clone, Default, Serialize, Deserialize, PartialEq, Eq, Hash, Debug, JsonSchema)]
184pub struct RemoteNodeProtocol {
185    /// Unique protocol ID.
186    pub id: Uint64,
187    /// Active protocol version.
188    pub version: String,
189}
190
191/// The chain synchronization state between the local node and a remote node.
192#[derive(Clone, Default, Serialize, Deserialize, PartialEq, Eq, Hash, Debug, JsonSchema)]
193pub struct PeerSyncState {
194    /// Best known header hash of remote peer.
195    ///
196    /// This is the observed tip of the remote node's canonical chain.
197    pub best_known_header_hash: Option<Byte32>,
198    /// Best known header number of remote peer
199    ///
200    /// This is the block number of the block with the hash `best_known_header_hash`.
201    pub best_known_header_number: Option<Uint64>,
202    /// Last common header hash of remote peer.
203    ///
204    /// This is the common ancestor of the local node canonical chain tip and the block
205    /// `best_known_header_hash`.
206    pub last_common_header_hash: Option<Byte32>,
207    /// Last common header number of remote peer.
208    ///
209    /// This is the block number of the block with the hash `last_common_header_hash`.
210    pub last_common_header_number: Option<Uint64>,
211    /// The total size of unknown header list.
212    ///
213    /// **Deprecated**: this is an internal state and will be removed in a future release.
214    pub unknown_header_list_size: Uint64,
215    /// The count of concurrency downloading blocks.
216    pub inflight_count: Uint64,
217    /// The count of blocks are available for concurrency download.
218    pub can_fetch_count: Uint64,
219}
220
221/// Node P2P address and score.
222#[derive(Clone, Default, Serialize, Deserialize, PartialEq, Eq, Hash, Debug, JsonSchema)]
223pub struct NodeAddress {
224    /// P2P address.
225    ///
226    /// This is the same address used in the whitelist in ckb.toml.
227    ///
228    /// Example: "/ip4/192.168.0.2/tcp/8112/p2p/QmTRHCdrRtgUzYLNCin69zEvPvLYdxUZLLfLYyHVY3DZAS"
229    pub address: String,
230    /// Address score.
231    ///
232    /// A higher score means a higher probability of a successful connection.
233    pub score: Uint64,
234}
235
236/// A banned P2P address.
237#[derive(Clone, Default, Serialize, Deserialize, PartialEq, Eq, Hash, Debug, JsonSchema)]
238pub struct BannedAddr {
239    /// The P2P address.
240    ///
241    /// Example: "/ip4/192.168.0.2/tcp/8112/p2p/QmTRHCdrRtgUzYLNCin69zEvPvLYdxUZLLfLYyHVY3DZAS"
242    pub address: String,
243    /// The address is banned until this time.
244    pub ban_until: Timestamp,
245    /// The reason.
246    pub ban_reason: String,
247    /// When this address is banned.
248    pub created_at: Timestamp,
249}
250
251/// The overall chain synchronization state of this local node.
252#[derive(Clone, Default, Serialize, Deserialize, PartialEq, Eq, Hash, Debug, JsonSchema)]
253pub struct SyncState {
254    /// Whether the local node is in IBD, Initial Block Download.
255    ///
256    /// When a node starts and its chain tip timestamp is far behind the wall clock, it will enter
257    /// the IBD until it catches up the synchronization.
258    ///
259    /// During IBD, the local node only synchronizes the chain with one selected remote node and
260    /// stops responding to most P2P requests.
261    pub ibd: bool,
262    /// Is ckb reached the assume_valid_target? If no assume_valid_target, this will be true.
263    pub assume_valid_target_reached: bool,
264    /// The assume_valid_target specified by ckb, if no assume_valid_target, this will be all zero.
265    pub assume_valid_target: Byte32,
266    /// Is ckb reached the min_chain_work?
267    pub min_chain_work_reached: bool,
268    /// This field acts as a security measure to ensure that a node only
269    /// synchronizes with other nodes that have a significant amount of
270    /// computational work invested in them, thereby preventing certain types
271    /// of attacks and ensuring network integrity. Only the mainnet uses a
272    /// hardcoded value for this field.
273    pub min_chain_work: Uint128,
274    /// This is the best known block number observed by the local node from the P2P network.
275    ///
276    /// The best here means that the block leads a chain which has the best known accumulated
277    /// difficulty.
278    ///
279    /// This can be used to estimate the synchronization progress. If this RPC returns B, and the
280    /// RPC `get_tip_block_number` returns T, the node has already synchronized T/B blocks.
281    pub best_known_block_number: BlockNumber,
282    /// This is timestamp of the same block described in `best_known_block_number`.
283    pub best_known_block_timestamp: Timestamp,
284    /// Count of orphan blocks the local node has downloaded.
285    ///
286    /// The local node downloads multiple blocks simultaneously but blocks must be connected
287    /// consecutively. If a descendant is downloaded before its ancestors, it becomes an orphan
288    /// block.
289    ///
290    /// If this number is too high, it indicates that block download has stuck at some block.
291    pub orphan_blocks_count: Uint64,
292    /// Count of downloading blocks.
293    pub inflight_blocks_count: Uint64,
294    /// The block number of current unverified tip block
295    pub unverified_tip_number: BlockNumber,
296    /// The block hash of current unverified tip block
297    pub unverified_tip_hash: H256,
298    /// The block number of current tip block
299    pub tip_number: BlockNumber,
300    /// The block hash of current tip block
301    pub tip_hash: H256,
302    /// The download scheduler's time analysis data, the fast is the 1/3 of the cut-off point, unit ms
303    pub fast_time: Uint64,
304    /// The download scheduler's time analysis data, the normal is the 4/5 of the cut-off point, unit ms
305    pub normal_time: Uint64,
306    /// The download scheduler's time analysis data, the low is the 9/10 of the cut-off point, unit ms
307    pub low_time: Uint64,
308}
ckb_jsonrpc_types/net.rs

ckb_jsonrpc_types/
net.rs
