Merge pull request #3341 from ethereum/add-GetPayloadResponse

Add `GetPayloadResponse` dataclass for `get_payload` API

setup.py

@@ -588,7 +588,7 @@ def notify_forkchoice_updated(self: ExecutionEngine,
                                   payload_attributes: Optional[PayloadAttributes]) -> Optional[PayloadId]:
         pass
 
-    def get_payload(self: ExecutionEngine, payload_id: PayloadId) -> ExecutionPayload:
+    def get_payload(self: ExecutionEngine, payload_id: PayloadId) -> GetPayloadResponse:
         # pylint: disable=unused-argument
         raise NotImplementedError("no default block production")
 

specs/_features/eip4788/validator.md

@@ -13,7 +13,7 @@
 - [Helpers](#helpers)
 - [Protocols](#protocols)
   - [`ExecutionEngine`](#executionengine)
-    - [`get_payload`](#get_payload)
+    - [Modified `get_payload`](#modified-get_payload)
 - [Beacon chain responsibilities](#beacon-chain-responsibilities)
   - [Block proposal](#block-proposal)
     - [Constructing the `BeaconBlockBody`](#constructing-the-beaconblockbody)
@@ -40,7 +40,7 @@ Please see related Beacon Chain doc before continuing and use them as a referenc
 
 ### `ExecutionEngine`
 
-#### `get_payload`
+#### Modified `get_payload`
 
 `get_payload` returns the upgraded EIP-4788 `ExecutionPayload` type.
 

specs/bellatrix/validator.md

@@ -9,6 +9,7 @@
 - [Introduction](#introduction)
 - [Prerequisites](#prerequisites)
 - [Helpers](#helpers)
+  - [`GetPayloadResponse`](#getpayloadresponse)
   - [`get_pow_block_at_terminal_total_difficulty`](#get_pow_block_at_terminal_total_difficulty)
   - [`get_terminal_pow_block`](#get_terminal_pow_block)
 - [Protocols](#protocols)
@@ -36,6 +37,14 @@ Please see related Beacon Chain doc before continuing and use them as a referenc
 
 ## Helpers
 
+### `GetPayloadResponse`
+
+```python
+@dataclass
+class GetPayloadResponse(object):
+    execution_payload: ExecutionPayload
+```
+
 ### `get_pow_block_at_terminal_total_difficulty`
 
 ```python
@@ -83,13 +92,13 @@ The Engine API may be used to implement it with an external execution engine.
 
 #### `get_payload`
 
-Given the `payload_id`, `get_payload` returns the most recent version of the execution payload that
-has been built since the corresponding call to `notify_forkchoice_updated` method.
+Given the `payload_id`, `get_payload` returns `GetPayloadResponse` with the most recent version of
+the execution payload that has been built since the corresponding call to `notify_forkchoice_updated` method.
 
 ```python
-def get_payload(self: ExecutionEngine, payload_id: PayloadId) -> ExecutionPayload:
+def get_payload(self: ExecutionEngine, payload_id: PayloadId) -> GetPayloadResponse:
     """
-    Return ``execution_payload`` object.
+    Return ``GetPayloadResponse`` object.
     """
     ...
 ```
@@ -162,7 +171,7 @@ def get_execution_payload(payload_id: Optional[PayloadId], execution_engine: Exe
         # Pre-merge, empty payload
         return ExecutionPayload()
     else:
-        return execution_engine.get_payload(payload_id)
+        return execution_engine.get_payload(payload_id).execution_payload
 ```
 
 *Note*: It is recommended for a validator to call `prepare_execution_payload` as soon as input parameters become known,

specs/capella/validator.md

@@ -11,9 +11,10 @@
 - [Introduction](#introduction)
 - [Prerequisites](#prerequisites)
 - [Helpers](#helpers)
+  - [Modified `GetPayloadResponse`](#modified-getpayloadresponse)
 - [Protocols](#protocols)
   - [`ExecutionEngine`](#executionengine)
-    - [`get_payload`](#get_payload)
+    - [Modified `get_payload`](#modified-get_payload)
 - [Beacon chain responsibilities](#beacon-chain-responsibilities)
   - [Block proposal](#block-proposal)
     - [Constructing the `BeaconBlockBody`](#constructing-the-beaconblockbody)
@@ -39,11 +40,20 @@ Please see related Beacon Chain doc before continuing and use them as a referenc
 
 ## Helpers
 
+### Modified `GetPayloadResponse`
+
+```python
+@dataclass
+class GetPayloadResponse(object):
+    execution_payload: ExecutionPayload
+    block_value: uint256
+```
+
 ## Protocols
 
 ### `ExecutionEngine`
 
-#### `get_payload`
+#### Modified `get_payload`
 
 `get_payload` returns the upgraded Capella `ExecutionPayload` type.
 

specs/deneb/validator.md

@@ -11,7 +11,11 @@
 - [Introduction](#introduction)
 - [Prerequisites](#prerequisites)
 - [Helpers](#helpers)
-  - [`get_blobs_and_kzg_commitments`](#get_blobs_and_kzg_commitments)
+  - [`BlobsBundle`](#blobsbundle)
+  - [Modified `GetPayloadResponse`](#modified-getpayloadresponse)
+- [Protocol](#protocol)
+  - [`ExecutionEngine`](#executionengine)
+    - [Modified `get_payload`](#modified-get_payload)
 - [Beacon chain responsibilities](#beacon-chain-responsibilities)
   - [Block and sidecar proposal](#block-and-sidecar-proposal)
     - [Constructing the `BeaconBlockBody`](#constructing-the-beaconblockbody)
@@ -36,17 +40,40 @@ Please see related Beacon Chain doc before continuing and use them as a referenc
 
 ## Helpers
 
-### `get_blobs_and_kzg_commitments`
+### `BlobsBundle`
 
-The interface to retrieve blobs and corresponding kzg commitments.
+```python
+@dataclass
+class BlobsBundle(object):
+    commitments: Sequence[KZGCommitment]
+    proofs: Sequence[KZGProof]
+    blobs: Sequence[Blob]
+```
+
+### Modified `GetPayloadResponse`
+
+```python
+@dataclass
+class GetPayloadResponse(object):
+    execution_payload: ExecutionPayload
+    block_value: uint256
+    blobs_bundle: BlobsBundle
+```
+
+## Protocol
+
+### `ExecutionEngine`
+
+#### Modified `get_payload`
 
-Note: This API is *unstable*. `get_blobs_and_kzg_commitments` and `get_payload` may be unified.
-Implementers may also retrieve blobs individually per transaction.
+Given the `payload_id`, `get_payload` returns the most recent version of the execution payload that
+has been built since the corresponding call to `notify_forkchoice_updated` method.
 
 ```python
-def get_blobs_and_kzg_commitments(
-    payload_id: PayloadId
-) -> Tuple[Sequence[Blob], Sequence[KZGCommitment], Sequence[KZGProof]]:
+def get_payload(self: ExecutionEngine, payload_id: PayloadId) -> GetPayloadResponse:
+    """
+    Return ExecutionPayload, uint256, BlobsBundle objects.
+    """
     # pylint: disable=unused-argument
     ...
 ```
@@ -62,7 +89,8 @@ All validator responsibilities remain unchanged other than those noted below.
 ##### Blob KZG commitments
 
 1. After retrieving the execution payload from the execution engine as specified in Capella,
-use the `payload_id` to retrieve `blobs` and `blob_kzg_commitments` via `get_blobs_and_kzg_commitments(payload_id)`.
+use the `payload_id` to retrieve `blobs`, `blob_kzg_commitments`, and `blob_kzg_proofs`
+via `get_payload(payload_id).blobs_bundle`.
 2. Validate `blobs` and `blob_kzg_commitments`:
 
 ```python

tests/formats/fork_choice/README.md

@@ -114,8 +114,8 @@ Optional step for optimistic sync tests.
 
 This step sets the [`payloadStatus`](https://github.com/ethereum/execution-apis/blob/main/src/engine/specification.md#PayloadStatusV1)
 value that Execution Layer client mock returns in responses to the following Engine API calls:
-* [`engine_newPayloadV1(payload)`](https://github.com/ethereum/execution-apis/blob/main/src/engine/specification.md#engine_newpayloadv1) if `payload.blockHash == payload_info.block_hash`
-* [`engine_forkchoiceUpdatedV1(forkchoiceState, ...)`](https://github.com/ethereum/execution-apis/blob/main/src/engine/specification.md#engine_forkchoiceupdatedv1) if `forkchoiceState.headBlockHash == payload_info.block_hash`
+* [`engine_newPayloadV1(payload)`](https://github.com/ethereum/execution-apis/blob/main/src/engine/paris.md#engine_newpayloadv1) if `payload.blockHash == payload_info.block_hash`
+* [`engine_forkchoiceUpdatedV1(forkchoiceState, ...)`](https://github.com/ethereum/execution-apis/blob/main/src/engine/paris.md#engine_forkchoiceupdatedv1) if `forkchoiceState.headBlockHash == payload_info.block_hash`
 
 *Note:* Status of a payload must be *initialized* via `on_payload_info` before the corresponding `on_block` execution step.