Add safe_block_hash to notify_forkchoice_updated

setup.py

@@ -529,6 +529,7 @@ def notify_new_payload(self: ExecutionEngine, execution_payload: ExecutionPayloa
 
     def notify_forkchoice_updated(self: ExecutionEngine,
                                   head_block_hash: Hash32,
+                                  safe_block_hash: Hash32,
                                   finalized_block_hash: Hash32,
                                   payload_attributes: Optional[PayloadAttributes]) -> Optional[PayloadId]:
         pass

specs/bellatrix/fork-choice.md

@@ -47,8 +47,9 @@ The Engine API may be used to implement it with an external execution engine.
 
 #### `notify_forkchoice_updated`
 
-This function performs two actions *atomically*:
+This function performs three actions *atomically*:
 * Re-organizes the execution payload chain and corresponding state to make `head_block_hash` the head.
+* Updates safe block hash with the value provided by `safe_block_hash` parameter.
 * Applies finality to the execution state: it irreversibly persists the chain of all execution payloads
 and corresponding state, up to and including `finalized_block_hash`.
 
@@ -58,18 +59,21 @@ Additionally, if `payload_attributes` is provided, this function sets in motion
 ```python
 def notify_forkchoice_updated(self: ExecutionEngine,
                               head_block_hash: Hash32,
+                              safe_block_hash: Hash32,
                               finalized_block_hash: Hash32,
                               payload_attributes: Optional[PayloadAttributes]) -> Optional[PayloadId]:
     ...
 ```
 
-*Note*: The call of the `notify_forkchoice_updated` function maps on the `POS_FORKCHOICE_UPDATED` event defined in the [EIP-3675](https://eips.ethereum.org/EIPS/eip-3675#definitions).
+*Note*: The `(head_block_hash, finalized_block_hash)` values of the `notify_forkchoice_updated` function call maps on the `POS_FORKCHOICE_UPDATED` event defined in the [EIP-3675](https://eips.ethereum.org/EIPS/eip-3675#definitions).
 As per EIP-3675, before a post-transition block is finalized, `notify_forkchoice_updated` MUST be called with `finalized_block_hash = Hash32()`.
 
 *Note*: Client software MUST NOT call this function until the transition conditions are met on the PoW network, i.e. there exists a block for which `is_valid_terminal_pow_block` function returns `True`.
 
 *Note*: Client software MUST call this function to initiate the payload build process to produce the merge transition block; the `head_block_hash` parameter MUST be set to the hash of a terminal PoW block in this case.
 
+*Note*: Until safe head function is implemented, `safe_block_hash` parameter MUST be stubbed with the `head_block_hash` value.
+
 ## Helpers
 
 ### `PayloadAttributes`

specs/bellatrix/validator.md

@@ -146,7 +146,14 @@ def prepare_execution_payload(state: BeaconState,
         prev_randao=get_randao_mix(state, get_current_epoch(state)),
         suggested_fee_recipient=suggested_fee_recipient,
     )
-    return execution_engine.notify_forkchoice_updated(parent_hash, finalized_block_hash, payload_attributes)
+    # Set safe and head block hashes to the same value
+    return execution_engine.notify_forkchoice_updated(
+        head_block_hash=parent_hash,
+        # TODO: Use `parent_hash` as a stub for now.
+        safe_block_hash=parent_hash,
+        finalized_block_hash=finalized_block_hash,
+        payload_attributes=payload_attributes,
+    )
 ```
 
 2. Set `block.body.execution_payload = get_execution_payload(payload_id, execution_engine)`, where:

tests/core/pyspec/eth2spec/test/bellatrix/unittests/validator/test_validator.py

@@ -1,4 +1,5 @@
 from copy import deepcopy
+from typing import Optional
 
 from eth2spec.test.helpers.pow_block import (
     prepare_random_pow_chain,
@@ -146,7 +147,11 @@ def test_prepare_execution_payload(spec, state):
 
         # Mock execution_engine
         class TestEngine(spec.NoopExecutionEngine):
-            def notify_forkchoice_updated(self, parent_hash, finalized_block_hash, payload_attributes) -> bool:
+            def notify_forkchoice_updated(self,
+                                          head_block_hash,
+                                          safe_block_hash,
+                                          finalized_block_hash,
+                                          payload_attributes) -> Optional[spec.PayloadId]:
                 return SAMPLE_PAYLOAD_ID
 
         payload_id = spec.prepare_execution_payload(