Skip to content

Conversation

tersec
Copy link
Contributor

@tersec tersec commented Apr 19, 2025

Several aspects of the engine API require encoding null values explicitly rather than implicitly.

https://github.com/ethereum/execution-apis/blob/v1.0.0-beta.4/src/engine/common.md#errors

Each error returns a null data value, except -32000 which returns the data object with a err member that explains the error encountered.

https://github.com/ethereum/execution-apis/blob/v1.0.0-beta.4/src/engine/paris.md#payload-validation

  • If validation fails, the response MUST contain {status: INVALID, latestValidHash: validHash} where validHash MUST be:
  • The block hash of the ancestor of the invalid payload satisfying the following two conditions:
    • It is fully validated and deemed VALID
    • Any other ancestor of the invalid payload with a higher blockNumber is INVALID
  • 0x0000000000000000000000000000000000000000000000000000000000000000 if the above conditions are satisfied by a PoW block.
  • null if client software cannot determine the ancestor of the invalid
    payload satisfying the above conditions.

https://github.com/ethereum/execution-apis/blob/v1.0.0-beta.4/src/engine/paris.md#specification

  1. Client software MUST respond to this method call in the following way:
  • {status: INVALID_BLOCK_HASH, latestValidHash: null, validationError: errorMessage | null} if the blockHash validation has failed
  • {status: INVALID, latestValidHash: 0x0000000000000000000000000000000000000000000000000000000000000000, validationError: errorMessage | null} if terminal block conditions are not satisfied
  • {status: SYNCING, latestValidHash: null, validationError: null} if requisite data for the payload's acceptance or validation is missing
  • with the payload status obtained from the Payload validation process if the payload has been fully validated while processing the call
  • {status: ACCEPTED, latestValidHash: null, validationError: null} if the following conditions are met:
    • the blockHash of the payload is valid
    • the payload doesn't extend the canonical chain
    • the payload hasn't been fully validated
    • ancestors of a payload are known and comprise a well-formed chain.

https://github.com/ethereum/execution-apis/blob/v1.0.0-beta.4/src/engine/paris.md#specification-1

  1. Client software MAY skip an update of the forkchoice state and MUST NOT begin a payload build process if forkchoiceState.headBlockHash references a VALID ancestor of the head of canonical chain, i.e. the ancestor passed payload validation process and deemed VALID. In the case of such an event, client software MUST return {payloadStatus: {status: VALID, latestValidHash: forkchoiceState.headBlockHash, validationError: null}, payloadId: null}.

...

  1. Client software MUST respond to this method call in the following way:
  • {payloadStatus: {status: SYNCING, latestValidHash: null, validationError: null}, payloadId: null} if forkchoiceState.headBlockHash references an unknown payload or a payload that can't be validated because requisite data for the validation is missing
  • {payloadStatus: {status: INVALID, latestValidHash: validHash, validationError: errorMessage | null}, payloadId: null} obtained from the Payload validation process if the payload is deemed INVALID
  • {payloadStatus: {status: INVALID, latestValidHash: 0x0000000000000000000000000000000000000000000000000000000000000000, validationError: errorMessage | null}, payloadId: null} obtained either from the Payload validation process or as a result of validating a terminal PoW block referenced by forkchoiceState.headBlockHash
  • {payloadStatus: {status: VALID, latestValidHash: forkchoiceState.headBlockHash, validationError: null}, payloadId: null} if the payload is deemed VALID and a build process hasn't been started
  • {payloadStatus: {status: VALID, latestValidHash: forkchoiceState.headBlockHash, validationError: null}, payloadId: buildProcessId} if the payload is deemed VALID and the build process has begun

https://github.com/ethereum/execution-apis/blob/v1.0.0-beta.4/src/engine/shanghai.md#specification

  1. Client software MUST return {status: INVALID, latestValidHash: null, validationError: errorMessage | null} if the blockHash validation has failed.

https://github.com/ethereum/execution-apis/blob/v1.0.0-beta.4/src/engine/shanghai.md#specification-3

  1. Client software MUST place responses in the order given in the request, using null for any missing blocks. For instance, if the request is [A.block_hash, B.block_hash, C.block_hash] and client software has data of payloads A and C, but doesn't have data of B, the response MUST be [A.body, null, C.body].

...

  1. Client software MUST set withdrawals field to null for bodies of pre-Shanghai blocks.

https://github.com/ethereum/execution-apis/blob/v1.0.0-beta.4/src/engine/shanghai.md#specification-4

  1. Client software MUST place null in the response array for unavailable blocks which numbers are lower than a number of the latest known block. Client software MUST NOT return trailing null values if the request extends past the current latest known block. Execution Layer client software is expected to download and carry the full block history until EIP-4444 or a similar proposal takes into effect. Consider the following response examples:

    • [B1.body, B2.body, ..., Bn.body] -- entire requested range is filled with block bodies,
    • [null, null, B3.body, ..., Bn.body] -- first two blocks are unavailable (either pruned or not yet downloaded),
    • [null, null, ..., null] -- requested range is behind the latest known block and all blocks are unavailable,
    • [B1.body, B2.body, B3.body, B4.body] -- B4 is the latest known block and trailing null values are trimmed,
    • [] -- entire requested range is beyond the latest known block,
    • [null, null, B3.body, B4.body] -- first two blocks are unavailable, B4 is the latest known block.
  2. Client software MUST set withdrawals field to null for bodies of pre-Shanghai blocks.

https://github.com/ethereum/execution-apis/blob/v1.0.0-beta.4/src/engine/cancun.md#specification

  1. Given the expected array of blob versioned hashes client software MUST run its validation by taking the following steps:
    ...
    2. Return {status: INVALID, latestValidHash: null, validationError: errorMessage | null} if the expected and the actual arrays don't match.

@tersec tersec merged commit cbe8edf into master Apr 22, 2025
24 checks passed
@tersec tersec deleted the XLT branch April 22, 2025 01:34
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant