Clean up Gloas specs (part 3) (#4694)

This is an extension of the following PR:

* #4693

This PR focusses on the `builder.md` specifications.

* I didn't feel that "attributions" was a very good word for what
builders do.
  * I've changed this to "activities" which I don't exactly love either.
  * Open to alternatives here.
* I tried to simplify some paragraphs. Less words the better.
* Use `engine_getPayloadV5` (new in fulu) instead of
`engine_getPayloadV4`.
* Lots of other little improvements 🙂

Author: jtraglia

specs/gloas/beacon-chain.md

@@ -656,10 +656,10 @@ out-of-range list access) are considered invalid. State transitions that cause a
 
 The post-state corresponding to a pre-state `state` and a signed execution
 payload envelope `signed_envelope` is defined as
-`process_execution_payload(state, signed_envelope)`. State transitions that
-trigger an unhandled exception (e.g. a failed `assert` or an out-of-range list
-access) are considered invalid. State transitions that cause an `uint64`
-overflow or underflow are also considered invalid.
+`process_execution_payload(state, signed_envelope, execution_engine)`. State
+transitions that trigger an unhandled exception (e.g. a failed `assert` or an
+out-of-range list access) are considered invalid. State transitions that cause
+an `uint64` overflow or underflow are also considered invalid.
 
 ### Modified `process_slot`
 

specs/gloas/builder.md

