# The Merge Spec changes and issues

Some items were moved from [Amphora Spec changes and issues](https://notes.ethereum.org/Iz9jhwQPREyTcW2XllwfMw?view)

## CL specs
* clarify the communication with EL during the transition, i.e. go through each EE method call and make a note if needed
* [x] [[#2745](https://github.com/ethereum/consensus-specs/pull/2745)] [`notify_fork_choice_updated`](https://github.com/ethereum/consensus-specs/blob/dev/specs/merge/fork-choice.md#notify_forkchoice_updated)
* [x] [[#2741](https://github.com/ethereum/consensus-specs/pull/2741)] remove CLI args to override TTD and TBH
* [x] [[#2728](https://github.com/ethereum/consensus-specs/pull/2728)] consider renaming `coinbase` to `fee_recipient` in the spec
* [x] specify how to send `forkchoiceUpdated` to trigger build process for the first payload ever
* it's already handled in the validator guide of the Merge spec in `consensus-specs` repository
* [x] refine terminal block handling in validator guide: `pow_chain` vs `pow_block_tree`, rename `PowBlock -> PowAttributes`
* related issue [#2636](https://github.com/ethereum/consensus-specs/issues/2636)
* `pow_chain` shouldn't necessarily contain a block with `TERMINAL_BLOCK_HASH` as this block might belong to a minority fork to the local observation of EL; consider `pow_block_tree` vs `get_pow_block` to query for TBH
* this is resolved by whitlisting `TERMINAL_BLOCK_HASH` on EL side
* renaming might not be necessary
* [x] Note in the merge p2p-interface that block validation is extended with payload execution extending the semantics of rules based on block validation
* Optimistic sync relies on propagating blcoks without validation of an execution payload
* [ ] Add `get_safe_head` as a fork choice rule extension, place it near to `/specs` folder
* [ ] `receipt_root` -> `receipts_root`

## EL specs
* EIP-3675
* [x] [[#4487](https://github.com/ethereum/EIPs/pull/4487)] revisit EIP-2124 logic, see [the concern](https://github.com/ethereum/EIPs/pull/4415/files#r745337814)
* [x] [[#4463](https://github.com/ethereum/EIPs/pull/4463)] EIP-3675: say that historical blocks are no longer a requisite for the node sync in security considerations
* EL clients require TTD to be known in advance [#2724](https://github.com/ethereum/consensus-specs/issues/2724)
* [x] [[#4466](https://github.com/ethereum/EIPs/pull/4466)] EIP-3675: BRING TTD BACK!!!
* [x] [[#132](https://github.com/ethereum/execution-apis/pull/132)] Engine API: consider adding meaningful errors if CL tries to do the transition at a TTD value that is unexpected to EL
* [x] [[#4493](https://github.com/ethereum/EIPs/pull/4493)] EIP-3675: add `TERMINAL_BLOCK_HASH` (consider picking another name) to whitelist the branch that is used for emergency Merge
* [x] [[EIP-4444](https://eips.ethereum.org/EIPS/eip-4444)] EL client software MAY NOT store data of entire chain history (headers, bodies, receipts) (assigned to: lightclient, george, etc)
* EIP-4399
* [x] [[#4465](https://github.com/ethereum/EIPs/pull/4465)] add a know how to distinguish PoS from PoW environment inside of a smart contract
* [ ] clarify more on `RANDOM` security consideration: biasability/predictability
* [ ] answer here https://ethereum-magicians.org/t/eip-4399-supplant-difficulty-opcode-with-random/7368/11

## Engine API
* [ ] Engine API authentication
* Consider to use JWT
* [ ] define QoS expectation on return -- e.g. 0.5s or `SLOTS_PER_SECOND / 30`, [#91](https://github.com/ethereum/execution-apis/issues/91)
* [ ] pass `SECONDS_PER_SLOT` to the execution client (or all of the parameters)?
* [x] [[#146](https://github.com/ethereum/execution-apis/pull/146)] consider adding `getPayloadsByRange` to engine API for payload deduplication across CL/EL -- see [doc for discussion](https://notes.ethereum.org/3_8ELmGXTIyghe9bzmBWUA?view)
* consider the option for `BeaconBlocksByRange` to replace payloads with their roots
* consider the option of `engine_getBlockBodiesByRange` and store `ExecutionPayloadHeader` on CL side
* [x] [[#148](https://github.com/ethereum/execution-apis/pull/148)] Refine Message ordering. Take 2
* Respond with error if the order of `forkchoiceUpdated` calls coming from CL is incorrect
* [x] [[#133](https://github.com/ethereum/execution-apis/pull/133)] Refine Message ordering
* "Execution Layer client software MUST execute calls strictly in the order of request IDs to avoid degenerate race conditions." -- potentially opens a DoS vector as a block that takes too long to be executed may brick the client
* "Consensus Layer client software MUST utilize JSON-RPC request IDs that are strictly increasing." -- CL must also send messages respecting order they appear in the system
* [x] [[#130](https://github.com/ethereum/execution-apis/pull/130)] consider renaming `feeRecipient` to `suggestedFeeRecipient` in the API call
* [x] [[#135](https://github.com/ethereum/execution-apis/pull/135)] send payload validation error to CL [#120](https://github.com/ethereum/execution-apis/issues/120)
* [x] [[#134](https://github.com/ethereum/execution-apis/pull/134)] Use the same port for HTTP and WebSocket, additional port is redundant

## Optimistic sync
* [x] [[#2770](https://github.com/ethereum/consensus-specs/pull/2770)] Aim to write a spec
* [x] Add clear directives that `engine_executePayload` and `engine_forkchoiceUpdated` method MUST continue to be called optimistically to give info to EL. To [aid sync and avoid deadlocks](https://notes.ethereum.org/@djrtwo/BJxKBaqNF)
* [x] [[solution](https://github.com/ethereum/consensus-specs/issues/2732#issuecomment-975907837)] non-existing PoW block as a parent of the merge block turns on `SYNCING`, this must not block validator duties as then the network will get stuck, see no 5. [here](https://github.com/ethereum/execution-apis/blob/main/src/engine/interop/specification.md#specification-2)
* [x] [ADDED TO THE TEST PLAN] Add a test case checking this scenario

## JSON-RPC API
* [ ] consider `forkchoiceUpdated` and/or `executePayload(child_payload)` as a confirmation of block's validity wrt PoS rules; i.e. space of "unsafe" blocks could be reduced to leaf blocks that have never been in the canonical chain
* [ ] add warning to `web3.eth.getBlockByHash` (or similar method) that blocks have not necessarily been corectly validated wtr beacon chain consensus. Point them to beacon API to do so. Probably need `web3.beacon.getBeaconBlocksByExecutionPayloadHash` to satisfy this. note that this is plural because multiple beacon blocks can include the same exact payload (i.e. sister blocks that have same exec payload contents)
* [ ] update block tags: `finalized`, `safe`, `unsafe`, `latest == safe`
* [ ] deprecate methods related to PoW, i.e. `eth_hashrate`, `eth_getWork`, `eth_submitWork` etc
* [ ] consider client specific RPC methods, https://geth.ethereum.org/docs/rpc

## Release
* [ ] Merge release procedure

## Testing
* [ ] [[WIP](https://hackmd.io/rDJk8dqqTpCiwCbaiNSB3g?view)] prepare test plan
* consider [test cases for the Merge](https://hackmd.io/z2h_RAJoTHWSRka-9MDEVg) by Marius
* [ ] Update Testing section of the merge-readiness.md

## Hive
* CL simulator
* covers Engine API implementation by EL and EIP-3675 requirements including:
* the Networking section (block gossip deprecation)
* TTD hardcode, TTD and TBH (terminal block hash) overrides
* fast/snap sync and processing blocks received via gossip MUST respect TTD and TBH
* relies on the Engine API as a entry point, should have a predefined Engine API calls as a test vector
* CL+EL fully functional nodes
* covers transition process with various edge cases that may appear in it
* network partitioning, involves two nodes; a terminal block is withheld by a node and after some time released to another node; it should be successfully processed
* passing a terminal block point while syncing; then CL must go back and validate terminal block conditions, finalized and not yet finalized cases should be covered; similar to the case when block is withheld
* covers Engine API implementation by CL
* covers consensus specs
* CL reads pre-loaded list of blocks, need to figure out how to emulate network partitioning
* Run all tests with all possible client combinations