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

reth_network_api/
lib.rs
