Address various cleanups and formatting suggestions

status-im · Mar 24, 2021 · ea5f606 · ea5f606
1 parent 96de910
commit ea5f606
Show file tree

Hide file tree

Showing 3 changed files with 34 additions and 33 deletions.
diff --git a/specs/merge/beacon-chain.md b/specs/merge/beacon-chain.md
@@ -1,6 +1,6 @@
 # Ethereum 2.0 The Merge
 
-**Warning:** This document is based on [Phase 0](../phase0/beacon-chain.md) and considered to be rebased to [Altair](../altair/beacon-chain.md) once the latter is shipped.
+**Warning:** This document is currently based on [Phase 0](../phase0/beacon-chain.md) but will be rebased to [Altair](../altair/beacon-chain.md) once the latter is shipped.
 
 **Notice**: This document is a work-in-progress for researchers and implementers.
 
@@ -36,23 +36,24 @@
 
 ## Introduction
 
-This is a patch implementing executable beacon chain proposal. 
-It enshrines application execution and validity as a first class citizen at the core of the beacon chain.
+This is a patch implementing the executable beacon chain proposal. 
+It enshrines application-layer execution and validity as a first class citizen at the core of the beacon chain.
 
 ## Constants
 
 ### Transition
+
 | Name | Value |
 | - | - |
-| `TRANSITION_TOTAL_DIFFICULTY` | _TBD_ |
+| `TRANSITION_TOTAL_DIFFICULTY` | **TBD** |
 
 ### Execution
 
 | Name | Value |
 | - | - |
-| `MAX_BYTES_PER_TRANSACTION_PAYLOAD` | `2**20` |
-| `MAX_APPLICATION_TRANSACTIONS` | `2**14` |
-| `BYTES_PER_LOGS_BLOOM` | `2**8` |
+| `MAX_BYTES_PER_TRANSACTION_PAYLOAD` | `uint64(2**20)` (= 1,048,576) |
+| `MAX_APPLICATION_TRANSACTIONS` | `uint64(2**14)` (= 16,384) |
+| `BYTES_PER_LOGS_BLOOM` | `uint64(2**8)` (= 256) |
 
 
 ## Containers
@@ -73,15 +74,13 @@ class BeaconBlockBody(phase0.BeaconBlockBody):
 
 #### `BeaconState`
 
-*Note*: `BeaconState` fields remain unchanged other than addition of `application_state_root` and `application_block_hash`. 
-
+*Note*: `BeaconState` fields remain unchanged other than addition of `application_state_root` and `application_block_hash`.
 
 ```python
 class BeaconState(phase0.BeaconState):
-    # [Added in Merge] hash of the root of application state
-    application_state_root: Bytes32
-    # [Added in Merge] hash of recent application block
-    application_block_hash: Bytes32
+    # Application-layer
+    application_state_root: Bytes32 # [New in Merge]
+    application_block_hash: Bytes32 # [New in Merge]
 ```
 
 ### New containers
@@ -128,7 +127,7 @@ class ApplicationPayload(Container):
 
 ```python
 def is_transition_completed(state: BeaconState) -> boolean:
-    state.application_block_hash != Bytes32()
+    return state.application_block_hash != Bytes32()
 ```
 
 #### `is_transition_block`
@@ -170,8 +169,7 @@ The body of the function is implementation dependent.
 ```python
 def process_application_payload(state: BeaconState, body: BeaconBlockBody) -> None:
     """
-    Note: This function is designed to be able to be run in parallel with 
-    the other `process_block` sub-functions
+    Note: This function is designed to be able to be run in parallel with the other `process_block` sub-functions
     """
 
     if is_transition_completed(state):
@@ -182,7 +180,7 @@ def process_application_payload(state: BeaconState, body: BeaconBlockBody) -> No
         state.application_block_hash = body.application_payload.block_hash
 
     elif is_transition_block(state, body):
-        assert body.application_payload == ApplicationPayload(block_hash = body.application_payload.block_hash)
+        assert body.application_payload == ApplicationPayload(block_hash=body.application_payload.block_hash)
         state.application_block_hash = body.application_payload.block_hash
 
     else:

diff --git a/specs/merge/fork-choice.md b/specs/merge/fork-choice.md
@@ -39,11 +39,11 @@ class PowBlock(Container):
 
 Let `get_pow_block(hash: Bytes32) -> PowBlock` be the function that given the hash of the PoW block returns its data.
 
-*Note*: The `eth_getBlockByHash` JSON-RPC method does not distinguish invalid blocks from blocks that hasn't been processed yet. Either extending of existing method or implementing a new one is required.
+*Note*: The `eth_getBlockByHash` JSON-RPC method does not distinguish invalid blocks from blocks that haven't been processed yet. Either extending this existing method or implementing a new one is required.
 
 #### `is_valid_transition_block`
 
-Used by fork-choice handler, `on_block`
+Used by fork-choice handler, `on_block`.
 
 ```python
 def is_valid_transition_block(block: PowBlock) -> boolean:
