Add TERMINAL_BLOCK_HASH override

configs/mainnet.yaml

@@ -7,7 +7,8 @@ PRESET_BASE: 'mainnet'
 # ---------------------------------------------------------------
 # TBD, 2**256-1 is a placeholder
 TERMINAL_TOTAL_DIFFICULTY: 115792089237316195423570985008687907853269984665640564039457584007913129639935
-
+# By default, don't use this param
+TERMINAL_BLOCK_HASH: 0x0000000000000000000000000000000000000000000000000000000000000000
 
 # Genesis
 # ---------------------------------------------------------------

configs/minimal.yaml

@@ -7,7 +7,8 @@ PRESET_BASE: 'minimal'
 # ---------------------------------------------------------------
 # TBD, 2**256-1 is a placeholder
 TERMINAL_TOTAL_DIFFICULTY: 115792089237316195423570985008687907853269984665640564039457584007913129639935
-
+# By default, don't use this param
+TERMINAL_BLOCK_HASH: 0x0000000000000000000000000000000000000000000000000000000000000000
 
 # Genesis
 # ---------------------------------------------------------------

specs/merge/beacon-chain.md

@@ -83,6 +83,7 @@ This patch adds transaction execution to the beacon chain as part of the Merge f
 | Name | Value |
 | - | - |
 | `TERMINAL_TOTAL_DIFFICULTY` | **TBD** |
+| `TERMINAL_BLOCK_HASH` | `Bytes32('0x0000000000000000000000000000000000000000000000000000000000000000')` |
 
 ## Containers
 

specs/merge/client-settings.md

@@ -19,3 +19,9 @@ To coordinate manual overrides to [`TERMINAL_TOTAL_DIFFICULTY`](./beacon-chain.m
 
 Except under exceptional scenarios, this setting is expected to not be used. Sufficient warning to the user about this exceptional configurable setting should be provided.
 
+### Override terminal block hash
+
+To allow for fork coordination around a specific PoW block, clients must also provide `--terminal-block-hash-override` as a configurable setting.
+The value provided by this setting takes precedence over the pre-configured `TERMINAL_BLOCK_HASH` parameter.
+
+Except under exceptional scenarios, this setting is expected to not be used. Sufficient warning to the user about this exceptional configurable setting should be provided.

specs/merge/fork-choice.md

@@ -90,6 +90,9 @@ Used by fork-choice handler, `on_block`.
 
 ```python
 def is_valid_terminal_pow_block(block: PowBlock, parent: PowBlock) -> bool:
+    if block.block_hash == TERMINAL_BLOCK_HASH:
+        return True
+
     is_total_difficulty_reached = block.total_difficulty >= TERMINAL_TOTAL_DIFFICULTY
     is_parent_total_difficulty_valid = parent.total_difficulty < TERMINAL_TOTAL_DIFFICULTY
     return is_total_difficulty_reached and is_parent_total_difficulty_valid
@@ -116,7 +119,7 @@ def on_block(store: Store, signed_block: SignedBeaconBlock) -> None:
     assert block.slot > finalized_slot
     # Check block is a descendant of the finalized block at the checkpoint finalized slot
     assert get_ancestor(store, block.parent_root, finalized_slot) == store.finalized_checkpoint.root
-    
+
     # Check the block is valid and compute the post-state
     state = pre_state.copy()
     state_transition(state, signed_block, True)
@@ -142,7 +145,7 @@ def on_block(store: Store, signed_block: SignedBeaconBlock) -> None:
     # Update finalized checkpoint
     if state.finalized_checkpoint.epoch > store.finalized_checkpoint.epoch:
         store.finalized_checkpoint = state.finalized_checkpoint
-        
+
         # Potentially update justified if different from store
         if store.justified_checkpoint != state.current_justified_checkpoint:
             # Update justified if new justified is later than store justified

specs/merge/validator.md

@@ -74,6 +74,14 @@ def get_pow_block_at_total_difficulty(total_difficulty: uint256, pow_chain: Sequ
 
     return None
 
+def get_terminal_pow_block(total_difficulty: uint256, block_hash_override: Hash32, pow_chain: Sequence[PowBlock]) -> Optional[PowBlock]:
+    # check block hash override prior to total difficulty
+    pow_block_overrides = [pow_block for pow_block in pow_chain if pow_block.block_hash == block_hash_override]
+    if len(pow_block_overrides) != 0:
+        return pow_block_overrides[0]
+
+    return get_pow_block_at_total_difficulty(total_difficulty, pow_chain)
+
 
 def produce_execution_payload(state: BeaconState,
                               parent_hash: Hash32,
@@ -87,7 +95,7 @@ def get_execution_payload(state: BeaconState,
                           execution_engine: ExecutionEngine,
                           pow_chain: Sequence[PowBlock]) -> ExecutionPayload:
     if not is_merge_complete(state):
-        terminal_pow_block = get_pow_block_at_total_difficulty(TERMINAL_TOTAL_DIFFICULTY, pow_chain)
+        terminal_pow_block = get_terminal_pow_block(TERMINAL_TOTAL_DIFFICULTY, TERMINAL_BLOCK_HASH, pow_chain)
         if terminal_pow_block is None:
             # Pre-merge, empty payload
             return ExecutionPayload()