Merge branch 'dev' into terminal_blockhash_override_2

configs/mainnet.yaml

@@ -31,7 +31,7 @@ GENESIS_DELAY: 604800
 
 # Altair
 ALTAIR_FORK_VERSION: 0x01000000
-ALTAIR_FORK_EPOCH: 18446744073709551615
+ALTAIR_FORK_EPOCH: 74240  # Oct 27, 2021, 10:56:23am UTC
 # Merge
 MERGE_FORK_VERSION: 0x02000000
 MERGE_FORK_EPOCH: 18446744073709551615

setup.py

@@ -32,7 +32,7 @@
 from marko.block import Heading, FencedCode, LinkRefDef, BlankLine
 from marko.inline import CodeSpan
 from marko.ext.gfm import gfm
-from marko.ext.gfm.elements import Table, Paragraph
+from marko.ext.gfm.elements import Table
 
 
 # Definitions in context.py
@@ -522,16 +522,23 @@ def get_pow_chain_head() -> PowBlock:
 
 class NoopExecutionEngine(ExecutionEngine):
 
-    def on_payload(self, execution_payload: ExecutionPayload) -> bool:
+    def execute_payload(self: ExecutionEngine, execution_payload: ExecutionPayload) -> bool:
         return True
 
-    def set_head(self, block_hash: Hash32) -> bool:
-        return True
+    def notify_consensus_validated(self: ExecutionEngine, block_hash: Hash32, valid: bool) -> None:
+        pass
 
-    def finalize_block(self, block_hash: Hash32) -> bool:
-        return True
+    def notify_forkchoice_updated(self: ExecutionEngine, head_block_hash: Hash32, finalized_block_hash: Hash32) -> None:
+        pass
+
+    def prepare_payload(self: ExecutionEngine,
+                        parent_hash: Hash32,
+                        timestamp: uint64,
+                        random: Bytes32,
+                        feeRecipient: ExecutionAddress) -> PayloadId:
+        raise NotImplementedError("no default block production")
 
-    def assemble_block(self, block_hash: Hash32, timestamp: uint64, random: Bytes32) -> ExecutionPayload:
+    def get_payload(self: ExecutionEngine, payload_id: PayloadId) -> ExecutionPayload:
         raise NotImplementedError("no default block production")
 
 

specs/altair/fork.md

@@ -1,7 +1,5 @@
 # Altair -- Fork Logic
 
-**Notice**: This document is a work-in-progress for researchers and implementers.
-
 ## Table of contents
 
 <!-- START doctoc generated TOC please keep comment here to allow auto update -->
@@ -26,13 +24,13 @@ Warning: this configuration is not definitive.
 | Name | Value |
 | - | - |
 | `ALTAIR_FORK_VERSION` | `Version('0x01000000')` |
-| `ALTAIR_FORK_EPOCH` | `Epoch(18446744073709551615)` **TBD** |
+| `ALTAIR_FORK_EPOCH` | `Epoch(74240)` (Oct 27, 2021, 10:56:23am UTC) |
 
 ## Fork to Altair
 
 ### Fork trigger
 
-TBD. Social consensus, along with state conditions such as epoch boundary, finality, deposits, active validator count, etc. may be part of the decision process to trigger the fork. For now we assume the condition will be triggered at epoch `ALTAIR_FORK_EPOCH`.
+The fork is triggered at epoch `ALTAIR_FORK_EPOCH`.
 
 Note that for the pure Altair networks, we don't apply `upgrade_to_altair` since it starts with Altair version logic.
 

specs/merge/beacon-chain.md

