Crate reth_payload_builder

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.
• PayloadJob: a type that yields (better) payloads over time.

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 consensus layer like engine_forkchoiceUpdatedV1.

Payload building is enabled if the forkchoice update request contains payload attributes.

See also the engine API docs 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:

use std::future::Future;
use std::pin::Pin;
use std::sync::Arc;
use std::task::{Context, Poll};
use alloy_consensus::Header;
use alloy_primitives::U256;
use reth_payload_builder::{EthBuiltPayload, PayloadBuilderError, KeepPayloadJobAlive, EthPayloadBuilderAttributes, PayloadJob, PayloadJobGenerator, PayloadKind};
use reth_primitives::{Block, SealedBlock};

/// The generator type that creates new jobs that builds empty blocks.
pub struct EmptyBlockPayloadJobGenerator;

impl PayloadJobGenerator for EmptyBlockPayloadJobGenerator {
    type Job = EmptyBlockPayloadJob;

/// This is invoked when the node receives payload attributes from the beacon node via `engine_forkchoiceUpdatedV1`
fn new_payload_job(&self, attr: EthPayloadBuilderAttributes) -> Result<Self::Job, PayloadBuilderError> {
        Ok(EmptyBlockPayloadJob{ attributes: attr,})
    }

}

/// A [PayloadJob] that builds empty blocks.
pub struct EmptyBlockPayloadJob {
  attributes: EthPayloadBuilderAttributes,
}

impl PayloadJob for EmptyBlockPayloadJob {
   type PayloadAttributes = EthPayloadBuilderAttributes;
   type ResolvePayloadFuture = futures_util::future::Ready<Result<EthBuiltPayload, PayloadBuilderError>>;
   type BuiltPayload = EthBuiltPayload;

fn best_payload(&self) -> Result<EthBuiltPayload, PayloadBuilderError> {
    // NOTE: some fields are omitted here for brevity
    let block = Block {
        header: Header {
            parent_hash: self.attributes.parent,
            timestamp: self.attributes.timestamp,
            beneficiary: self.attributes.suggested_fee_recipient,
            ..Default::default()
        },
        ..Default::default()
    };
    let payload = EthBuiltPayload::new(self.attributes.id, Arc::new(SealedBlock::seal_slow(block)), U256::ZERO, None);
    Ok(payload)
}

fn payload_attributes(&self) -> Result<EthPayloadBuilderAttributes, PayloadBuilderError> {
    Ok(self.attributes.clone())
}

fn resolve_kind(&mut self, _kind: PayloadKind) -> (Self::ResolvePayloadFuture, KeepPayloadJobAlive) {
       let payload = self.best_payload();
       (futures_util::future::ready(payload), KeepPayloadJobAlive::No)
    }
}

/// A [PayloadJob] is a future that's being polled by the `PayloadBuilderService`
impl Future for EmptyBlockPayloadJob {
 type Output = Result<(), PayloadBuilderError>;

fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
        Poll::Pending
    }
}

Feature Flags

• test-utils: Export utilities for testing

Modules

noop

A payload builder service task that does nothing.

test_utilstest-utils

Utils for testing purposes.

Structs

EthBuiltPayload

Contains the built payload.

EthPayloadBuilderAttributes

Container type for all components required to build a payload.

PayloadBuilderHandle

A communication channel to the PayloadBuilderService.

PayloadBuilderService

A service that manages payload building tasks.

PayloadId

And 8-byte identifier for an execution payload.

PayloadStore

A communication channel to the PayloadBuilderService that can retrieve payloads.

Enums

KeepPayloadJobAlive

Whether the payload job should be kept alive or terminated after the payload was requested by the CL.

PayloadBuilderError

Possible error variants during payload building.

PayloadKind

Determines how we should choose the payload to return.

PayloadServiceCommand

Message type for the PayloadBuilderService.

Traits

PayloadJob

A type that can build a payload.

PayloadJobGenerator

A type that knows how to create new jobs for creating payloads.