diff --git a/crates/payload/basic/src/lib.rs b/crates/payload/basic/src/lib.rs index 16be06110..461325c6f 100644 --- a/crates/payload/basic/src/lib.rs +++ b/crates/payload/basic/src/lib.rs @@ -11,7 +11,7 @@ attr(deny(warnings, rust_2018_idioms), allow(dead_code, unused_variables)) ))] -//! reth basic payload job generator +//! A basic payload generator for reth. use crate::metrics::PayloadBuilderMetrics; use futures_core::ready; @@ -60,7 +60,7 @@ use tracing::{debug, trace}; mod metrics; -/// The [PayloadJobGenerator] that creates [BasicPayloadJob]s. +/// The [`PayloadJobGenerator`] that creates [`BasicPayloadJob`]s. pub struct BasicPayloadJobGenerator { /// The client that can interact with the chain. client: Client, diff --git a/crates/payload/builder/src/database.rs b/crates/payload/builder/src/database.rs index 78a25a1e0..c69f7bafa 100644 --- a/crates/payload/builder/src/database.rs +++ b/crates/payload/builder/src/database.rs @@ -10,7 +10,7 @@ use std::{ collections::{hash_map::Entry, HashMap}, }; -/// A container type that caches all [DatabaseRef] reads from an underlying [DatabaseRef]. +/// A container type that caches reads from an underlying [DatabaseRef]. /// /// This is intended to be used in conjunction with [CacheDB](reth_revm_primitives::db::CacheDB) /// during payload building which repeatedly accesses the same data. diff --git a/crates/payload/builder/src/lib.rs b/crates/payload/builder/src/lib.rs index fdc57c913..b1b6e8989 100644 --- a/crates/payload/builder/src/lib.rs +++ b/crates/payload/builder/src/lib.rs @@ -16,27 +16,30 @@ attr(deny(warnings, rust_2018_idioms), allow(dead_code, unused_variables)) ))] -//! This crate defines the abstractions to create and update payloads: -//! - [PayloadJobGenerator]: a type that knows how to create new jobs for creating payloads based -//! on [PayloadAttributes](reth_rpc_types::engine::PayloadAttributes). -//! - [PayloadJob]: a type that can yields (better) payloads over time. +//! This crate defines abstractions to create and update payloads (blocks): +//! - [`PayloadJobGenerator`]: a type that knows how to create new jobs for creating payloads based +//! on [`PayloadAttributes`](reth_rpc_types::engine::PayloadAttributes). +//! - [`PayloadJob`]: a type that yields (better) payloads over time. //! -//! This crate comes with the generic [PayloadBuilderService] responsible for managing payload jobs. +//! This crate comes with the generic [`PayloadBuilderService`] responsible for managing payload +//! jobs. //! //! ## Node integration //! -//! In a standard node the [PayloadBuilderService] sits downstream of the engine API or rather the -//! component that handles requests from the Beacon Node like `engine_forkchoiceUpdatedV1`. +//! In a standard node the [`PayloadBuilderService`] sits downstream of the engine API, or rather +//! the component that handles requests from the consensus layer like `engine_forkchoiceUpdatedV1`. +//! //! Payload building is enabled if the forkchoice update request contains payload attributes. -//! See also -//! If the forkchoice update request is VALID and contains payload attributes the -//! [PayloadBuilderService] will create a new [PayloadJob] via the [PayloadJobGenerator] and start -//! polling it until the payload is requested by the CL and the payload job is resolved: -//! [PayloadJob::resolve] +//! +//! See also [the engine API docs](https://github.com/ethereum/execution-apis/blob/6709c2a795b707202e93c4f2867fa0bf2640a84f/src/engine/shanghai.md#engine_forkchoiceupdatedv2) +//! If the forkchoice update request is `VALID` and contains payload attributes the +//! [`PayloadBuilderService`] will create a new [`PayloadJob`] via the given [`PayloadJobGenerator`] +//! and start polling it until the payload is requested by the CL and the payload job is resolved +//! (see [`PayloadJob::resolve`]). //! //! ## Example //! -//! A simple example of a [PayloadJobGenerator] that creates empty blocks: +//! A simple example of a [`PayloadJobGenerator`] that creates empty blocks: //! //! ``` //! use std::future::Future; diff --git a/crates/payload/builder/src/service.rs b/crates/payload/builder/src/service.rs index 67d6bbbaf..278beef6e 100644 --- a/crates/payload/builder/src/service.rs +++ b/crates/payload/builder/src/service.rs @@ -124,10 +124,10 @@ impl PayloadBuilderHandle { /// /// This type is an endless future that manages the building of payloads. /// -/// It tracks active payloads and their build jobs that run in the worker pool. +/// It tracks active payloads and their build jobs that run in a worker pool. /// -/// By design, this type relies entirely on the [PayloadJobGenerator] to create new payloads and -/// does know nothing about how to build them, itt just drives the payload jobs. +/// By design, this type relies entirely on the [`PayloadJobGenerator`] to create new payloads and +/// does know nothing about how to build them, it just drives their jobs to completion. #[must_use = "futures do nothing unless you `.await` or poll them"] pub struct PayloadBuilderService where @@ -141,7 +141,7 @@ where _service_tx: mpsc::UnboundedSender, /// Receiver half of the command channel. command_rx: UnboundedReceiverStream, - /// metrics for the payload builder service + /// Metrics for the payload builder service metrics: PayloadBuilderServiceMetrics, } diff --git a/crates/payload/builder/src/traits.rs b/crates/payload/builder/src/traits.rs index e855a20c8..4fddbebec 100644 --- a/crates/payload/builder/src/traits.rs +++ b/crates/payload/builder/src/traits.rs @@ -5,14 +5,15 @@ use std::{future::Future, sync::Arc}; /// A type that can build a payload. /// -/// This type is a Future that resolves when the job is done (e.g. timed out) or it failed. It's not -/// supposed to return the best payload built when it resolves instead [PayloadJob::best_payload] -/// should be used for that. +/// This type is a [`Future`] that resolves when the job is done (e.g. complete, timed out) or it +/// failed. It's not supposed to return the best payload built when it resolves, instead +/// [`PayloadJob::best_payload`] should be used for that. /// -/// A PayloadJob must always be prepared to return the best payload built so far to make there's a -/// valid payload to deliver to the CL, so it does not miss a slot, even if the payload is empty. +/// A `PayloadJob` must always be prepared to return the best payload built so far to ensure there +/// is a valid payload to deliver to the CL, so it does not miss a slot, even if the payload is +/// empty. /// -/// Note: A PayloadJob need to be cancel safe because it might be dropped after the CL has requested the payload via `engine_getPayloadV1`, See also +/// Note: A `PayloadJob` need to be cancel safe because it might be dropped after the CL has requested the payload via `engine_getPayloadV1` (see also [engine API docs](https://github.com/ethereum/execution-apis/blob/6709c2a795b707202e93c4f2867fa0bf2640a84f/src/engine/paris.md#engine_getpayloadv1)) pub trait PayloadJob: Future> + Send + Sync { /// Represents the future that resolves the block that's returned to the CL. type ResolvePayloadFuture: Future, PayloadBuilderError>> @@ -29,9 +30,11 @@ pub trait PayloadJob: Future> + Send + /// /// This is invoked on [`engine_getPayloadV2`](https://github.com/ethereum/execution-apis/blob/main/src/engine/shanghai.md#engine_getpayloadv2) and [`engine_getPayloadV1`](https://github.com/ethereum/execution-apis/blob/main/src/engine/paris.md#engine_getpayloadv1). /// - /// The timeout for returning the payload to the CL is 1s. - /// Ideally, future returned by this method must resolve in under 1s. Ideally this is the best - /// payload built so far or an empty block without transactions if nothing has been built yet. + /// The timeout for returning the payload to the CL is 1s, thus the future returned should + /// resolve in under 1 second. + /// + /// Ideally this is the best payload built so far, or an empty block without transactions, if + /// nothing has been built yet. /// /// According to the spec: /// > Client software MAY stop the corresponding build process after serving this call. @@ -39,9 +42,9 @@ pub trait PayloadJob: Future> + Send + /// It is at the discretion of the implementer whether the build job should be kept alive or /// terminated. /// - /// If this returns [KeepPayloadJobAlive::Yes] then the future the [PayloadJob] will be polled - /// once more, if this returns [KeepPayloadJobAlive::No] then the [PayloadJob] will be dropped - /// after this call + /// If this returns [`KeepPayloadJobAlive::Yes`], then the [`PayloadJob`] will be polled + /// once more. If this returns [`KeepPayloadJobAlive::No`] then the [`PayloadJob`] will be + /// dropped after this call. fn resolve(&mut self) -> (Self::ResolvePayloadFuture, KeepPayloadJobAlive); } @@ -59,15 +62,17 @@ pub enum KeepPayloadJobAlive { pub trait PayloadJobGenerator: Send + Sync { /// The type that manages the lifecycle of a payload. /// - /// This type is a Stream that yields better payloads. + /// This type is a future that yields better payloads. type Job: PayloadJob; - /// Creates the initial payload and a new [PayloadJob] that yields better payloads. + /// Creates the initial payload and a new [`PayloadJob`] that yields better payloads over time. /// /// This is called when the CL requests a new payload job via a fork choice update. /// - /// Note: this is expected to build a new (empty) payload without transactions, so it can be - /// returned directly. when asked for + /// # Note + /// + /// This is expected to initially build a new (empty) payload without transactions, so it can be + /// returned directly. fn new_payload_job( &self, attr: PayloadBuilderAttributes,