Merge pull request #2587 from lsankar4033/merge-ttd-override

terminal total difficulty override setting

README.md

@@ -45,6 +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)
 
 ### Sharding
 
@@ -53,7 +54,7 @@ Sharding follows the merge, and is divided into three parts:
 * Sharding base functionality - In early engineering phase
   * [Beacon Chain changes](specs/sharding/beacon-chain.md)
   * [P2P Network changes](specs/sharding/p2p-interface.md)
-* Custody Game - Ready, dependent on sharding 
+* Custody Game - Ready, dependent on sharding
   * [Beacon Chain changes](specs/custody_game/beacon-chain.md)
   * [Validator custody work](specs/custody_game/validator.md)
 * Data Availability Sampling - In active R&D

specs/merge/client_settings.md

@@ -0,0 +1,26 @@
+<!-- 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.
+
+### Override terminal total difficulty
+
+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`.
+
+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).

specs/merge/fork.md

@@ -97,13 +97,13 @@ def upgrade_to_merge(pre: altair.BeaconState) -> BeaconState:
         # Execution-layer
         latest_execution_payload_header=ExecutionPayloadHeader(),
     )
-    
+
     return post
 ```
 
 ### Initializing transition store
 
-If `state.slot % SLOTS_PER_EPOCH == 0` and `compute_epoch_at_slot(state.slot) == MERGE_FORK_EPOCH`, a transition store is initialized to be further utilized by the transition process of the Merge.
+If `state.slot % SLOTS_PER_EPOCH == 0`, `compute_epoch_at_slot(state.slot) == MERGE_FORK_EPOCH`, and the transition store has not already been initialized, a transition store is initialized to be further utilized by the transition process of the Merge.
 
 Transition store initialization occurs after the state has been modified by corresponding `upgrade_to_merge` function.
 
@@ -127,3 +127,6 @@ def initialize_transition_store(state: BeaconState) -> TransitionStore:
     pow_block = get_pow_block(state.eth1_data.block_hash)
     return get_transition_store(pow_block)
 ```
+
+*Note*: Transition store can also be initialized at client startup by [overriding terminal total
+difficulty](client_settings.md#override-terminal-total-difficulty).