reth_payload_builder/
lib.rs

Help
1//! This crate defines abstractions to create and update payloads (blocks):
2//! - [`PayloadJobGenerator`]: a type that knows how to create new jobs for creating payloads based
3//!   on [`PayloadAttributes`](alloy_rpc_types::engine::PayloadAttributes).
4//! - [`PayloadJob`]: a type that yields (better) payloads over time.
5//!
6//! This crate comes with the generic [`PayloadBuilderService`] responsible for managing payload
7//! jobs.
8//!
9//! ## Node integration
10//!
11//! In a standard node the [`PayloadBuilderService`] sits downstream of the engine API, or rather
12//! the component that handles requests from the consensus layer like `engine_forkchoiceUpdatedV1`.
13//!
14//! Payload building is enabled if the forkchoice update request contains payload attributes.
15//!
16//! See also [the engine API docs](https://github.com/ethereum/execution-apis/blob/6709c2a795b707202e93c4f2867fa0bf2640a84f/src/engine/shanghai.md#engine_forkchoiceupdatedv2)
17//! If the forkchoice update request is `VALID` and contains payload attributes the
18//! [`PayloadBuilderService`] will create a new [`PayloadJob`] via the given [`PayloadJobGenerator`]
19//! and start polling it until the payload is requested by the CL and the payload job is resolved
20//! (see [`PayloadJob::resolve`]).
21//!
22//! ## Example
23//!
24//! A simple example of a [`PayloadJobGenerator`] that creates empty blocks:
25//!
26//! ```
27//! use std::future::Future;
28//! use std::pin::Pin;
29//! use std::sync::Arc;
30//! use std::task::{Context, Poll};
31//! use alloy_consensus::{Header, Block};
32//! use alloy_primitives::U256;
33//! use reth_payload_builder::{EthBuiltPayload, PayloadBuilderError, KeepPayloadJobAlive, EthPayloadBuilderAttributes, PayloadJob, PayloadJobGenerator, PayloadKind};
34//! use reth_primitives_traits::SealedBlock;
35//!
36//! /// The generator type that creates new jobs that builds empty blocks.
37//! pub struct EmptyBlockPayloadJobGenerator;
38//!
39//! impl PayloadJobGenerator for EmptyBlockPayloadJobGenerator {
40//!     type Job = EmptyBlockPayloadJob;
41//!
42//! /// This is invoked when the node receives payload attributes from the beacon node via `engine_forkchoiceUpdatedV1`
43//! fn new_payload_job(&self, attr: EthPayloadBuilderAttributes) -> Result<Self::Job, PayloadBuilderError> {
44//!         Ok(EmptyBlockPayloadJob{ attributes: attr,})
45//!     }
46//!
47//! }
48//!
49//! /// A [PayloadJob] that builds empty blocks.
50//! pub struct EmptyBlockPayloadJob {
51//!   attributes: EthPayloadBuilderAttributes,
52//! }
53//!
54//! impl PayloadJob for EmptyBlockPayloadJob {
55//!    type PayloadAttributes = EthPayloadBuilderAttributes;
56//!    type ResolvePayloadFuture = futures_util::future::Ready<Result<EthBuiltPayload, PayloadBuilderError>>;
57//!    type BuiltPayload = EthBuiltPayload;
58//!
59//! fn best_payload(&self) -> Result<EthBuiltPayload, PayloadBuilderError> {
60//!     // NOTE: some fields are omitted here for brevity
61//!     let block = Block {
62//!         header: Header {
63//!             parent_hash: self.attributes.parent,
64//!             timestamp: self.attributes.timestamp,
65//!             beneficiary: self.attributes.suggested_fee_recipient,
66//!             ..Default::default()
67//!         },
68//!         ..Default::default()
69//!     };
70//!     let payload = EthBuiltPayload::new(self.attributes.id, Arc::new(SealedBlock::seal_slow(block)), U256::ZERO, None);
71//!     Ok(payload)
72//! }
73//!
74//! fn payload_attributes(&self) -> Result<EthPayloadBuilderAttributes, PayloadBuilderError> {
75//!     Ok(self.attributes.clone())
76//! }
77//!
78//! fn resolve_kind(&mut self, _kind: PayloadKind) -> (Self::ResolvePayloadFuture, KeepPayloadJobAlive) {
79//!        let payload = self.best_payload();
80//!        (futures_util::future::ready(payload), KeepPayloadJobAlive::No)
81//!     }
82//! }
83//!
84//! /// A [PayloadJob] is a future that's being polled by the `PayloadBuilderService`
85//! impl Future for EmptyBlockPayloadJob {
86//!  type Output = Result<(), PayloadBuilderError>;
87//!
88//! fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
89//!         Poll::Pending
90//!     }
91//! }
92//! ```
93//!
94//! ## Feature Flags
95//!
96//! - `test-utils`: Export utilities for testing
97
98#![doc(
99    html_logo_url = "https://raw.githubusercontent.com/paradigmxyz/reth/main/assets/reth-docs.png",
100    html_favicon_url = "https://avatars0.githubusercontent.com/u/97369466?s=256",
101    issue_tracker_base_url = "https://github.com/paradigmxyz/reth/issues/"
102)]
103#![cfg_attr(not(test), warn(unused_crate_dependencies))]
104#![cfg_attr(docsrs, feature(doc_cfg, doc_auto_cfg))]
105
106mod metrics;
107mod service;
108mod traits;
109
110pub mod noop;
111
112#[cfg(any(test, feature = "test-utils"))]
113pub mod test_utils;
114
115pub use alloy_rpc_types::engine::PayloadId;
116pub use reth_payload_builder_primitives::PayloadBuilderError;
117pub use reth_payload_primitives::PayloadKind;
118pub use service::{
119    PayloadBuilderHandle, PayloadBuilderService, PayloadServiceCommand, PayloadStore,
120};
121pub use traits::{KeepPayloadJobAlive, PayloadJob, PayloadJobGenerator};
122
123// re-export the Ethereum engine primitives for convenience
124#[doc(inline)]
125pub use reth_ethereum_engine_primitives::{EthBuiltPayload, EthPayloadBuilderAttributes};
reth_payload_builder/lib.rs

reth_payload_builder/
lib.rs
