Terminal blockhash override

README.md

@@ -45,7 +45,7 @@ The merge is still actively in development. The exact specification has not been
   * [Merge fork](specs/merge/fork.md)
   * [Fork Choice changes](specs/merge/fork-choice.md)
   * [Validator additions](specs/merge/validator.md)
-  * [Client settings](specs/merge/client_settings.md)
+  * [Client settings](specs/merge/client-settings.md)
 
 ### Sharding
 

specs/merge/client-settings.md

@@ -1,26 +1,34 @@
-<!-- START doctoc generated TOC please keep comment here to allow auto update -->
-<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
-**Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*
-
-- [The Merge -- Client Settings](#the-merge----client-settings)
-    - [Override terminal total difficulty](#override-terminal-total-difficulty)
-
-<!-- END doctoc generated TOC please keep comment here to allow auto update -->
-
 # The Merge -- Client Settings
 
 **Notice**: This document is a work-in-progress for researchers and implementers.
 
 This document specifies configurable settings that clients must implement for the Merge.
 
+## Table of contents
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+
+- [Override terminal total difficulty](#override-terminal-total-difficulty)
+- [Override terminal block hash](#override-terminal-block-hash)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
 ### Override terminal total difficulty
 
-To coordinate manual overrides to [`terminal_total_difficulty`](fork-choice.md#transitionstore), clients
+To coordinate manual overrides to [`terminal_total_difficulty`](./fork-choice.md#transitionstore), clients
 must provide `--terminal-total-difficulty-override` as a configurable setting.
 
 If `TransitionStore` has already [been initialized](./fork.md#initializing-transition-store), this alters the previously initialized value of
-`TransitionStore.terminal_total_difficulty`, otherwise this setting initializes `TransitionStore` with the specified, bypassing `compute_terminal_total_difficulty` and the use of an `anchor_pow_block`.
-`terminal_total_difficulty`.
+`TransitionStore.terminal_total_difficulty`, otherwise this setting initializes `TransitionStore` with the specified `terminal_total_difficulty`, bypassing `compute_terminal_total_difficulty` and the use of an `anchor_pow_block`. `TransitionStore.terminal_block_hash` is initialized to `Hash32()` if this path is used.
 
 Except under exceptional scenarios, this setting is expected to not be used, and `terminal_total_difficulty` will operate with [default functionality](./fork.md#initializing-transition-store). Sufficient warning to the user about this exceptional configurable setting should be provided.
-[here](fork.md#initializing-transition-store).
+
+### Override terminal block hash
+
+In case fork coordination around a specific PoW block hash is necessary, clients must also provide `--terminal-block-hash-override` as a configurable setting.
+
+If `TransitionStore` has already [been initialized](./fork.md#initializing-transition-store), this alters the previously initialized value of
+`TransitionStore.terminal_block_hash`, otherwise this setting initializes `TransitionStore` with the specified `terminal_block_hash` and `terminal_total_difficulty` to `2**256 - 1`.
+
+As with `--terminal-total-difficulty-override`, this setting is not expected to be used unless under exceptional scenarios and sufficient warning to the user about this setting should be provided.

specs/merge/fork-choice.md

@@ -74,6 +74,7 @@ def finalize_block(self: ExecutionEngine, block_hash: Hash32) -> bool:
 @dataclass
 class TransitionStore(object):
     terminal_total_difficulty: uint256
+    terminal_block_hash: Hash32
 ```
 
 ### `PowBlock`
@@ -101,6 +102,9 @@ Used by fork-choice handler, `on_block`.
 
 ```python
 def is_valid_terminal_pow_block(transition_store: TransitionStore, block: PowBlock, parent: PowBlock) -> bool:
+    if block.block_hash == transition_store.terminal_block_hash:
+        return True
+
     is_total_difficulty_reached = block.total_difficulty >= transition_store.terminal_total_difficulty
     is_parent_total_difficulty_valid = parent.total_difficulty < transition_store.terminal_total_difficulty
     return block.is_valid and is_total_difficulty_reached and is_parent_total_difficulty_valid
@@ -127,7 +131,7 @@ def on_block(store: Store, signed_block: SignedBeaconBlock, transition_store: Tr
     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
-    
+
     # [New in Merge]
     if (transition_store is not None) and is_merge_block(pre_state, block.body):
         # Delay consideration of block until PoW block is processed by the PoW node
@@ -154,7 +158,7 @@ def on_block(store: Store, signed_block: SignedBeaconBlock, transition_store: Tr
     # 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/fork.md

@@ -120,7 +120,7 @@ def compute_terminal_total_difficulty(anchor_pow_block: PowBlock) -> uint256:
 
 def get_transition_store(anchor_pow_block: PowBlock) -> TransitionStore:
     terminal_total_difficulty = compute_terminal_total_difficulty(anchor_pow_block)
-    return TransitionStore(terminal_total_difficulty=terminal_total_difficulty)
+    return TransitionStore(terminal_total_difficulty=terminal_total_difficulty, terminal_block_hash=Hash32())
 
 
 def initialize_transition_store(state: BeaconState) -> TransitionStore:
@@ -129,4 +129,4 @@ def initialize_transition_store(state: BeaconState) -> TransitionStore:
 ```
 
 *Note*: Transition store can also be initialized at client startup by [overriding terminal total
-difficulty](client_settings.md#override-terminal-total-difficulty).
+difficulty](./client-settings.md#override-terminal-total-difficulty).