Merge pull request #2682 from ethereum/TBH-epoch

add TBH_ACTIVATION_EPOCH

configs/mainnet.yaml

@@ -7,8 +7,10 @@ PRESET_BASE: 'mainnet'
 # ---------------------------------------------------------------
 # TBD, 2**256-2**10 is a placeholder
 TERMINAL_TOTAL_DIFFICULTY: 115792089237316195423570985008687907853269984665640564039457584007913129638912
-# By default, don't use this param
+# By default, don't use these params
 TERMINAL_BLOCK_HASH: 0x0000000000000000000000000000000000000000000000000000000000000000
+TERMINAL_BLOCK_HASH_ACTIVATION_EPOCH: 18446744073709551615
+
 
 
 # Genesis

configs/minimal.yaml

@@ -7,8 +7,10 @@ PRESET_BASE: 'minimal'
 # ---------------------------------------------------------------
 # TBD, 2**256-2**10 is a placeholder
 TERMINAL_TOTAL_DIFFICULTY: 115792089237316195423570985008687907853269984665640564039457584007913129638912
-# By default, don't use this param
+# By default, don't use these params
 TERMINAL_BLOCK_HASH: 0x0000000000000000000000000000000000000000000000000000000000000000
+TERMINAL_BLOCK_HASH_ACTIVATION_EPOCH: 18446744073709551615
+
 
 
 # Genesis

setup.py

@@ -603,7 +603,7 @@ def objects_to_spec(preset_name: str,
 
     # Access global dict of config vars for runtime configurables
     for name in spec_object.config_vars.keys():
-        functions_spec = functions_spec.replace(name, 'config.' + name)
+        functions_spec = re.sub(r"\b%s\b" % name, 'config.' + name, functions_spec)
 
     def format_config_var(name: str, vardef: VariableDefinition) -> str:
         if vardef.type_name is None:

specs/merge/beacon-chain.md

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

specs/merge/client-settings.md

@@ -18,11 +18,12 @@ This document specifies configurable settings that clients must implement for th
 
 To coordinate manual overrides to [`TERMINAL_TOTAL_DIFFICULTY`](./beacon-chain.md#Transition-settings) parameter, clients must provide `--terminal-total-difficulty-override` as a configurable setting. The value provided by this setting must take precedence over pre-configured `TERMINAL_TOTAL_DIFFICULTY` parameter. Clients should accept the setting as a decimal value (i.e., *not* hexadecimal).
 
-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.
+Except under exceptional scenarios, this setting is not expected to be used. Sufficient warning to the user about this exceptional configurable setting should be provided.
 
 ### Override terminal block hash
 
-To allow for transition 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.
+To allow for transition coordination around a specific PoW block, clients must also provide `--terminal-block-hash-override` and `--terminal-block-hash-epoch-override` as configurable settings.
+* The value provided by `--terminal-block-hash-override` takes precedence over the pre-configured `TERMINAL_BLOCK_HASH` parameter.
+* The value provided by `--terminal-block-hash-epoch-override` takes precedence over the pre-configured `TERMINAL_BLOCK_HASH_ACTIVATION_EPOCH` 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.
+Except under exceptional scenarios, these settings are not expected to be used. Sufficient warning to the user about this exceptional configurable setting should be provided.

specs/merge/fork-choice.md

@@ -75,8 +75,8 @@ 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
+    if TERMINAL_BLOCK_HASH != Hash32():
+        return block.block_hash == TERMINAL_BLOCK_HASH
 
     is_total_difficulty_reached = block.total_difficulty >= TERMINAL_TOTAL_DIFFICULTY
     is_parent_total_difficulty_valid = parent.total_difficulty < TERMINAL_TOTAL_DIFFICULTY
@@ -111,9 +111,13 @@ def on_block(store: Store, signed_block: SignedBeaconBlock) -> None:
 
     # [New in Merge]
     if is_merge_block(pre_state, block.body):
+        # Check the parent PoW block of execution payload is a valid terminal PoW block.
         pow_block = get_pow_block(block.body.execution_payload.parent_hash)
         pow_parent = get_pow_block(pow_block.parent_hash)
         assert is_valid_terminal_pow_block(pow_block, pow_parent)
+        # If `TERMINAL_BLOCK_HASH` is used as an override, the activation epoch must be reached.
+        if TERMINAL_BLOCK_HASH != Hash32():
+            assert compute_epoch_at_slot(block.slot) >= TERMINAL_BLOCK_HASH_ACTIVATION_EPOCH
 
     # Add new block to the store
     store.blocks[hash_tree_root(block)] = block

specs/merge/validator.md

@@ -127,6 +127,12 @@ def prepare_execution_payload(state: BeaconState,
                               fee_recipient: ExecutionAddress,
                               execution_engine: ExecutionEngine) -> Optional[PayloadId]:
     if not is_merge_complete(state):
+        is_terminal_block_hash_set = TERMINAL_BLOCK_HASH != Hash32()
+        is_activation_epoch_reached = get_current_epoch(state.slot) < TERMINAL_BLOCK_HASH_ACTIVATION_EPOCH
+        if is_terminal_block_hash_set and is_activation_epoch_reached:
+            # Terminal block hash is set but activation epoch is not yet reached, no prepare payload call is needed
+            return None
+
         terminal_pow_block = get_terminal_pow_block(pow_chain)
         if terminal_pow_block is None:
             # Pre-merge, no prepare payload call is needed