From e31fcbd6a9f795100ec6f1de434ffd4555a0f0e2 Mon Sep 17 00:00:00 2001 From: Hsiao-Wei Wang Date: Fri, 28 Apr 2023 23:09:10 +0800 Subject: [PATCH] Add `GetPayloadResponse` for `get_payload` API --- setup.py | 2 +- specs/_features/eip4788/validator.md | 4 +-- specs/bellatrix/validator.md | 19 +++++++++--- specs/capella/validator.md | 14 +++++++-- specs/deneb/validator.md | 46 ++++++++++++++++++++++------ tests/formats/fork_choice/README.md | 4 +-- 6 files changed, 68 insertions(+), 21 deletions(-) diff --git a/setup.py b/setup.py index fc3acb8062..a3e94642e0 100644 --- a/setup.py +++ b/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") diff --git a/specs/_features/eip4788/validator.md b/specs/_features/eip4788/validator.md index 421e297ce9..3140cdb213 100644 --- a/specs/_features/eip4788/validator.md +++ b/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. diff --git a/specs/bellatrix/validator.md b/specs/bellatrix/validator.md index a176d7534e..dea763cde8 100644 --- a/specs/bellatrix/validator.md +++ b/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, diff --git a/specs/capella/validator.md b/specs/capella/validator.md index 644ee476f9..29cff8c611 100644 --- a/specs/capella/validator.md +++ b/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. diff --git a/specs/deneb/validator.md b/specs/deneb/validator.md index b627de023e..6562c91ddd 100644 --- a/specs/deneb/validator.md +++ b/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 diff --git a/tests/formats/fork_choice/README.md b/tests/formats/fork_choice/README.md index c94b959338..3b28837de7 100644 --- a/tests/formats/fork_choice/README.md +++ b/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.