@@ -11,12 +11,12 @@
   - [Process deposit](#process-deposit)
   - [Builder index](#builder-index)
   - [Activation](#activation)
-- [Builders attributions](#builders-attributions)
-  - [Constructing the payload bid](#constructing-the-payload-bid)
+- [Builder activities](#builder-activities)
+  - [Constructing the `SignedExecutionPayloadBid`](#constructing-the-signedexecutionpayloadbid)
   - [Constructing the `DataColumnSidecar`s](#constructing-the-datacolumnsidecars)
     - [Modified `get_data_column_sidecars`](#modified-get_data_column_sidecars)
     - [Modified `get_data_column_sidecars_from_block`](#modified-get_data_column_sidecars_from_block)
-  - [Constructing the execution payload envelope](#constructing-the-execution-payload-envelope)
+  - [Constructing the `SignedExecutionPayloadEnvelope`](#constructing-the-signedexecutionpayloadenvelope)
   - [Honest payload withheld messages](#honest-payload-withheld-messages)
 
 <!-- mdformat-toc end -->
@@ -26,41 +26,38 @@
 This is an accompanying document which describes the expected actions of a
 "builder" participating in the Ethereum proof-of-stake protocol.
 
-With the Gloas fork, the protocol includes new staked participants of the
-protocol called *Builders*. While Builders are a subset of the validator set,
-they have extra attributions that are optional. Validators may opt to not be
-builders and as such we collect the set of guidelines for those validators that
-want to act as builders in this document.
+With the Gloas fork, the protocol introduces a new type of validator called a
+*builder*. Builders have the option to produce execution payloads by submitting
+bids. This document is a collection of guidelines for builders.
 
 ## Becoming a builder
 
 ### Builder withdrawal credentials
 
-The `withdrawal_credentials` field for builders has a specific format that
-identifies them as registered builders in the network. Builders must use the
-`BUILDER_WITHDRAWAL_PREFIX` to participate in the Gloas mechanism.
+The `withdrawal_credentials` field determines whether a validator is registered
+as a builder on the network. To be recognized as a builder, a validator’s
+`withdrawal_credentials` must use the `BUILDER_WITHDRAWAL_PREFIX`. This prefix
+distinguishes builders from other validator types.
 
-The `withdrawal_credentials` field must be such that:
+The `withdrawal_credentials` field must be:
 
-- `withdrawal_credentials[:1] == BUILDER_WITHDRAWAL_PREFIX` (i.e., `0x03`)
+- `withdrawal_credentials[:1] == BUILDER_WITHDRAWAL_PREFIX` (`0x03`)
 - `withdrawal_credentials[1:12] == b'\x00' * 11`
 - `withdrawal_credentials[12:] == builder_execution_address`
 
-Where `builder_execution_address` is a 20-byte execution layer address that will
-receive:
-
-- Withdrawal rewards (similar to `ETH1_ADDRESS_WITHDRAWAL_PREFIX`)
-- Compounding rewards (builders inherit compounding functionality)
+Where `builder_execution_address` is an execution layer address that will
+receive withdrawals.
 
 ### Submit deposit
 
 Builders follow the same deposit process as regular validators, but with the
 builder-specific withdrawal credentials. The deposit must include:
 
-- `pubkey`: The builder's BLS public key
-- `withdrawal_credentials`: Set with `BUILDER_WITHDRAWAL_PREFIX` (`0x03`)
-- `amount`: At least `MIN_DEPOSIT_AMOUNT`
-- `signature`: BLS signature over the deposit data
+- `pubkey`: The builder's BLS public key.
+- `withdrawal_credentials`: With the `BUILDER_WITHDRAWAL_PREFIX` (`0x03`)
+  prefix.
+- `amount`: At least `MIN_DEPOSIT_AMOUNT` gwei.
+- `signature`: BLS signature over the deposit data.
 
 ### Process deposit
 
@@ -75,54 +72,55 @@ the builder in execution payload bids and envelopes.
 
 ### Activation
 
-Builder activation follows the same process as validator activation.
+Builder activation follows the same process as other validators. Note that the
+validator must have a balance of at least `MIN_ACTIVATION_BALANCE` to become
+eligible for activation.
 
-## Builders attributions
+## Builder activities
 
+Builders have two optional activities: submitting bids and submitting payloads.
 Builders can submit bids to produce execution payloads. They can broadcast these
-bids in the form of `SignedExecutionPayloadBid` objects, these objects encode a
+bids in the form of `SignedExecutionPayloadBid` objects. These objects encode a
 commitment to reveal an execution payload in exchange for a payment. When their
 bids are chosen by the corresponding proposer, builders are expected to
 broadcast an accompanying `SignedExecutionPayloadEnvelope` object honoring the
-commitment.
-
-Thus, builders tasks are divided in two, submitting bids, and submitting
-payloads.
+commitment. If a proposer accepts a builder's bid, the builder will pay the
+proposer what it promised whether it submits the payload or not.
 
-### Constructing the payload bid
+### Constructing the `SignedExecutionPayloadBid`
 
 Builders can broadcast a payload bid for the current or the next slot's proposer
 to include. They produce a `SignedExecutionPayloadBid` as follows.
 
 01. Set `bid.parent_block_hash` to the current head of the execution chain (this
     can be obtained from the beacon state as `state.latest_block_hash`).
-02. Set `bid.parent_block_root` to be the head of the consensus chain (this can
+02. Set `bid.parent_block_root` to be the head of the consensus chain; this can
     be obtained from the beacon state as
     `hash_tree_root(state.latest_block_header)`. The `parent_block_root` and
     `parent_block_hash` must be compatible, in the sense that they both should
     come from the same `state` by the method described in this and the previous
     point.
 03. Construct an execution payload. This can be performed with an external
-    execution engine with a call to `engine_getPayloadV4`.
+    execution engine via a call to `engine_getPayloadV5`.
 04. Set `bid.block_hash` to be the block hash of the constructed payload, that
     is `payload.block_hash`.
-05. Set `bid.gas_limit` to be the gas limit of the constructed payload, that is
-    `payload.gas_limit`.
-06. Set `bid.builder_index` to be the validator index of the builder performing
-    these actions.
-07. Set `bid.slot` to be the slot for which this bid is aimed. This slot
-    **MUST** be either the current slot or the next slot.
-08. Set `bid.value` to be the value that the builder will pay the proposer if
-    the bid is accepted. The builder **MUST** have enough balance to fulfill
-    this bid and all pending payments.
-09. Set `bid.kzg_commitments_root` to be the `hash_tree_root` of the
-    `blobsbundle.commitments` field returned by `engine_getPayloadV4`.
-10. Set `bid.fee_recipient` to be an execution address to receive the payment.
+05. Set `bid.fee_recipient` to be an execution address to receive the payment.
     This address can be obtained from the proposer directly via a request or can
     be set from the withdrawal credentials of the proposer. The burn address can
     be used as a fallback.
+06. Set `bid.gas_limit` to be the gas limit of the constructed payload, that is
+    `payload.gas_limit`.
+07. Set `bid.builder_index` to be the validator index of the builder performing
+    these actions.
+08. Set `bid.slot` to be the slot for which this bid is aimed. This slot
+    **MUST** be either the current slot or the next slot.
+09. Set `bid.value` to be the value (in gwei) that the builder will pay the
+    proposer if the bid is accepted. The builder **MUST** have enough excess
+    balance to fulfill this bid and all pending payments.
+10. Set `bid.kzg_commitments_root` to be the `hash_tree_root` of the
+    `blobsbundle.commitments` field returned by `engine_getPayloadV5`.
 
-After building the `bid`, the builder obtains a `signature` of the bid by using
+After building the `bid`, the builder obtains a `signature` of the bid by using:
 
 ```python
 def get_execution_payload_bid_signature(
@@ -133,23 +131,25 @@ def get_execution_payload_bid_signature(
     return bls.Sign(privkey, signing_root)
 ```
 
-The builder assembles then
+Then the builder assembles
 `signed_execution_payload_bid = SignedExecutionPayloadBid(message=bid, signature=signature)`
 and broadcasts it on the `execution_payload_bid` global gossip topic.
 
 ### Constructing the `DataColumnSidecar`s
 
 #### Modified `get_data_column_sidecars`
 
-*Note*: The function `get_data_column_sidecars` is modified to remove
-`signed_block_header` and `kzg_commitments_inclusion_proof` parameters as header
-and inclusion proof verifications are no longer required in ePBS.
-
 ```python
 def get_data_column_sidecars(
+    # [Modified in Gloas:EIP7732]
+    # Removed `signed_block_header`
+    # [New in Gloas:EIP7732]
     beacon_block_root: Root,
+    # [New in Gloas:EIP7732]
     slot: Slot,
     kzg_commitments: List[KZGCommitment, MAX_BLOB_COMMITMENTS_PER_BLOCK],
+    # [Modified in Gloas:EIP7732]
+    # Removed `kzg_commitments_inclusion_proof`
     cells_and_kzg_proofs: Sequence[
         Tuple[Vector[Cell, CELLS_PER_EXT_BLOB], Vector[KZGProof, CELLS_PER_EXT_BLOB]]
     ],
@@ -207,36 +207,38 @@ def get_data_column_sidecars_from_block(
     )
 ```
 
-### Constructing the execution payload envelope
+### Constructing the `SignedExecutionPayloadEnvelope`
 
 When the proposer publishes a valid `SignedBeaconBlock` containing a signed
 commitment by the builder, the builder is later expected to broadcast the
 corresponding `SignedExecutionPayloadEnvelope` that fulfills this commitment.
 See below for a special case of an *honestly withheld payload*.
 
-To construct the `execution_payload_envelope` the builder must perform the
-following steps. We alias `block` to be the corresponding beacon block and alias
-`bid` to be the committed `ExecutionPayloadBid` in
+To construct the `ExecutionPayloadEnvelope` the builder must perform the
+following steps. We alias `block` to be the corresponding `BeaconBlock` and
+alias `bid` to be the committed `ExecutionPayloadBid` in
 `block.body.signed_execution_payload_bid.message`.
 
-1. Set the `payload` field to be the `ExecutionPayload` constructed when
-   creating the corresponding bid. This payload **MUST** have the same block
-   hash as `bid.block_hash`.
-2. Set the `execution_requests` field to be the `ExecutionRequests` associated
+1. Set `envelope.payload` to be the `ExecutionPayload` constructed when creating
+   the corresponding bid. This payload **MUST** have the same block hash as
+   `envelope.bid.block_hash`.
+2. Set `envelope.execution_requests` to be the `ExecutionRequests` associated
    with `payload`.
-3. Set the `builder_index` field to be the validator index of the builder
+3. Set `envelope.builder_index` to be the validator index of the builder
    performing these steps. This field **MUST** be `bid.builder_index`.
-4. Set `beacon_block_root` to be `hash_tree_root(block)`.
-5. Set `slot` to be `block.slot`.
-6. Set `blob_kzg_commitments` to be the `commitments` field of the blobs bundle
-   constructed when constructing the bid. This field **MUST** have a
-   `hash_tree_root` equal to `bid.blob_kzg_commitments_root`.
+4. Set `envelope.beacon_block_root` to be `hash_tree_root(block)`.
+5. Set `envelope.slot` to be `block.slot`.
+6. Set `envelope.blob_kzg_commitments` to be the `commitments` field of the
+   blobs bundle constructed when constructing the bid. This field **MUST** have
+   a `hash_tree_root` equal to `bid.blob_kzg_commitments_root`.
 
-After setting these parameters, the builder should run
-`process_execution_payload(state, signed_envelope, verify=False)` and this
-function should not trigger an exception.
+After setting these parameters, the builder assembles
+`signed_execution_payload_envelope = SignedExecutionPayloadEnvelope(message=envelope, signature=BLSSignature())`,
+then verify that the envelope is valid with
+`process_execution_payload(state, signed_execution_payload_envelope, execution_engine, verify=False)`.
+This function should not trigger an exception.
 
-6. Set `state_root` to `hash_tree_root(state)`.
+7. Set `envelope.state_root` to `hash_tree_root(state)`.
 
 After preparing the `envelope` the builder should sign the envelope using:
 
@@ -249,7 +251,7 @@ def get_execution_payload_envelope_signature(
     return bls.Sign(privkey, signing_root)
 ```
 
-The builder assembles then
+Then the builder assembles
 `signed_execution_payload_envelope = SignedExecutionPayloadEnvelope(message=envelope, signature=signature)`
 and broadcasts it on the `execution_payload` global gossip topic.