reth_network_api/
lib.rs

1//! Reth interface definitions and commonly used types for the reth-network crate.
2//!
3//! Provides abstractions for the reth-network crate.
4//!
5//! ## Feature Flags
6//!
7//! - `serde` (default): Enable serde support
8
9#![doc(
10    html_logo_url = "https://raw.githubusercontent.com/paradigmxyz/reth/main/assets/reth-docs.png",
11    html_favicon_url = "https://avatars0.githubusercontent.com/u/97369466?s=256",
12    issue_tracker_base_url = "https://github.com/paradigmxyz/reth/issues/"
13)]
14#![cfg_attr(docsrs, feature(doc_cfg, doc_auto_cfg))]
15
16pub mod downloaders;
17/// Network Error
18pub mod error;
19pub mod events;
20/// Implementation of network traits for that does nothing.
21pub mod noop;
22
23pub mod test_utils;
24use test_utils::PeersHandleProvider;
25
26pub use alloy_rpc_types_admin::EthProtocolInfo;
27pub use reth_network_p2p::{BlockClient, HeadersClient};
28pub use reth_network_types::{PeerKind, Reputation, ReputationChangeKind};
29
30pub use downloaders::BlockDownloaderProvider;
31pub use error::NetworkError;
32pub use events::{
33    DiscoveredEvent, DiscoveryEvent, NetworkEvent, NetworkEventListenerProvider, PeerRequest,
34    PeerRequestSender,
35};
36
37use reth_eth_wire_types::{
38    capability::Capabilities, Capability, DisconnectReason, EthVersion, NetworkPrimitives,
39    UnifiedStatus,
40};
41use reth_network_p2p::sync::NetworkSyncUpdater;
42use reth_network_peers::NodeRecord;
43use std::{future::Future, net::SocketAddr, sync::Arc, time::Instant};
44
45/// The `PeerId` type.
46pub type PeerId = alloy_primitives::B512;
47
48/// Helper trait that unifies network API needed to launch node.
49pub trait FullNetwork:
50    BlockDownloaderProvider<
51        Client: BlockClient<Block = <Self::Primitives as NetworkPrimitives>::Block>,
52    > + NetworkSyncUpdater
53    + NetworkInfo
54    + NetworkEventListenerProvider
55    + Peers
56    + PeersHandleProvider
57    + Clone
58    + Unpin
59    + 'static
60{
61}
62
63impl<T> FullNetwork for T where
64    T: BlockDownloaderProvider<
65            Client: BlockClient<Block = <Self::Primitives as NetworkPrimitives>::Block>,
66        > + NetworkSyncUpdater
67        + NetworkInfo
68        + NetworkEventListenerProvider
69        + Peers
70        + PeersHandleProvider
71        + Clone
72        + Unpin
73        + 'static
74{
75}
76
77/// Provides general purpose information about the network.
78#[auto_impl::auto_impl(&, Arc)]
79pub trait NetworkInfo: Send + Sync {
80    /// Returns the [`SocketAddr`] that listens for incoming connections.
81    fn local_addr(&self) -> SocketAddr;
82
83    /// Returns the current status of the network being ran by the local node.
84    fn network_status(&self) -> impl Future<Output = Result<NetworkStatus, NetworkError>> + Send;
85
86    /// Returns the chain id
87    fn chain_id(&self) -> u64;
88
89    /// Returns `true` if the network is undergoing sync.
90    fn is_syncing(&self) -> bool;
91
92    /// Returns `true` when the node is undergoing the very first Pipeline sync.
93    fn is_initially_syncing(&self) -> bool;
94}
95
96/// Provides general purpose information about Peers in the network.
97#[auto_impl::auto_impl(&, Arc)]
98pub trait PeersInfo: Send + Sync {
99    /// Returns how many peers the network is currently connected to.
100    ///
101    /// Note: this should only include established connections and _not_ ongoing attempts.
102    fn num_connected_peers(&self) -> usize;
103
104    /// Returns the Ethereum Node Record of the node.
105    fn local_node_record(&self) -> NodeRecord;
106
107    /// Returns the local ENR of the node.
108    fn local_enr(&self) -> enr::Enr<enr::secp256k1::SecretKey>;
109}
110
111/// Provides an API for managing the peers of the network.
112#[auto_impl::auto_impl(&, Arc)]
113pub trait Peers: PeersInfo {
114    /// Adds a peer to the peer set with TCP `SocketAddr`.
115    fn add_peer(&self, peer: PeerId, tcp_addr: SocketAddr) {
116        self.add_peer_kind(peer, PeerKind::Static, tcp_addr, None);
117    }
118
119    /// Adds a peer to the peer set with TCP and UDP `SocketAddr`.
120    fn add_peer_with_udp(&self, peer: PeerId, tcp_addr: SocketAddr, udp_addr: SocketAddr) {
121        self.add_peer_kind(peer, PeerKind::Static, tcp_addr, Some(udp_addr));
122    }
123
124    /// Adds a trusted [`PeerId`] to the peer set.
125    ///
126    /// This allows marking a peer as trusted without having to know the peer's address.
127    fn add_trusted_peer_id(&self, peer: PeerId);
128
129    /// Adds a trusted peer to the peer set with TCP `SocketAddr`.
130    fn add_trusted_peer(&self, peer: PeerId, tcp_addr: SocketAddr) {
131        self.add_peer_kind(peer, PeerKind::Trusted, tcp_addr, None);
132    }
133
134    /// Adds a trusted peer with TCP and UDP `SocketAddr` to the peer set.
135    fn add_trusted_peer_with_udp(&self, peer: PeerId, tcp_addr: SocketAddr, udp_addr: SocketAddr) {
136        self.add_peer_kind(peer, PeerKind::Trusted, tcp_addr, Some(udp_addr));
137    }
138
139    /// Adds a peer to the known peer set, with the given kind.
140    fn add_peer_kind(
141        &self,
142        peer: PeerId,
143        kind: PeerKind,
144        tcp_addr: SocketAddr,
145        udp_addr: Option<SocketAddr>,
146    );
147
148    /// Returns the rpc [`PeerInfo`] for all connected [`PeerKind::Trusted`] peers.
149    fn get_trusted_peers(
150        &self,
151    ) -> impl Future<Output = Result<Vec<PeerInfo>, NetworkError>> + Send {
152        self.get_peers_by_kind(PeerKind::Trusted)
153    }
154
155    /// Returns the rpc [`PeerInfo`] for all connected [`PeerKind::Basic`] peers.
156    fn get_basic_peers(&self) -> impl Future<Output = Result<Vec<PeerInfo>, NetworkError>> + Send {
157        self.get_peers_by_kind(PeerKind::Basic)
158    }
159
160    /// Returns the rpc [`PeerInfo`] for all connected peers with the given kind.
161    fn get_peers_by_kind(
162        &self,
163        kind: PeerKind,
164    ) -> impl Future<Output = Result<Vec<PeerInfo>, NetworkError>> + Send;
165
166    /// Returns the rpc [`PeerInfo`] for all connected peers.
167    fn get_all_peers(&self) -> impl Future<Output = Result<Vec<PeerInfo>, NetworkError>> + Send;
168
169    /// Returns the rpc [`PeerInfo`] for the given peer id.
170    ///
171    /// Returns `None` if the peer is not connected.
172    fn get_peer_by_id(
173        &self,
174        peer_id: PeerId,
175    ) -> impl Future<Output = Result<Option<PeerInfo>, NetworkError>> + Send;
176
177    /// Returns the rpc [`PeerInfo`] for the given peers if they are connected.
178    ///
179    /// Note: This only returns peers that are connected, unconnected peers are ignored but keeping
180    /// the order in which they were requested.
181    fn get_peers_by_id(
182        &self,
183        peer_ids: Vec<PeerId>,
184    ) -> impl Future<Output = Result<Vec<PeerInfo>, NetworkError>> + Send;
185
186    /// Removes a peer from the peer set that corresponds to given kind.
187    fn remove_peer(&self, peer: PeerId, kind: PeerKind);
188
189    /// Disconnect an existing connection to the given peer.
190    fn disconnect_peer(&self, peer: PeerId);
191
192    /// Disconnect an existing connection to the given peer using the provided reason
193    fn disconnect_peer_with_reason(&self, peer: PeerId, reason: DisconnectReason);
194
195    /// Connect to the given peer. NOTE: if the maximum number of outbound sessions is reached,
196    /// this won't do anything. See `reth_network::SessionManager::dial_outbound`.
197    fn connect_peer(&self, peer: PeerId, tcp_addr: SocketAddr) {
198        self.connect_peer_kind(peer, PeerKind::Static, tcp_addr, None)
199    }
200
201    /// Connects a peer to the known peer set, with the given kind.
202    fn connect_peer_kind(
203        &self,
204        peer: PeerId,
205        kind: PeerKind,
206        tcp_addr: SocketAddr,
207        udp_addr: Option<SocketAddr>,
208    );
209
210    /// Send a reputation change for the given peer.
211    fn reputation_change(&self, peer_id: PeerId, kind: ReputationChangeKind);
212
213    /// Get the reputation of a peer.
214    fn reputation_by_id(
215        &self,
216        peer_id: PeerId,
217    ) -> impl Future<Output = Result<Option<Reputation>, NetworkError>> + Send;
218}
219
220/// Info about an active peer session.
221#[derive(Debug, Clone)]
222pub struct PeerInfo {
223    /// Announced capabilities of the peer
224    pub capabilities: Arc<Capabilities>,
225    /// The identifier of the remote peer
226    pub remote_id: PeerId,
227    /// The client's name and version
228    pub client_version: Arc<str>,
229    /// The peer's enode
230    pub enode: String,
231    /// The peer's enr
232    pub enr: Option<String>,
233    /// The peer's address we're connected to
234    pub remote_addr: SocketAddr,
235    /// The local address of the connection
236    pub local_addr: Option<SocketAddr>,
237    /// The direction of the session
238    pub direction: Direction,
239    /// The negotiated eth version.
240    pub eth_version: EthVersion,
241    /// The Status message the peer sent for the `eth` handshake
242    pub status: Arc<UnifiedStatus>,
243    /// The timestamp when the session to that peer has been established.
244    pub session_established: Instant,
245    /// The peer's connection kind
246    pub kind: PeerKind,
247}
248
249/// The direction of the connection.
250#[derive(Debug, Copy, Clone, PartialEq, Eq)]
251pub enum Direction {
252    /// Incoming connection.
253    Incoming,
254    /// Outgoing connection to a specific node.
255    Outgoing(PeerId),
256}
257
258impl Direction {
259    /// Returns `true` if this an incoming connection.
260    pub const fn is_incoming(&self) -> bool {
261        matches!(self, Self::Incoming)
262    }
263
264    /// Returns `true` if this an outgoing connection.
265    pub const fn is_outgoing(&self) -> bool {
266        matches!(self, Self::Outgoing(_))
267    }
268}
269
270impl std::fmt::Display for Direction {
271    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
272        match self {
273            Self::Incoming => write!(f, "incoming"),
274            Self::Outgoing(_) => write!(f, "outgoing"),
275        }
276    }
277}
278
279/// The status of the network being ran by the local node.
280#[derive(Clone, Debug)]
281#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
282pub struct NetworkStatus {
283    /// The local node client version.
284    pub client_version: String,
285    /// The current ethereum protocol version
286    pub protocol_version: u64,
287    /// Information about the Ethereum Wire Protocol.
288    pub eth_protocol_info: EthProtocolInfo,
289    /// The list of supported capabilities and their versions.
290    pub capabilities: Vec<Capability>,
291}
reth_network_api/lib.rs

reth_network_api/
lib.rs
