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

reth_payload_builder/
lib.rs
