Struct NodeBuilder

pub struct NodeBuilder<DB, ChainSpec> { /* private fields */ }

Declaratively construct a node.

NodeBuilder provides a builder-like interface for composing components of a node.

Order

Configuring a node starts out with a NodeConfig (this can be obtained from cli arguments for example) and then proceeds to configure the core static types of the node: NodeTypesWithEngine, these include the node’s primitive types and the node’s engine types.

Next all stateful components of the node are configured, these include all the components of the node that are downstream of those types, these include:

• The EVM and Executor configuration: ExecutorBuilder
• The transaction pool: PoolBuilder
• The network: NetworkBuilder
• The payload builder: PayloadBuilder

Once all the components are configured, the node is ready to be launched.

On launch the builder returns a fully type aware NodeHandle that has access to all the configured components and can interact with the node.

There are convenience functions for networks that come with a preset of types and components via the Node trait, see reth_node_ethereum::EthereumNode or reth_optimism_node::OpNode.

The NodeBuilder::node function configures the node’s types and components in one step.

Components

All components are configured with a NodeComponentsBuilder that is responsible for actually creating the node components during the launch process. The ComponentsBuilder is a general purpose implementation of the NodeComponentsBuilder trait that can be used to configure the executor, network, transaction pool and payload builder of the node. It enforces the correct order of configuration, for example the network and the payload builder depend on the transaction pool type that is configured first.

All builder traits are generic over the node types and are invoked with the BuilderContext that gives access to internals of the that are needed to configure the components. This include the original config, chain spec, the database provider and the task executor,

Hooks

Once all the components are configured, the builder can be used to set hooks that are run at specific points in the node’s lifecycle. This way custom services can be spawned before the node is launched NodeBuilderWithComponents::on_component_initialized, or once the rpc server(s) are launched NodeBuilderWithComponents::on_rpc_started. The NodeBuilderWithComponents::extend_rpc_modules can be used to inject custom rpc modules into the rpc server before it is launched. See also RpcContext All hooks accept a closure that is then invoked at the appropriate time in the node’s launch process.

Flow

The NodeBuilder is intended to sit behind a CLI that provides the necessary NodeConfig input: NodeBuilder::new

From there the builder is configured with the node’s types, components, and hooks, then launched with the WithLaunchContext::launch method. On launch all the builtin internals, such as the Database and its providers BlockchainProvider are initialized before the configured NodeComponentsBuilder is invoked with the BuilderContext to create the transaction pool, network, and payload builder components. When the RPC is configured, the corresponding hooks are invoked to allow for custom rpc modules to be injected into the rpc server: NodeBuilderWithComponents::extend_rpc_modules

Finally all components are created and all services are launched and a NodeHandle is returned that can be used to interact with the node: FullNode

The following diagram shows the flow of the node builder from CLI to a launched node.

graph TD; CLI::parse-->NodeCommand NodeCommand--execute-->NodeBuilder subgraph "Builder" NodeBuilder--"with_types"-->NodeBuilderT NodeBuilderT("NodeBuilder(Types)")--"with_components"-->NodeBuilderC NodeBuilderC("NodeBuilder(Types, Components)")--"extend_rpc_modules"-->NodeBuilderC NodeBuilderC--"on_rpc_started"-->NodeBuilderC end NodeBuilderC--"launch"-->launch subgraph launch database("database init")-->tree("blockchain tree init") tree--BuilderContext-->components{"build_components"} subgraph components ComponentsBuilder--"first creates"-->Pool Pool--"then creates"-->PayloadService Pool--"then creates"-->Network end components--"launch rpc"-->RpcContext RpcContext--invokes-->extend_rpc_modules RpcContext--invokes-->on_rpc_started end launch--"FullNode"-->NodeHandle

Internals

The node builder is fully type safe, it uses the NodeTypesWithEngine trait to enforce that all components are configured with the correct types. However the database types and with that the provider trait implementations are currently created by the builder itself during the launch process, hence the database type is not part of the NodeTypesWithEngine trait and the node’s components, that depend on the database, are configured separately. In order to have a nice trait that encapsulates the entire node the FullNodeComponents trait was introduced. This trait has convenient associated types for all the components of the node. After WithLaunchContext::launch the NodeHandle contains an instance of FullNode that implements the FullNodeComponents trait and has access to all the components of the node. Internally the node builder uses several generic adapter types that are then map to traits with associated types for ease of use.

Limitations

Currently the launch process is limited to ethereum nodes and requires all the components specified above. It also expects beacon consensus with the ethereum engine API that is configured by the builder itself during launch. This might change in the future.

Implementations

impl<ChainSpec> NodeBuilder<(), ChainSpec>

pub const fn new(config: NodeConfig<ChainSpec>) -> Self

Create a new NodeBuilder.

pub fn apply<F>(self, f: F) -> Self

where F: FnOnce(Self) -> Self,

Apply a function to the builder

pub fn apply_if<F>(self, cond: bool, f: F) -> Self

where F: FnOnce(Self) -> Self,

Apply a function to the builder, if the condition is true.

impl<DB, ChainSpec> NodeBuilder<DB, ChainSpec>

pub const fn config(&self) -> &NodeConfig<ChainSpec>

Returns a reference to the node builder’s config.

pub fn config_mut(&mut self) -> &mut NodeConfig<ChainSpec>

Returns a mutable reference to the node builder’s config.

impl<DB, ChainSpec: EthChainSpec> NodeBuilder<DB, ChainSpec>

pub fn with_database<D>(self, database: D) -> NodeBuilder<D, ChainSpec>

Configures the underlying database that the node will use.

pub const fn with_launch_context( self, task_executor: TaskExecutor, ) -> WithLaunchContext<Self>

Preconfigure the builder with the context to launch the node.

This provides the task executor and the data directory for the node.

pub fn testing_node( self, task_executor: TaskExecutor, ) -> WithLaunchContext<NodeBuilder<Arc<TempDatabase<DatabaseEnv>>, ChainSpec>>

Available on crate feature test-utils only.

Creates an ephemeral preconfigured node for testing purposes.

impl<DB, ChainSpec> NodeBuilder<DB, ChainSpec>

where DB: Database + DatabaseMetrics + DatabaseMetadata + Clone + Unpin + 'static, ChainSpec: EthChainSpec + EthereumHardforks,

pub fn with_types<T>(self) -> NodeBuilderWithTypes<RethFullAdapter<DB, T>>

where T: NodeTypesWithEngine<ChainSpec = ChainSpec>,

Configures the types of the node.

pub fn with_types_and_provider<T, P>( self, ) -> NodeBuilderWithTypes<FullNodeTypesAdapter<NodeTypesWithDBAdapter<T, DB>, P>>

where T: NodeTypesWithEngine<ChainSpec = ChainSpec>, P: FullProvider<NodeTypesWithDBAdapter<T, DB>>,

Configures the types of the node and the provider type that will be used by the node.

pub fn node<N>( self, node: N, ) -> NodeBuilderWithComponents<RethFullAdapter<DB, N>, N::ComponentsBuilder, N::AddOns>

where N: Node<RethFullAdapter<DB, N>, ChainSpec = ChainSpec>,

Preconfigures the node with a specific node implementation.

This is a convenience method that sets the node’s types and components in one call.

Layout

Note: Unable to compute type layout, possibly due to this type having generic parameters. Layout can only be computed for concrete, fully-instantiated types.