@@ -73,7 +73,7 @@ def on_block(store: Store, signed_block: SignedBeaconBlock) -> None:
     # 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
 
-    # [Added in Merge] Consider delaying the beacon block processing until PoW block is accepted by the application node
+    # [New in Merge] Consider delaying the beacon block processing until PoW block is accepted by the application node
     if is_transition_block(pre_state, block.body):
         pow_block = get_pow_block(block.body.application_payload.block_hash)
         assert is_valid_transition_block(pow_block)

diff --git a/specs/merge/validator.md b/specs/merge/validator.md
@@ -1,6 +1,6 @@
 # Ethereum 2.0 The Merge
 
-**Warning:** This document is based on [Phase 0](../phase0/validator.md) and considered to be rebased to [Altair](../altair/validator.md) once the latter is shipped.
+**Warning:** This document is currently based on [Phase 0](../phase0/validator.md) but will be rebased to [Altair](../altair/validator.md) once the latter is shipped.
 
 **Notice**: This document is a work-in-progress for researchers and implementers.
 
@@ -16,7 +16,7 @@
   - [Block proposal](#block-proposal)
     - [Constructing the `BeaconBlockBody`](#constructing-the-beaconblockbody)
       - [Application Payload](#application-payload)
-        - [`ApplicaitonBlock`](#applicaitonblock)
+        - [`PowBlock`](#powblock)
         - [`get_pow_chain_head`](#get_pow_chain_head)
         - [`produce_application_payload`](#produce_application_payload)
 
@@ -43,7 +43,7 @@ All validator responsibilities remain unchanged other than those noted below. Na
 
 ##### Application Payload
 
-###### `ApplicaitonBlock`
+###### `PowBlock`
 ```python
 class PowBlock(Container):
     block_hash: Bytes32
@@ -59,17 +59,20 @@ Let `get_pow_chain_head() -> PowBlock` be the function that returns the head of
 Let `produce_application_payload(parent_hash: Bytes32) -> ApplicationPayload` be the function that produces new instance of application payload.
 The body of this function is implementation dependent.
 
-* Set `block.body.application_payload = get_application_payload(state, randao_reveal)` where:
+* Set `block.body.application_payload = get_application_payload(state)` where:
 
 ```python
 def get_application_payload(state: BeaconState) -> ApplicationPayload:
-    if is_transition_completed(state):
-      application_parent_hash = state.application_block_hash
-      return produce_application_payload(application_parent_hash)
-
-    pow_block = get_pow_chain_head()
-    if pow_block.total_difficulty >= TRANSITION_TOTAL_DIFFICULTY:
-      return ApplicationPayload(block_hash = pow_block.block_hash)
-    else:
-      return ApplicationPayload()
+    if not is_transition_completed(state):
+      pow_block = get_pow_chain_head()
+      if pow_block.total_difficulty < TRANSITION_TOTAL_DIFFICULTY:
+        # Pre-merge, empty payload
+        return ApplicationPayload()
+      else:
+        # Signify merge via last PoW block_hash and an otherwise empty payload
+        return ApplicationPayload(block_hash=pow_block.block_hash)
+
+    # Post-merge, normal payload
+    application_parent_hash = state.application_block_hash
+    return produce_application_payload(state.application_block_hash)
 ```