From 49d225bb785bba6eb233e306119b7caf6ca3057c Mon Sep 17 00:00:00 2001 From: lsankar4033 Date: Wed, 8 Sep 2021 12:34:33 -0700 Subject: [PATCH 01/11] Add new --terminal-total-difficulty-override client_setting --- README.md | 3 ++- specs/merge/client_settings.md | 14 ++++++++++++++ 2 files changed, 16 insertions(+), 1 deletion(-) create mode 100644 specs/merge/client_settings.md diff --git a/README.md b/README.md index bc4ba100b..b5a898d37 100644 --- a/README.md +++ b/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 diff --git a/specs/merge/client_settings.md b/specs/merge/client_settings.md new file mode 100644 index 000000000..172617a74 --- /dev/null +++ b/specs/merge/client_settings.md @@ -0,0 +1,14 @@ +# 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`](specs/merge/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`. From 01fe3cdb083dbf561d08ad2f11db777fe2724811 Mon Sep 17 00:00:00 2001 From: lsankar4033 Date: Wed, 8 Sep 2021 12:57:49 -0700 Subject: [PATCH 02/11] Add note about default behavior --- specs/merge/client_settings.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/specs/merge/client_settings.md b/specs/merge/client_settings.md index 172617a74..f1ff8b639 100644 --- a/specs/merge/client_settings.md +++ b/specs/merge/client_settings.md @@ -12,3 +12,6 @@ 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](specs/merge/fork.md#initializing-transition-store). From 0f7d8e5552c0ed7c4e992e3183a7e19d365c63c4 Mon Sep 17 00:00:00 2001 From: lsankar4033 Date: Wed, 8 Sep 2021 13:03:05 -0700 Subject: [PATCH 03/11] Add notes in merge/fork.md --- specs/merge/fork.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/specs/merge/fork.md b/specs/merge/fork.md index f16be0574..0785f577c 100644 --- a/specs/merge/fork.md +++ b/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](specs/merge/client_settings.md#override-terminal-total-difficulty). From a542a07578d5cc3b5c1d41e11a14a071cc0fe7da Mon Sep 17 00:00:00 2001 From: lsankar4033 Date: Wed, 8 Sep 2021 13:06:22 -0700 Subject: [PATCH 04/11] Fix links --- specs/merge/client_settings.md | 4 ++-- specs/merge/fork.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/specs/merge/client_settings.md b/specs/merge/client_settings.md index f1ff8b639..520ca1fdf 100644 --- a/specs/merge/client_settings.md +++ b/specs/merge/client_settings.md @@ -6,7 +6,7 @@ This document specifies configurable settings that merge clients are expected to ### Override terminal total difficulty -To coordinate changes to [`terminal_total_difficulty`](specs/merge/fork-choice.md#transitionstore), clients +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 @@ -14,4 +14,4 @@ If `TransitionStore` has already been initialized, this just changes the value o `terminal_total_difficulty`. By default, this setting is expected to not be used and `terminal_total_difficulty` will be set as defined -[here](specs/merge/fork.md#initializing-transition-store). +[here](fork.md#initializing-transition-store). diff --git a/specs/merge/fork.md b/specs/merge/fork.md index 0785f577c..64216a401 100644 --- a/specs/merge/fork.md +++ b/specs/merge/fork.md @@ -129,4 +129,4 @@ def initialize_transition_store(state: BeaconState) -> TransitionStore: ``` Note that transition store can also be initialized at client startup by [overriding terminal total -difficulty](specs/merge/client_settings.md#override-terminal-total-difficulty). +difficulty](client_settings.md#override-terminal-total-difficulty). From 10f4ea4b5122903c28ef9dbb6ec66bba93b9791a Mon Sep 17 00:00:00 2001 From: Lakshman Sankar Date: Thu, 9 Sep 2021 08:36:25 -0700 Subject: [PATCH 05/11] Wording change Co-authored-by: Danny Ryan --- specs/merge/client_settings.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/merge/client_settings.md b/specs/merge/client_settings.md index 520ca1fdf..8f4ca6367 100644 --- a/specs/merge/client_settings.md +++ b/specs/merge/client_settings.md @@ -9,7 +9,7 @@ This document specifies configurable settings that merge clients are expected to 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 +If `TransitionStore` has already [been initialized](./fork.md#initializing-transition-store), this alters the previously initialized value of `TransitionStore.terminal_total_difficulty`, otherwise it initializes `TransitionStore` with the specified `terminal_total_difficulty`. From de1487564ad02c5201427179d42507971808cccf Mon Sep 17 00:00:00 2001 From: Lakshman Sankar Date: Thu, 9 Sep 2021 08:36:42 -0700 Subject: [PATCH 06/11] Wording change Co-authored-by: Mikhail Kalinin --- specs/merge/fork.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/merge/fork.md b/specs/merge/fork.md index 64216a401..f2547758d 100644 --- a/specs/merge/fork.md +++ b/specs/merge/fork.md @@ -128,5 +128,5 @@ def initialize_transition_store(state: BeaconState) -> TransitionStore: return get_transition_store(pow_block) ``` -Note that transition store can also be initialized at client startup by [overriding terminal total +*Note*: Transition store can also be initialized at client startup by [overriding terminal total difficulty](client_settings.md#override-terminal-total-difficulty). From 385ee12ef0a9d2db1fb57af9549ac9c4a5b42d4c Mon Sep 17 00:00:00 2001 From: Lakshman Sankar Date: Thu, 9 Sep 2021 08:36:54 -0700 Subject: [PATCH 07/11] 'should' -> 'must' Co-authored-by: Danny Ryan --- specs/merge/client_settings.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/merge/client_settings.md b/specs/merge/client_settings.md index 8f4ca6367..e2a69c538 100644 --- a/specs/merge/client_settings.md +++ b/specs/merge/client_settings.md @@ -7,7 +7,7 @@ This document specifies configurable settings that merge clients are expected to ### Override terminal total difficulty To coordinate changes to [`terminal_total_difficulty`](fork-choice.md#transitionstore), clients -should have a setting `--terminal-total-difficulty-override`. +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 it initializes `TransitionStore` with the specified From 771933d1a70ef62c7cd645d3050127c2f5d1fb52 Mon Sep 17 00:00:00 2001 From: Lakshman Sankar Date: Thu, 9 Sep 2021 08:37:27 -0700 Subject: [PATCH 08/11] Stronger language around usage of the setting Co-authored-by: Danny Ryan --- specs/merge/client_settings.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/merge/client_settings.md b/specs/merge/client_settings.md index e2a69c538..05a13094a 100644 --- a/specs/merge/client_settings.md +++ b/specs/merge/client_settings.md @@ -13,5 +13,5 @@ If `TransitionStore` has already [been initialized](./fork.md#initializing-trans `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 +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). From 252f4ea14ad5a48d7100a38968f636d380e893b2 Mon Sep 17 00:00:00 2001 From: Lakshman Sankar Date: Thu, 9 Sep 2021 08:37:39 -0700 Subject: [PATCH 09/11] Wording change Co-authored-by: Danny Ryan --- specs/merge/client_settings.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/merge/client_settings.md b/specs/merge/client_settings.md index 05a13094a..6356e8a5b 100644 --- a/specs/merge/client_settings.md +++ b/specs/merge/client_settings.md @@ -2,7 +2,7 @@ **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. +This document specifies configurable settings that clients must implement for the Merge. ### Override terminal total difficulty From 83471fe46121760d6fc8b2e150e6590c7f6ad3f7 Mon Sep 17 00:00:00 2001 From: Lakshman Sankar Date: Thu, 9 Sep 2021 08:38:33 -0700 Subject: [PATCH 10/11] Apply suggestions from code review Co-authored-by: Danny Ryan --- specs/merge/client_settings.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specs/merge/client_settings.md b/specs/merge/client_settings.md index 6356e8a5b..3ff897560 100644 --- a/specs/merge/client_settings.md +++ b/specs/merge/client_settings.md @@ -6,11 +6,11 @@ This document specifies configurable settings that clients must implement for th ### Override terminal total difficulty -To coordinate changes 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 it initializes `TransitionStore` with the specified +`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. From 879a60a1697b72497e5dfb0cd0cc733d51b4ac85 Mon Sep 17 00:00:00 2001 From: lsankar4033 Date: Thu, 9 Sep 2021 08:45:21 -0700 Subject: [PATCH 11/11] Run doctoc --- specs/merge/client_settings.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/specs/merge/client_settings.md b/specs/merge/client_settings.md index 3ff897560..a8ca633ff 100644 --- a/specs/merge/client_settings.md +++ b/specs/merge/client_settings.md @@ -1,3 +1,12 @@ + + +**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) + + + # The Merge -- Client Settings **Notice**: This document is a work-in-progress for researchers and implementers.