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::B256;
33//! use reth_payload_builder::PayloadId;
34//! use alloy_primitives::U256;
35//! use reth_payload_builder::{EthBuiltPayload, PayloadBuilderError, KeepPayloadJobAlive, PayloadJob, PayloadJobGenerator, PayloadKind};
36//! use reth_primitives_traits::SealedBlock;
37//! use alloy_rpc_types::engine::PayloadAttributes;
38//! use reth_payload_builder::BuildNewPayload;
39//!
40//! /// The generator type that creates new jobs that builds empty blocks.
41//! pub struct EmptyBlockPayloadJobGenerator;
42//!
43//! impl PayloadJobGenerator for EmptyBlockPayloadJobGenerator {
44//!     type Job = EmptyBlockPayloadJob;
45//!
46//! /// This is invoked when the node receives payload attributes from the beacon node via `engine_forkchoiceUpdatedV1`
47//! fn new_payload_job(&self, input: BuildNewPayload<PayloadAttributes>, _id: PayloadId) -> Result<Self::Job, PayloadBuilderError> {
48//!         Ok(EmptyBlockPayloadJob{ attributes: input.attributes, parent: input.parent_hash })
49//!     }
50//!
51//! }
52//!
53//! /// A [PayloadJob] that builds empty blocks.
54//! pub struct EmptyBlockPayloadJob {
55//!   attributes: PayloadAttributes,
56//!   parent: B256,
57//! }
58//!
59//! impl PayloadJob for EmptyBlockPayloadJob {
60//!    type PayloadAttributes = PayloadAttributes;
61//!    type ResolvePayloadFuture = futures_util::future::Ready<Result<EthBuiltPayload, PayloadBuilderError>>;
62//!    type BuiltPayload = EthBuiltPayload;
63//!
64//! fn best_payload(&self) -> Result<EthBuiltPayload, PayloadBuilderError> {
65//!     // NOTE: some fields are omitted here for brevity
66//!     let block = Block {
67//!         header: Header {
68//!             parent_hash: self.parent,
69//!             timestamp: self.attributes.timestamp,
70//!             beneficiary: self.attributes.suggested_fee_recipient,
71//!             ..Default::default()
72//!         },
73//!         ..Default::default()
74//!     };
75//!     let payload = EthBuiltPayload::new(Arc::new(SealedBlock::seal_slow(block)), U256::ZERO, None, None);
76//!     Ok(payload)
77//! }
78//!
79//! fn payload_attributes(&self) -> Result<PayloadAttributes, PayloadBuilderError> {
80//!     Ok(self.attributes.clone())
81//! }
82//!
83//! fn payload_timestamp(&self) -> Result<u64, PayloadBuilderError> {
84//!     Ok(self.attributes.timestamp)
85//! }
86//!
87//! fn resolve_kind(&mut self, _kind: PayloadKind) -> (Self::ResolvePayloadFuture, KeepPayloadJobAlive) {
88//!        let payload = self.best_payload();
89//!        (futures_util::future::ready(payload), KeepPayloadJobAlive::No)
90//!     }
91//! }
92//!
93//! /// A [PayloadJob] is a future that's being polled by the `PayloadBuilderService`
94//! impl Future for EmptyBlockPayloadJob {
95//!  type Output = Result<(), PayloadBuilderError>;
96//!
97//! fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
98//!         Poll::Pending
99//!     }
100//! }
101//! ```
102//!
103//! ## Feature Flags
104//!
105//! - `test-utils`: Export utilities for testing
106
107#![doc(
108    html_logo_url = "https://raw.githubusercontent.com/paradigmxyz/reth/main/assets/reth-docs.png",
109    html_favicon_url = "https://avatars0.githubusercontent.com/u/97369466?s=256",
110    issue_tracker_base_url = "https://github.com/paradigmxyz/reth/issues/"
111)]
112#![cfg_attr(not(test), warn(unused_crate_dependencies))]
113#![cfg_attr(docsrs, feature(doc_cfg))]
114
115mod metrics;
116mod service;
117mod traits;
118
119pub mod noop;
120
121#[cfg(any(test, feature = "test-utils"))]
122pub mod test_utils;
123
124pub use alloy_rpc_types::engine::PayloadId;
125pub use reth_payload_builder_primitives::PayloadBuilderError;
126pub use reth_payload_primitives::PayloadKind;
127pub use service::{
128    BuildNewPayload, PayloadBuilderHandle, PayloadBuilderService, PayloadServiceCommand,
129    PayloadStore,
130};
131pub use traits::{KeepPayloadJobAlive, PayloadJob, PayloadJobGenerator};
132
133// re-export the Ethereum engine primitives for convenience
134#[doc(inline)]
135pub use reth_ethereum_engine_primitives::{BlobSidecars, EthBuiltPayload};
reth_payload_builder/lib.rs

reth_payload_builder/
lib.rs
