Skip to main content
netspecsEthereum networking

4.5.3.Payload validation

Stage
In progress
Version
Sources
engine/paris.mde5d1bb6engine/shanghai.mde5d1bb6engine/cancun.mde5d1bb6engine/prague.mde5d1bb6engine/amsterdam.mde5d1bb6
Related
Block access list sidecarsePBS envelopesOptional execution proofsPayload chunkingFork choice and payloadsBlock importReorganization

The consensus client submits a received execution payload through engine_newPayload. The execution client returns PayloadStatusV1.

Status values

VALID means the payload and its ancestors are valid. INVALID means the payload is invalid. SYNCING means the client lacks data needed to decide. ACCEPTED means it accepted the payload for later processing.

latestValidHash identifies the last valid execution ancestor when known. validationError may explain an invalid result but is not a stable machine interface.

The active engine_newPayloadV* method returns INVALID, not INVALID_BLOCK_HASH, when the supplied execution block hash does not match the payload.

Wire surface

The valid method is engine_newPayloadV4.

Consensus response

The consensus client can import a VALID payload normally. It keeps a SYNCING or ACCEPTED block optimistic and must not finalize it before validation. Payload validity is idempotent: a payload that is VALID or INVALID must not switch to the other state on a later validation pass. For INVALID, it removes the invalid branch from consideration and uses latestValidHash to find the valid boundary.

Failure handling

Invalid parameters, unsupported fork, and transport failure are not payload validity results. The consensus client retries a timeout when needed. It treats conflicting execution-client answers as a local safety fault and does not guess which branch is valid.

Design rationale

The status model keeps invalid payloads separate from payloads that the execution client cannot validate yet.