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,17 @@
+# The Merge -- Client Settings
+
+**Notice**: This document is a work-in-progress for researchers and implementers.
+
+This document specifies configurable settings that merge clients are expected to ship with.
+
+### Override terminal total difficulty
+
+To coordinate changes to [`terminal_total_difficulty`](fork-choice.md#transitionstore), clients
+should have a setting `--terminal-total-difficulty-override`.
+
+If `TransitionStore` has already been initialized, this just changes the value of
+`TransitionStore.terminal_total_difficulty`, otherwise it initializes `TransitionStore` with the specified
+`terminal_total_difficulty`.
+
+By default, this setting is expected to not be used and `terminal_total_difficulty` will be set as defined
+[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 that transition store can also be initialized at client startup by [overriding terminal total
+difficulty](client_settings.md#override-terminal-total-difficulty).