# Merge Interop Spec

[toc]

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:
| Specification | Release / Commit | Reference |
| - | - | - |
| Consensus spec | `v1.1.1` | [`v1.1.1`](https://github.com/ethereum/consensus-specs/tree/v1.1.1/specs/merge) |
| Consensus spec tests | `v1.1.1` | [`v1.1.1`](https://github.com/ethereum/consensus-spec-tests/releases/tag/v1.1.1) |
| EIP-3675 | `504954e3bba2b58712d84865966ebc17bd4875f5` | [`504954e3`](https://github.com/ethereum/EIPs/blob/504954e3bba2b58712d84865966ebc17bd4875f5/EIPS/eip-3675.md) |
| Engine API | `v1.0.0-alpha.2` | [`v1.0.0-alpha.2`](https://github.com/ethereum/execution-apis/blob/v1.0.0-alpha.2/src/engine/interop/specification.md) |

## 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