reth_payload_builder/
lib.rs

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 payload_timestamp(&self) -> Result<u64, PayloadBuilderError> {
79//!     Ok(self.attributes.timestamp)
80//! }
81//!
82//! fn resolve_kind(&mut self, _kind: PayloadKind) -> (Self::ResolvePayloadFuture, KeepPayloadJobAlive) {
83//!        let payload = self.best_payload();
84//!        (futures_util::future::ready(payload), KeepPayloadJobAlive::No)
85//!     }
86//! }
87//!
88//! /// A [PayloadJob] is a future that's being polled by the `PayloadBuilderService`
89//! impl Future for EmptyBlockPayloadJob {
90//!  type Output = Result<(), PayloadBuilderError>;
91//!
92//! fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
93//!         Poll::Pending
94//!     }
95//! }
96//! ```
97//!
98//! ## Feature Flags
99//!
100//! - `test-utils`: Export utilities for testing
101
102#![doc(
103    html_logo_url = "https://raw.githubusercontent.com/paradigmxyz/reth/main/assets/reth-docs.png",
104    html_favicon_url = "https://avatars0.githubusercontent.com/u/97369466?s=256",
105    issue_tracker_base_url = "https://github.com/paradigmxyz/reth/issues/"
106)]
107#![cfg_attr(not(test), warn(unused_crate_dependencies))]
108#![cfg_attr(docsrs, feature(doc_cfg, doc_auto_cfg))]
109
110mod metrics;
111mod service;
112mod traits;
113
114pub mod noop;
115
116#[cfg(any(test, feature = "test-utils"))]
117pub mod test_utils;
118
119pub use alloy_rpc_types::engine::PayloadId;
120pub use reth_payload_builder_primitives::PayloadBuilderError;
121pub use reth_payload_primitives::PayloadKind;
122pub use service::{
123    PayloadBuilderHandle, PayloadBuilderService, PayloadServiceCommand, PayloadStore,
124};
125pub use traits::{KeepPayloadJobAlive, PayloadJob, PayloadJobGenerator};
126
127// re-export the Ethereum engine primitives for convenience
128#[doc(inline)]
129pub use reth_ethereum_engine_primitives::{
130    BlobSidecars, EthBuiltPayload, EthPayloadBuilderAttributes,
131};
reth_payload_builder/lib.rs

reth_payload_builder/
lib.rs
