Merge Interop Spec

• Merge Interop Spec
  • Spec versions
  • Consensus client
    • Engine API
  • Execution client
    • The random field
    • Timestamp validation
    • Engine API
  • Sync
    • Proposals on the sync process design

This document defines the version of the Merge specification that should be implemented as a prerequisite for the Interop and provides additional guidance to client developers.

Spec versions

The Merge specification has a number of different sources that should be aligned with each other to avoid incompatibility issues between consensus and execution client implementations.

We define the following versions for each of these documents to be used during the Interop:

Consensus client

Consensus clients must satisfy the following requirements to be conformant with the Interop spec:

• Implement all consensus-specs with exception for the Client Settings section
• Implement all Engine API calls (synchronous)
• Pass all consensus-spec tests

Engine API

Consensus client implementation must call Engine API methods in a synchronous fashion to avoid potential inconsistencies in the block tree and fork choice data across the layers that might be induced via unexpected message ordering.

Keeping local representation of the network data in a consistent state between the layers in an asynchronous environment requires additional design and specification work and is out of the scope for the initial Interop.

Execution client

Execution clients must satisfy the following requirements to be conformant with the Interop spec:

• Implement all changes introduced by the EIP-3675
• Implement Engine API server (synchronous)

The random field

The random field has been introduced into the ExecutionPayload in the consensus-specs and the Engine API, but an EIP introducing this field to the execution layer is pending.

For initial Interop, execution client must adhere to the following rules and requirements with respect to the random field:

• Support the random field of the ExecutionPayload structure defined in the Engine API spec
• Set the random field of the payload sent in response to the engine_getPayload call to the value supplied in the corresponding engine_preparePayload call
• Ignore the random field value while processing the engine_executePayload call

Timestamp validation

As the timestamp value is strictly validated by consensus clients, it is recommended an execution client software turns off any validations that are related to the timestamp field during building and processing an execution payload.

Engine API

It is recommended for the execution client software to respond with 4: Unknown header error to the engine_preparePayload, engine_forkchoiceUpdated method calls if any block referenced by either of these calls hasn't been confirmed as valid by the corresponding engine_consensusValidated call.

If no sync strategy is yet supported by the execution client software, it is recommended to respond with 4: Unknown header error to the engine_executePayload call if the parent block of the payload supplied by this call is either unknown or hasn't been confirmed as valid by the corresponding engine_consensusValidated call.

Sync

Sync process affects every part of the post-Merge client software, starting from consensus-layer client that should understand when the execution counterparty is syncing and react accordingly, going through the Engine API that communicates sync status between the layers, and ending up in execution-layer client which does the job on pulling chain data from the wire.

The key goal of the design of the sync process is to allow execution clients to switch between different strategies of syncing with the network without making any changes to the Engine API and consensus client implementations.

While the sync process implementation is not a strong requirement for the Interop, we encourage client developers to prototype sync beforehand in order to evaluate design proposals, identify the pain points of the sync process during the transition and after the Merge, and be able to engage deeply on the topic during the Interop.

Proposals on the sync process design

• https://github.com/fjl/p2p-drafts/blob/master/merge-sync/merge-sync.md