Crate reth_payload_builder

Source
Expand description

This crate defines abstractions to create and update payloads (blocks):

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, BlockExt};

/// 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(block.seal_slow()), U256::ZERO, None, 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§

Enums§

Traits§