Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Engine API: define payload bodies requests #352

Merged
merged 9 commits into from
Jan 20, 2023
Merged

Engine API: define payload bodies requests #352

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
c03864e
Engine API: define payload bodies requests
mkalinin Jan 11, 2023
68ef355
Apply suggestions from code review
mkalinin Jan 11, 2023
aef7136
Update src/engine/shanghai.md
mkalinin Jan 13, 2023
2e7cef9
Add handling pre-Shanghai bodies
mkalinin Jan 13, 2023
a11ac53
More null values
mkalinin Jan 17, 2023
20264e4
Merge branch 'main' into payload-bodies
mkalinin Jan 20, 2023
0cb7aa0
Merge branch 'payload-bodies' of github.com:mkalinin/execution-apis i…
mkalinin Jan 20, 2023
f60ac17
Provide example responses for ByRange
mkalinin Jan 20, 2023
19fb76e
Note that EL is expected to carry the full history
mkalinin Jan 20, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
73 changes: 72 additions & 1 deletion src/engine/shanghai.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@ Engine API changes introduced in Shanghai.
- [Structures](#structures)
- [WithdrawalV1](#withdrawalv1)
- [ExecutionPayloadV2](#executionpayloadv2)
- [ExecutionPayloadBodyV1](#executionpayloadbodyv1)
- [PayloadAttributesV2](#payloadattributesv2)
- [Methods](#methods)
- [engine_newPayloadV2](#engine_newpayloadv2)
Expand All @@ -24,6 +25,14 @@ Engine API changes introduced in Shanghai.
- [Request](#request-2)
- [Response](#response-2)
- [Specification](#specification-2)
- [engine_getPayloadBodiesByHashV1](#engine_getpayloadbodiesbyhashv1)
- [Request](#request-3)
- [Response](#response-3)
- [Specification](#specification-3)
- [engine_getPayloadBodiesByRangeV1](#engine_getpayloadbodiesbyrangev1)
- [Request](#request-4)
- [Response](#response-4)
- [Specification](#specification-4)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

Expand Down Expand Up @@ -61,6 +70,11 @@ This structure has the syntax of `ExecutionPayloadV1` and appends a single field
- `transactions`: `Array of DATA` - Array of transaction objects, each object is a byte list (`DATA`) representing `TransactionType || TransactionPayload` or `LegacyTransaction` as defined in [EIP-2718](https://eips.ethereum.org/EIPS/eip-2718)
- `withdrawals`: `Array of WithdrawalV1` - Array of withdrawals, each object is an `OBJECT` containing the fields of a `WithdrawalV1` structure.

### ExecutionPayloadBodyV1
This structure contains a body of an execution payload. The fields are encoded as follows:
- `transactions`: `Array of DATA` - Array of transaction objects, each object is a byte list (`DATA`) representing `TransactionType || TransactionPayload` or `LegacyTransaction` as defined in [EIP-2718](https://eips.ethereum.org/EIPS/eip-2718)
- `withdrawals`: `Array of WithdrawalV1` - Array of withdrawals, each object is an `OBJECT` containing the fields of a `WithdrawalV1` structure.

### PayloadAttributesV2

This structure has the syntax of `PayloadAttributesV1` and appends a single field: `withdrawals`.
Expand Down Expand Up @@ -134,4 +148,61 @@ This method follows the same specification as [`engine_forkchoiceUpdatedV1`](./p

This method follows the same specification as [`engine_getPayloadV1`](./paris.md#engine_getpayloadv1) with the addition of the following:

1. Client software **SHOULD** use the sum of the block's priority fees or any other algorithm to determine `blockValue`.
1. Client software **SHOULD** use the sum of the block's priority fees or any other algorithm to determine `blockValue`.

### engine_getPayloadBodiesByHashV1

#### Request

* method: `engine_getPayloadBodiesByHashV1`
* params:
1. `Array of DATA`, 32 Bytes - Array of `block_hash` field values of the `ExecutionPayload` structure
* timeout: 10s

#### Response

* result: `Array of ExecutionPayloadBodyV1` - Array of [`ExecutionPayloadBodyV1`](#ExecutionPayloadBodyV1) objects.
* error: code and message set in case an exception happens while processing the method call.

#### Specification

1. Given array of block hashes client software **MUST** respond with array of `ExecutionPayloadBodyV1` objects with the corresponding hashes respecting the order of block hashes in the input array.

1. Client software **MUST** place responses in the order given in the request, using `null` for any missing blocks. For instance, if the request is `[A.block_hash, B.block_hash, C.block_hash]` and client software has data of payloads `A` and `C`, but doesn't have data of `B`, the response **MUST** be `[A.body, null, C.body]`.

1. Client software **MAY NOT** respond to requests for finalized blocks by hash.

1. Client software **MUST** set `withdrawals` field to `null` for bodies of pre-Shanghai blocks.

1. This request maps to [`BeaconBlocksByRoot`](https://github.com/ethereum/consensus-specs/blob/dev/specs/phase0/p2p-interface.md#beaconblocksbyroot) in the consensus layer `p2p` specification. Callers must be careful to use the execution block hash, instead of the beacon block root.

### engine_getPayloadBodiesByRangeV1

#### Request

* method: `engine_getPayloadBodiesByRangeV1`
* params:
1. `start`: `QUANTITY`, 64 bits - Starting block number
1. `count`: `QUANITTY`, 64 bits - Number of blocks to return
* timeout: 10s

#### Response

* result: `Array of ExecutionPayloadBodyV1` - Array of [`ExecutionPayloadBodyV1`](#ExecutionPayloadBodyV1) objects.
* error: code and message set in case an exception happens while processing the method call.

#### Specification

1. Given a `start` and a `count`, the client software **MUST** respond with array of `ExecutionPayloadBodyV1` objects with the corresponding execution block number respecting the order of blocks in the canonical chain, as selected by the latest `engine_forkchoiceUpdated` call.

1. Client software **MUST** support `count` values of at least 32 blocks.
mkalinin marked this conversation as resolved.
Show resolved Hide resolved

1. Client software **MUST** place `null` in the response array for any blocks that have been pruned or where the request extends past the current latest known block.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Shouldn't this be determinable by the number of responses? Is there ever a case where there would be a gap? Right now, I expect every request over a boundary to be like:

->  engine_getPayloadBodiesByRangeV1(100, 5)
<- [block_101, block_102, null, null, null]

Basically I think the trailing nulls are redundant info.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good point. @arnetheduck why would CL need trailing nulls?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think it matters greatly either way - we have to consider that a syncing client cannot reliably tell if it should be a null or not past its own head, so we can just pick one "style" and go with it.

Arguably, not sending "null" carries the "I don't know" distinction vs "I know there's nothing past that block" as happens with a historical request over a boundary where the EL "knows" there are blocks after the gap, so it might indeed be better to not include the null for any request past head.


1. Client software **MUST** set `withdrawals` field to `null` for bodies of pre-Shanghai blocks.

1. This request maps to [`BeaconBlocksByRange`](https://github.com/ethereum/consensus-specs/blob/dev/specs/phase0/p2p-interface.md#beaconblocksbyrange) in the consensus layer `p2p` specification.

1. Callers must be careful to not confuse `start` with a slot number, instead mapping the slot to a block number. Callers must also be careful to request non-finalized blocks by hash in order to avoid race conditions around the current view of the canonical chain.

1. Callers must be careful to verify the hash of the received blocks when requesting non-finalized parts of the chain since the response is prone to being re-orged.
3 changes: 3 additions & 0 deletions wordlist.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,8 @@
apis
attributesv
bodyv
bodiesbyrangev
bodiesbyhashv
bytecode
configurationv
crypto
Expand Down