docs: more node-builder docs (#7034)

crates/node-builder/Cargo.toml

@@ -6,6 +6,7 @@ rust-version.workspace = true
 license.workspace = true
 homepage.workspace = true
 repository.workspace = true
+readme = "README.md"
 
 [lints]
 workspace = true

crates/node-builder/README.md

@@ -0,0 +1,7 @@
+## reth-node-builder
+
+A declarative way to configure a reth ethereum node.
+
+### Examples
+
+The [examples](../../examples) folder contains various examples of how to use the builder to configure a reth node.

crates/node-builder/src/builder.rs

@@ -66,12 +66,14 @@ type RethFullAdapter<DB, N> =
 /// [`NodeBuilder`] provides a [builder-like interface][builder] for composing
 /// components of a node.
 ///
-/// Configuring a node starts out with a [`NodeConfig`] and then proceeds to configure the core
-/// static types of the node: [NodeTypes], these include the node's primitive types and the node's
-/// engine types.
+/// ## 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: [NodeTypes], these
+/// include the node's primitive types and the node's engine types.
 ///
 /// Next all stateful components of the node are configured, these include the
-/// [ConfigureEvm](reth_node_api::evm::ConfigureEvm), the database [Database] and finally all the
+/// [ConfigureEvm](reth_node_api::evm::ConfigureEvm), the database [Database] and all the
 /// components of the node that are downstream of those types, these include:
 ///
 ///  - The transaction pool: [PoolBuilder]
@@ -88,6 +90,48 @@ type RethFullAdapter<DB, N> =
 ///
 /// 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
+/// 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 [NodeBuilder::on_component_initialized], or once the rpc server(s) are launched
+/// [NodeBuilder::on_rpc_started]. The [NodeBuilder::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.
+///
+/// ## Internals
+///
+/// The node builder is fully type safe, it uses the [NodeTypes] 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 [NodeTypes] 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 [NodeBuilder::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 expect beacon consensus with the ethereum engine API that is configured
+/// by the builder itself during launch. This might change in the future.
+///
 /// [builder]: https://doc.rust-lang.org/1.0.0/style/ownership/builders.html
 pub struct NodeBuilder<DB, State> {
     /// All settings for how the node should be configured.