Trait PayloadValidator 

pub trait PayloadValidator<Types>:
    Send
    + Sync
    + Unpin
    + 'static
where
    Types: PayloadTypes,
{
    type Block: Block;

    // Required method
    fn convert_payload_to_block(
        &self,
        payload: <Types as PayloadTypes>::ExecutionData,
    ) -> Result<SealedBlock<Self::Block>, NewPayloadError>;

    // Provided methods
    fn ensure_well_formed_payload(
        &self,
        payload: <Types as PayloadTypes>::ExecutionData,
    ) -> Result<RecoveredBlock<Self::Block>, NewPayloadError> { ... }
    fn validate_block_post_execution_with_hashed_state(
        &self,
        _state_updates: &HashedPostState,
        _block: &RecoveredBlock<Self::Block>,
    ) -> Result<(), ConsensusError> { ... }
    fn validate_payload_attributes_against_header(
        &self,
        attr: &<Types as PayloadTypes>::PayloadAttributes,
        header: &<Self::Block as Block>::Header,
    ) -> Result<(), InvalidPayloadAttributesError> { ... }
}

Available on crate feature node-api only.

Type that validates an ExecutionPayload.

This trait handles validation at the engine API boundary — converting payloads into blocks and validating payload attributes for block building.

Methods and when they’re used

• convert_payload_to_block: Used during engine_newPayload processing to decode the payload into a SealedBlock. Also used to validate payload structure during backfill buffering. In the engine tree, this runs concurrently with state setup on a background thread.

• ensure_well_formed_payload: Converts payload and recovers transaction signatures. Used when recovered senders are needed immediately.

• validate_payload_attributes_against_header: Enforced as part of the engine’s forkchoiceUpdated handling when payload attributes are provided. Gates whether a payload build job is started.

• validate_block_post_execution_with_hashed_state: Called after block execution in the engine’s payload validation pipeline. No-op on L1, used by L2s (e.g., OP Stack) for additional post-execution checks.

Relationship to consensus traits

This trait does NOT replace the consensus traits (Consensus, FullConsensus from reth-consensus). Those handle the actual consensus rule validation (header checks, pre/post-execution). This trait handles engine API-specific concerns: payload encoding/decoding and attribute validation.

Required Associated Types

type Block: Block

The block type used by the engine.

Required Methods

fn convert_payload_to_block( &self, payload: <Types as PayloadTypes>::ExecutionData, ) -> Result<SealedBlock<Self::Block>, NewPayloadError>

Converts the given payload into a sealed block without recovering signatures.

This function validates the payload and converts it into a SealedBlock which contains the block hash but does not perform signature recovery on transactions.

This is more efficient than Self::ensure_well_formed_payload when signature recovery is not needed immediately or will be performed later.

Implementers should ensure that the checks are done in the order that conforms with the engine-API specification.

Provided Methods

fn ensure_well_formed_payload( &self, payload: <Types as PayloadTypes>::ExecutionData, ) -> Result<RecoveredBlock<Self::Block>, NewPayloadError>

Ensures that the given payload does not violate any consensus rules that concern the block’s layout.

This function must convert the payload into the executable block and pre-validate its fields.

Implementers should ensure that the checks are done in the order that conforms with the engine-API specification.

fn validate_block_post_execution_with_hashed_state( &self, _state_updates: &HashedPostState, _block: &RecoveredBlock<Self::Block>, ) -> Result<(), ConsensusError>

Verifies payload post-execution w.r.t. hashed state updates.

fn validate_payload_attributes_against_header( &self, attr: &<Types as PayloadTypes>::PayloadAttributes, header: &<Self::Block as Block>::Header, ) -> Result<(), InvalidPayloadAttributesError>

Validates the payload attributes with respect to the header.

By default, this enforces that the payload attributes timestamp is greater than the timestamp according to:

7. Client software MUST ensure that payloadAttributes.timestamp is greater than timestamp of a block referenced by forkchoiceState.headBlockHash.

See also: https://github.com/ethereum/execution-apis/blob/main/src/engine/common.md#specification-1

Enforced as part of the engine’s forkchoiceUpdated handling when the consensus layer provides payload attributes. If this returns an error, the forkchoice state update itself is NOT rolled back, but no payload build job is started — the response includes INVALID_PAYLOAD_ATTRIBUTES.

Implementations on Foreign Types

impl<'a, Types, T> PayloadValidator<Types> for &'a T

where Types: PayloadTypes, T: 'a + PayloadValidator<Types> + ?Sized, &'a T: Send + Sync + Unpin + 'static,

type Block = <T as PayloadValidator<Types>>::Block

fn convert_payload_to_block( &self, payload: <Types as PayloadTypes>::ExecutionData, ) -> Result<SealedBlock<<&'a T as PayloadValidator<Types>>::Block>, NewPayloadError>

fn ensure_well_formed_payload( &self, payload: <Types as PayloadTypes>::ExecutionData, ) -> Result<RecoveredBlock<<&'a T as PayloadValidator<Types>>::Block>, NewPayloadError>

fn validate_block_post_execution_with_hashed_state( &self, _state_updates: &HashedPostState, _block: &RecoveredBlock<<&'a T as PayloadValidator<Types>>::Block>, ) -> Result<(), ConsensusError>

fn validate_payload_attributes_against_header( &self, attr: &<Types as PayloadTypes>::PayloadAttributes, header: &<<&'a T as PayloadValidator<Types>>::Block as Block>::Header, ) -> Result<(), InvalidPayloadAttributesError>

impl<Types, T> PayloadValidator<Types> for Arc<T>

where Types: PayloadTypes, T: PayloadValidator<Types> + ?Sized, Arc<T>: Send + Sync + Unpin + 'static,

type Block = <T as PayloadValidator<Types>>::Block

fn convert_payload_to_block( &self, payload: <Types as PayloadTypes>::ExecutionData, ) -> Result<SealedBlock<<Arc<T> as PayloadValidator<Types>>::Block>, NewPayloadError>

fn ensure_well_formed_payload( &self, payload: <Types as PayloadTypes>::ExecutionData, ) -> Result<RecoveredBlock<<Arc<T> as PayloadValidator<Types>>::Block>, NewPayloadError>

fn validate_block_post_execution_with_hashed_state( &self, _state_updates: &HashedPostState, _block: &RecoveredBlock<<Arc<T> as PayloadValidator<Types>>::Block>, ) -> Result<(), ConsensusError>

fn validate_payload_attributes_against_header( &self, attr: &<Types as PayloadTypes>::PayloadAttributes, header: &<<Arc<T> as PayloadValidator<Types>>::Block as Block>::Header, ) -> Result<(), InvalidPayloadAttributesError>

Implementors

impl<ChainSpec, Types> PayloadValidator<Types> for EthereumEngineValidator<ChainSpec>

where ChainSpec: EthChainSpec + EthereumHardforks + 'static, Types: PayloadTypes<ExecutionData = ExecutionData>,

type Block = Block<EthereumTxEnvelope<TxEip4844>>