reth_node_api/node.rs
1//! Traits for configuring a node.
2
3use crate::PayloadTypes;
4use alloy_rpc_types_engine::JwtSecret;
5use reth_basic_payload_builder::PayloadBuilder;
6use reth_consensus::{ConsensusError, FullConsensus};
7use reth_db_api::{database_metrics::DatabaseMetrics, Database};
8use reth_engine_primitives::{BeaconConsensusEngineEvent, BeaconConsensusEngineHandle};
9use reth_evm::ConfigureEvm;
10use reth_network_api::FullNetwork;
11use reth_node_core::node_config::NodeConfig;
12use reth_node_types::{NodeTypes, NodeTypesWithDBAdapter, TxTy};
13use reth_payload_builder::PayloadBuilderHandle;
14use reth_provider::FullProvider;
15use reth_tasks::TaskExecutor;
16use reth_tokio_util::EventSender;
17use reth_transaction_pool::{PoolTransaction, TransactionPool};
18use std::{fmt::Debug, future::Future, marker::PhantomData};
19
20/// A helper trait that is downstream of the [`NodeTypes`] trait and adds stateful
21/// components to the node.
22///
23/// Its types are configured by node internally and are not intended to be user configurable.
24pub trait FullNodeTypes: Clone + Debug + Send + Sync + Unpin + 'static {
25 /// Node's types with the database.
26 type Types: NodeTypes;
27 /// Underlying database type used by the node to store and retrieve data.
28 type DB: Database + DatabaseMetrics + Clone + Unpin + 'static;
29 /// The provider type used to interact with the node.
30 type Provider: FullProvider<NodeTypesWithDBAdapter<Self::Types, Self::DB>>;
31}
32
33/// An adapter type that adds the builtin provider type to the user configured node types.
34#[derive(Clone, Debug)]
35pub struct FullNodeTypesAdapter<Types, DB, Provider>(PhantomData<(Types, DB, Provider)>);
36
37impl<Types, DB, Provider> FullNodeTypes for FullNodeTypesAdapter<Types, DB, Provider>
38where
39 Types: NodeTypes,
40 DB: Database + DatabaseMetrics + Clone + Unpin + 'static,
41 Provider: FullProvider<NodeTypesWithDBAdapter<Types, DB>>,
42{
43 type Types = Types;
44 type DB = DB;
45 type Provider = Provider;
46}
47
48/// Helper trait to bound [`PayloadBuilder`] to the node's engine types.
49pub trait PayloadBuilderFor<N: NodeTypes>:
50 PayloadBuilder<
51 Attributes = <N::Payload as PayloadTypes>::PayloadBuilderAttributes,
52 BuiltPayload = <N::Payload as PayloadTypes>::BuiltPayload,
53>
54{
55}
56
57impl<T, N: NodeTypes> PayloadBuilderFor<N> for T where
58 T: PayloadBuilder<
59 Attributes = <N::Payload as PayloadTypes>::PayloadBuilderAttributes,
60 BuiltPayload = <N::Payload as PayloadTypes>::BuiltPayload,
61 >
62{
63}
64
65/// Encapsulates all types and components of the node.
66pub trait FullNodeComponents: FullNodeTypes + Clone + 'static {
67 /// The transaction pool of the node.
68 type Pool: TransactionPool<Transaction: PoolTransaction<Consensus = TxTy<Self::Types>>> + Unpin;
69
70 /// The node's EVM configuration, defining settings for the Ethereum Virtual Machine.
71 type Evm: ConfigureEvm<Primitives = <Self::Types as NodeTypes>::Primitives>;
72
73 /// The consensus type of the node.
74 type Consensus: FullConsensus<<Self::Types as NodeTypes>::Primitives, Error = ConsensusError>
75 + Clone
76 + Unpin
77 + 'static;
78
79 /// Network API.
80 type Network: FullNetwork;
81
82 /// Returns the transaction pool of the node.
83 fn pool(&self) -> &Self::Pool;
84
85 /// Returns the node's evm config.
86 fn evm_config(&self) -> &Self::Evm;
87
88 /// Returns the node's consensus type.
89 fn consensus(&self) -> &Self::Consensus;
90
91 /// Returns the handle to the network
92 fn network(&self) -> &Self::Network;
93
94 /// Returns the handle to the payload builder service handling payload building requests from
95 /// the engine.
96 fn payload_builder_handle(&self) -> &PayloadBuilderHandle<<Self::Types as NodeTypes>::Payload>;
97
98 /// Returns the provider of the node.
99 fn provider(&self) -> &Self::Provider;
100
101 /// Returns an executor handle to spawn tasks.
102 ///
103 /// This can be used to spawn critical, blocking tasks or register tasks that should be
104 /// terminated gracefully. See also [`TaskSpawner`](reth_tasks::TaskSpawner).
105 fn task_executor(&self) -> &TaskExecutor;
106}
107
108/// Context passed to [`NodeAddOns::launch_add_ons`],
109#[derive(Debug, Clone)]
110pub struct AddOnsContext<'a, N: FullNodeComponents> {
111 /// Node with all configured components.
112 pub node: N,
113 /// Node configuration.
114 pub config: &'a NodeConfig<<N::Types as NodeTypes>::ChainSpec>,
115 /// Handle to the beacon consensus engine.
116 pub beacon_engine_handle: BeaconConsensusEngineHandle<<N::Types as NodeTypes>::Payload>,
117 /// Notification channel for engine API events
118 pub engine_events: EventSender<BeaconConsensusEngineEvent<<N::Types as NodeTypes>::Primitives>>,
119 /// JWT secret for the node.
120 pub jwt_secret: JwtSecret,
121}
122
123/// Customizable node add-on types.
124///
125/// This trait defines the interface for extending a node with additional functionality beyond
126/// the core [`FullNodeComponents`]. It provides a way to launch supplementary services such as
127/// RPC servers, monitoring, external integrations, or any custom functionality that builds on
128/// top of the core node components.
129///
130/// ## Purpose
131///
132/// The `NodeAddOns` trait serves as an extension point in the node builder architecture,
133/// allowing developers to:
134/// - Define custom services that run alongside the main node
135/// - Access all node components and configuration during initialization
136/// - Return a handle for managing the launched services (e.g. handle to rpc server)
137///
138/// ## How it fits into `NodeBuilder`
139///
140/// In the node builder pattern, add-ons are the final layer that gets applied after all core
141/// components are configured and started. The builder flow typically follows:
142///
143/// 1. Configure [`NodeTypes`] (chain spec, database types, etc.)
144/// 2. Build [`FullNodeComponents`] (consensus, networking, transaction pool, etc.)
145/// 3. Launch [`NodeAddOns`] with access to all components via [`AddOnsContext`]
146///
147/// ## Primary Use Case
148///
149/// The primary use of this trait is to launch RPC servers that provide external API access to
150/// the node. For Ethereum nodes, this typically includes two main servers: the regular RPC
151/// server (HTTP/WS/IPC) that handles user requests and the authenticated Engine API server
152/// that communicates with the consensus layer. The returned handle contains the necessary
153/// endpoints and control mechanisms for these servers, allowing the node to serve JSON-RPC
154/// requests and participate in consensus. While RPC is the main use case, the trait is
155/// intentionally flexible to support other kinds of add-ons such as monitoring, indexing, or
156/// custom protocol extensions.
157///
158/// ## Context Access
159///
160/// The [`AddOnsContext`] provides access to:
161/// - All node components via the `node` field
162/// - Node configuration
163/// - Engine API handles for consensus layer communication
164/// - JWT secrets for authenticated endpoints
165///
166/// This ensures add-ons can integrate deeply with the node while maintaining clean separation
167/// of concerns.
168pub trait NodeAddOns<N: FullNodeComponents>: Send {
169 /// Handle to add-ons.
170 ///
171 /// This type is returned by [`launch_add_ons`](Self::launch_add_ons) and represents a
172 /// handle to the launched services. It must be `Clone` to allow multiple components to
173 /// hold references and should provide methods to interact with the running services.
174 ///
175 /// For RPC add-ons, this typically includes:
176 /// - Server handles to access local addresses and shutdown methods
177 /// - RPC module registry for runtime inspection of available methods
178 /// - Configured middleware and transport-specific settings
179 /// - For Engine API implementations, this also includes handles for consensus layer
180 /// communication
181 type Handle: Send + Sync + Clone;
182
183 /// Configures and launches the add-ons.
184 ///
185 /// This method is called once during node startup after all core components are initialized.
186 /// It receives an [`AddOnsContext`] that provides access to:
187 ///
188 /// - The fully configured node with all its components
189 /// - Node configuration for reading settings
190 /// - Engine API handles for consensus layer communication
191 /// - JWT secrets for setting up authenticated endpoints (if any).
192 ///
193 /// The implementation should:
194 /// 1. Use the context to configure the add-on services
195 /// 2. Launch any background tasks using the node's task executor
196 /// 3. Return a handle that allows interaction with the launched services
197 ///
198 /// # Errors
199 ///
200 /// This method may fail if the add-ons cannot be properly configured or launched,
201 /// for example due to port binding issues or invalid configuration.
202 fn launch_add_ons(
203 self,
204 ctx: AddOnsContext<'_, N>,
205 ) -> impl Future<Output = eyre::Result<Self::Handle>> + Send;
206}
207
208impl<N: FullNodeComponents> NodeAddOns<N> for () {
209 type Handle = ();
210
211 async fn launch_add_ons(self, _components: AddOnsContext<'_, N>) -> eyre::Result<Self::Handle> {
212 Ok(())
213 }
214}