@@ -31,7 +31,8 @@
     - [`compute_timestamp_at_slot`](#compute_timestamp_at_slot)
 - [Beacon chain state transition function](#beacon-chain-state-transition-function)
   - [Execution engine](#execution-engine)
-    - [`on_payload`](#on_payload)
+    - [`execute_payload`](#execute_payload)
+    - [`notify_consensus_validated`](#notify_consensus_validated)
   - [Block processing](#block-processing)
   - [Execution payload processing](#execution-payload-processing)
     - [`is_valid_gas_limit`](#is_valid_gas_limit)
@@ -53,6 +54,7 @@ This patch adds transaction execution to the beacon chain as part of the Merge f
 | - | - | - |
 | `OpaqueTransaction` | `ByteList[MAX_BYTES_PER_OPAQUE_TRANSACTION]` | a [typed transaction envelope](https://eips.ethereum.org/EIPS/eip-2718#opaque-byte-array-rather-than-an-rlp-array) structured as `TransactionType \|\| TransactionPayload` |
 | `Transaction` | `Union[OpaqueTransaction]` | a transaction |
+| `ExecutionAddress` | `Bytes20` | Address of account on the execution layer |
 
 ## Constants
 
@@ -159,7 +161,7 @@ class BeaconState(Container):
 class ExecutionPayload(Container):
     # Execution block header fields
     parent_hash: Hash32
-    coinbase: Bytes20  # 'beneficiary' in the yellow paper
+    coinbase: ExecutionAddress  # 'beneficiary' in the yellow paper
     state_root: Bytes32
     receipt_root: Bytes32  # 'receipts root' in the yellow paper
     logs_bloom: ByteVector[BYTES_PER_LOGS_BLOOM]
@@ -181,7 +183,7 @@ class ExecutionPayload(Container):
 class ExecutionPayloadHeader(Container):
     # Execution block header fields
     parent_hash: Hash32
-    coinbase: Bytes20
+    coinbase: ExecutionAddress
     state_root: Bytes32
     receipt_root: Bytes32
     logs_bloom: ByteVector[BYTES_PER_LOGS_BLOOM]
@@ -241,19 +243,38 @@ def compute_timestamp_at_slot(state: BeaconState, slot: Slot) -> uint64:
 The implementation-dependent `ExecutionEngine` protocol encapsulates the execution sub-system logic via:
 
 * a state object `self.execution_state` of type `ExecutionState`
-* a state transition function `self.on_payload` which mutates `self.execution_state`
+* a state transition function `self.execute_payload` which applies changes to the `self.execution_state`
+* a function `self.notify_consensus_validated` which signals that the beacon block containing the execution payload
+is valid with respect to the consensus rule set
 
-#### `on_payload`
+*Note*: `execute_payload` and `notify_consensus_validated` are functions accessed through the `EXECUTION_ENGINE` module which instantiates the `ExecutionEngine` protocol.
+
+The body of each of these functions is implementation dependent.
+The Engine API may be used to implement them with an external execution engine.
+
+#### `execute_payload`
 
 ```python
-def on_payload(self: ExecutionEngine, execution_payload: ExecutionPayload) -> bool:
+def execute_payload(self: ExecutionEngine, execution_payload: ExecutionPayload) -> bool:
     """
     Returns ``True`` iff ``execution_payload`` is valid with respect to ``self.execution_state``.
     """
     ...
 ```
 
-The above function is accessed through the `EXECUTION_ENGINE` module which instantiates the `ExecutionEngine` protocol.
+#### `notify_consensus_validated`
+
+```python
+def notify_consensus_validated(self: ExecutionEngine, block_hash: Hash32, valid: bool) -> None:
+    ...
+```
+
+The inputs to this function depend on the result of the state transition. A call to `notify_consensus_validated` must be made after the [`state_transition`](../phase0/beacon-chain.md#beacon-chain-state-transition-function) function finishes. The value of the `valid` parameter must be set as follows:
+
+* `True` if `state_transition` function call succeeds
+* `False` if `state_transition` function call fails
+
+*Note*: The call of the `notify_consensus_validated` function with `valid = True` maps on the `POS_CONSENSUS_VALIDATED` event defined in the [EIP-3675](https://eips.ethereum.org/EIPS/eip-3675#definitions).
 
 ### Block processing
 
@@ -310,7 +331,7 @@ def process_execution_payload(state: BeaconState, payload: ExecutionPayload, exe
     # Verify timestamp
     assert payload.timestamp == compute_timestamp_at_slot(state, state.slot)
     # Verify the execution payload is valid
-    assert execution_engine.on_payload(payload)
+    assert execution_engine.execute_payload(payload)
     # Cache execution payload header
     state.latest_execution_payload_header = ExecutionPayloadHeader(
         parent_hash=payload.parent_hash,

specs/merge/fork-choice.md

@@ -10,8 +10,7 @@
 - [Introduction](#introduction)
 - [Protocols](#protocols)
   - [`ExecutionEngine`](#executionengine)
-    - [`set_head`](#set_head)
-    - [`finalize_block`](#finalize_block)
+    - [`notify_forkchoice_updated`](#notify_forkchoice_updated)
 - [Helpers](#helpers)
   - [`PowBlock`](#powblock)
   - [`get_pow_block`](#get_pow_block)
@@ -32,39 +31,25 @@ This is the modification of the fork choice according to the executable beacon c
 
 ### `ExecutionEngine`
 
-The following methods are added to the `ExecutionEngine` protocol for use in the fork choice:
-
-#### `set_head`
-
-Re-organizes the execution payload chain and corresponding state to make `block_hash` the head.
+*Note*: The `notify_forkchoice_updated` function is added to the `ExecutionEngine` protocol to signal the fork choice updates.
 
 The body of this function is implementation dependent.
-The Consensus API may be used to implement this with an external execution engine.
+The Engine API may be used to implement it with an external execution engine.
 
-```python
-def set_head(self: ExecutionEngine, block_hash: Hash32) -> bool:
-    """
-    Returns True if the ``block_hash`` was successfully set as head of the execution payload chain.
-    """
-    ...
-```
+#### `notify_forkchoice_updated`
 
-#### `finalize_block`
-
-Applies finality to the execution state: it irreversibly persists the chain of all execution payloads
-and corresponding state, up to and including `block_hash`.
-
-The body of this function is implementation dependent.
-The Consensus API may be used to implement this with an external execution engine.
+This function performs two actions *atomically*:
+* Re-organizes the execution payload chain and corresponding state to make `head_block_hash` the head.
+* Applies finality to the execution state: it irreversibly persists the chain of all execution payloads
+and corresponding state, up to and including `finalized_block_hash`.
 
 ```python
-def finalize_block(self: ExecutionEngine, block_hash: Hash32) -> bool:
-    """
-    Returns True if the data up to and including ``block_hash`` was successfully finalized.
-    """
+def notify_forkchoice_updated(self: ExecutionEngine, head_block_hash: Hash32, finalized_block_hash: Hash32) -> None:
     ...
 ```
 
+*Note*: The call of the `notify_forkchoice_updated` function maps on the `POS_FORKCHOICE_UPDATED` event defined in the [EIP-3675](https://eips.ethereum.org/EIPS/eip-3675#definitions).
+
 ## Helpers
 
 ### `PowBlock`

specs/merge/p2p-interface.md

@@ -68,14 +68,10 @@ See the Merge [state transition document](./beacon-chain.md#beaconblockbody) for
 In addition to the gossip validations for this topic from prior specifications,
 the following validations MUST pass before forwarding the `signed_beacon_block` on the network.
 Alias `block = signed_beacon_block.message`, `execution_payload = block.body.execution_payload`.
-- If the merge is complete with respect to the head state -- i.e. `is_merge_complete(state)` --
-  then validate the following:
-  - _[REJECT]_ The block's execution payload must be non-empty --
-    i.e. `execution_payload != ExecutionPayload()`
 - If the execution is enabled for the block -- i.e. `is_execution_enabled(state, block.body)`
   then validate the following:
   - _[REJECT]_ The block's execution payload timestamp is correct with respect to the slot
-    -- i.e. `execution_payload.timestamp == compute_time_at_slot(state, block.slot)`.
+    -- i.e. `execution_payload.timestamp == compute_timestamp_at_slot(state, block.slot)`.
   - _[REJECT]_ Gas used is less than the gas limit --
     i.e. `execution_payload.gas_used <= execution_payload.gas_limit`.
   - _[REJECT]_ The execution payload block hash is not equal to the parent hash --
@@ -89,7 +85,7 @@ Alias `block = signed_beacon_block.message`, `execution_payload = block.body.exe
 
 ### Transitioning the gossip
 
-See gossip transition details found in the [Altair document](../altair/p2p) for
+See gossip transition details found in the [Altair document](../altair/p2p-interface.md#transitioning-the-gossip) for
 details on how to handle transitioning gossip topics for the Merge.
 
 ## The Req/Resp domain