The consensus client sends the execution head, safe block, and finalized block
through engine_forkchoiceUpdated. It may attach payload attributes to start a
local payload build. engine_getPayload retrieves that build.
Fork-choice state
ForkchoiceStateV1 contains headBlockHash, safeBlockHash, and
finalizedBlockHash. Zero means that the safe or finalized block is not yet
known. safeBlockHash must be the head or one of its ancestors. The execution
client rejects an inconsistent state with -38002 and may return -38006 when
the requested reorganization is too deep. An unknown head or a head whose
validation data is missing returns a SYNCING payload status. A zero safe or
finalized hash is allowed until the transition block is finalized.
Merge build methods
The valid methods are engine_forkchoiceUpdatedV1 and
engine_getPayloadV1.
Build lifecycle
When the fork-choice state is valid, the execution client applies it before it
processes payload attributes. Valid attributes start a local build and return
an eight-byte payload ID. The ID names short-lived build state. The consensus
client may call engine_getPayload until its proposal deadline. An unknown or
expired ID gives -38001; invalid attributes give -38003, and a timestamp for
an unsupported fork gives -38005.
The consensus client validates the returned timestamp, parent, fee recipient, and every field present in the selected payload version before it uses the payload. This includes withdrawals, blob data, execution requests, or block access lists only when that version defines the field.
Failure handling
Wrong fork timing gives unsupported fork. Bad attributes give invalid payload attributes. A timeout does not prove that the execution client stopped the build. The consensus client can retry or use a separate valid builder path.
Design rationale
Fork choice and payload building share one call so the execution client builds on the exact head that the consensus client selected.