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: add getPayloadBodiesByRangeV1 to #146 #218

Closed
wants to merge 12 commits into from
Closed

Engine API: add getPayloadBodiesByRangeV1 to #146 #218

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
b1a4ebd
Engine API: add getPayloadBodies method
mkalinin Dec 10, 2021
6be1088
Engine API: fix spellchecker
mkalinin Dec 10, 2021
f500c48
Engine API: fix spellchecker. Take 2
mkalinin Dec 10, 2021
b490341
Merge branch 'main' into get-payload-bodies
mkalinin Feb 2, 2022
f9ee0ff
Merge remote-tracking branch 'mkalinin/get-payload-bodies' into lots-…
arnetheduck May 6, 2022
832c938
add by-range request
arnetheduck May 6, 2022
1091c2d
fight spellchecker
arnetheduck May 6, 2022
e189c5b
Update src/engine/specification.md
arnetheduck May 10, 2022
e19aa80
Update src/engine/specification.md
arnetheduck May 10, 2022
19c2e8a
Merge remote-tracking branch 'origin/main' into lots-of-bodies
arnetheduck May 31, 2022
e1989ed
`ByRoot` -> `ByHash`
arnetheduck May 31, 2022
de8fd3d
Allow `nil` in response
arnetheduck Sep 29, 2022
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
68 changes: 65 additions & 3 deletions src/engine/specification.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@ This document specifies the Engine API methods that the Consensus Layer uses to
- [Timeouts](#timeouts)
- [Structures](#structures)
- [ExecutionPayloadV1](#executionpayloadv1)
- [ExecutionPayloadBodyV1](#executionpayloadbodyv1)
- [ForkchoiceStateV1](#forkchoicestatev1)
- [PayloadAttributesV1](#payloadattributesv1)
- [PayloadStatusV1](#payloadstatusv1)
Expand All @@ -41,6 +42,14 @@ This document specifies the Engine API methods that the Consensus Layer uses to
- [Request](#request-3)
- [Response](#response-3)
- [Specification](#specification-3)
- [engine_getPayloadBodiesByHashV1](#engine_getpayloadbodiesByHashV1)
- [Request](#request-4)
- [Response](#response-4)
- [Specification](#specification-4)
- [engine_getPayloadBodiesByRangeV1](#engine_getpayloadbodiesbyrangev1)
- [Request](#request-5)
- [Response](#response-5)
- [Specification](#specification-5)

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

Expand Down Expand Up @@ -112,7 +121,7 @@ The list of error codes introduced by this specification can be found below.
| -32700 | Parse error | Invalid JSON was received by the server. |
| -32600 | Invalid Request | The JSON sent is not a valid Request object. |
| -32601 | Method not found | The method does not exist / is not available. |
| -32602 | Invalid params | Invalid method parameter(s). |
| -32602 | Invalid params | Invalid method parameter(s). |
| -32603 | Internal error | Internal JSON-RPC error. |
| -32000 | Server error | Generic client error while processing request. |
| -38001 | Unknown payload | Payload does not exist / is not available. |
Expand Down Expand Up @@ -174,6 +183,11 @@ This structure maps on the [`ExecutionPayload`](https://github.com/ethereum/cons
- `blockHash`: `DATA`, 32 Bytes
- `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)

### 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)

### ForkchoiceStateV1

This structure encapsulates the fork choice state. The fields are encoded as follows:
Expand Down Expand Up @@ -255,7 +269,7 @@ The payload build process is specified as follows:
#### Request

* method: `engine_newPayloadV1`
* params:
* params:
1. [`ExecutionPayloadV1`](#ExecutionPayloadV1)
* timeout: 8s

Expand Down Expand Up @@ -292,7 +306,7 @@ The payload build process is specified as follows:
#### Request

* method: "engine_forkchoiceUpdatedV1"
* params:
* params:
1. `forkchoiceState`: `Object` - instance of [`ForkchoiceStateV1`](#ForkchoiceStateV1)
2. `payloadAttributes`: `Object|null` - instance of [`PayloadAttributesV1`](#PayloadAttributesV1) or `null`
* timeout: 8s
Expand Down Expand Up @@ -389,3 +403,51 @@ The payload build process is specified as follows:
6. Considering the absence of the `TERMINAL_BLOCK_NUMBER` setting, Consensus Layer client software **MAY** use `0` value for the `terminalBlockNumber` field in the input parameters of this call.

[json-rpc-spec]: https://playground.open-rpc.org/?schemaUrl=https://raw.githubusercontent.com/ethereum/execution-apis/assembled-spec/openrpc.json&uiSchema[appBar][ui:splitView]=false&uiSchema[appBar][ui:input]=false&uiSchema[appBar][ui:examplesDropdown]=false

### engine_getPayloadBodiesByHashV1

#### Request

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

#### 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 `nil` 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, nil, C.body]`.

1. Clients that support `engine_getPayloadBodiesByRangeV1` **MAY NOT** respond to requests for finalized blocks by hash.
Copy link
Contributor

Choose a reason for hiding this comment

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

This is because they may have pruned them?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Same as CL really - this allows us to drop hash-based indices and retrieve blocks from linear archival storage - the aim with this clause is to ensure that CL:s use the linear request for prefinality blocks and only "top up" with by-hash requests where forks are possible.


1. This request maps to [`BeaconBlocksByRoot`](https://github.com/ethereum/consensus-specs/blob/dev/specs/phase0/p2p-interface.md#beaconblocksbyrange=) in the consensus layer `p2p` specification. Callers must be careful to use the execution block root, instead of the beacon block root.
arnetheduck marked this conversation as resolved.
Show resolved Hide resolved

### 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

#### 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.
* Clients that don't support fetching bodies by range **MUST** return the error code `-32601 Method not found The method does not exist / is not available.`. Callers may then revert to `engine_getPayloadBodiesByHashV1`.

#### 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 `forkChoiceUpdated` call.
Copy link
Contributor

Choose a reason for hiding this comment

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

I think we need to add an error condition for if the EL does not have the requisite data (either a malformed CL request or some sort of failure/resync on EL side

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Updated response to give nil when blocks are missing

1. Client software **MUST** support `count` values of at least 32 blocks.
1. Client software **MUST** place `nil` in the response array for any blocks that have been pruned or where the request extends past the current latest known block.

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 root 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