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::task::{Context, Poll};
use reth_payload_builder::{EthBuiltPayload, KeepPayloadJobAlive, EthPayloadBuilderAttributes, PayloadJob, PayloadJobGenerator};
use reth_payload_builder::error::PayloadBuilderError;
use reth_primitives::{Block, Header, U256};

/// 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 payload = 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, payload.seal_slow(), U256::ZERO);
    Ok(payload)
}

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

fn resolve(&mut self) -> (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

• database
  Database adapters for payload building.
• error
  Error types emitted by types or implementations of this crate.
• 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

• Events
  Payload builder events.
• KeepPayloadJobAlive
  Whether the payload job should be kept alive or terminated after the payload was requested by the CL.

Traits

• PayloadJob
  A type that can build a payload.
• PayloadJobGenerator
  A type that knows how to create new jobs for creating payloads.