Skip to content

Commit ee3df5b

Browse files
mkalininralexstokeslightclient
authored
Engine API: Cancun specification (ethereum#420)
* Define cancun with blob-extension spec * Cosmetic fixes * Add toc * Deprecate engine_exchangeTransitionConfigurationV1 * Define engine api openrpc schema for cancun * Update src/engine/cancun.md Co-authored-by: Alex Stokes <r.alex.stokes@gmail.com> * Add parentBeaconBlockRoot to schema * Apply suggestions from code review Co-authored-by: lightclient <14004106+lightclient@users.noreply.github.com> * Add payloadattributesv3 to Cancun * Apply suggestions by @ralexstokes Co-authored-by: Alex Stokes <r.alex.stokes@gmail.com> * Add parentBeaconBlockRoot to schema * Tag parameters of newPayloadV3 * Couple of cosmetic fixes --------- Co-authored-by: Alex Stokes <r.alex.stokes@gmail.com> Co-authored-by: lightclient <14004106+lightclient@users.noreply.github.com>
1 parent b231971 commit ee3df5b

File tree

6 files changed

+367
-0
lines changed

6 files changed

+367
-0
lines changed

‎src/engine/cancun.md

Lines changed: 172 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,172 @@
1+
# Engine API -- Cancun
2+
3+
Engine API changes introduced in Cancun.
4+
5+
This specificaiton is based on and extends [Engine API - Shanghai](./shanghai.md) specification.
6+
7+
## Table of contents
8+
9+
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
10+
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
11+
12+
- [Structures](#structures)
13+
- [ExecutionPayloadV3](#executionpayloadv3)
14+
- [BlobsBundleV1](#blobsbundlev1)
15+
- [PayloadAttributesV3](#payloadattributesv3)
16+
- [Methods](#methods)
17+
- [engine_newPayloadV3](#engine_newpayloadv3)
18+
- [Request](#request)
19+
- [Response](#response)
20+
- [Specification](#specification)
21+
- [engine_forkchoiceUpdatedV3](#engine_forkchoiceupdatedv3)
22+
- [Request](#request-1)
23+
- [Response](#response-1)
24+
- [Specification](#specification-1)
25+
- [engine_getPayloadV3](#engine_getpayloadv3)
26+
- [Request](#request-2)
27+
- [Response](#response-2)
28+
- [Specification](#specification-2)
29+
- [Deprecate `engine_exchangeTransitionConfigurationV1`](#deprecate-engine_exchangetransitionconfigurationv1)
30+
31+
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
32+
33+
## Structures
34+
35+
### ExecutionPayloadV3
36+
37+
This structure has the syntax of [`ExecutionPayloadV2`](./shanghai.md#executionpayloadv2) and appends the new fields: `dataGasUsed` and `excessDataGas`.
38+
39+
- `parentHash`: `DATA`, 32 Bytes
40+
- `feeRecipient`: `DATA`, 20 Bytes
41+
- `stateRoot`: `DATA`, 32 Bytes
42+
- `receiptsRoot`: `DATA`, 32 Bytes
43+
- `logsBloom`: `DATA`, 256 Bytes
44+
- `prevRandao`: `DATA`, 32 Bytes
45+
- `blockNumber`: `QUANTITY`, 64 Bits
46+
- `gasLimit`: `QUANTITY`, 64 Bits
47+
- `gasUsed`: `QUANTITY`, 64 Bits
48+
- `timestamp`: `QUANTITY`, 64 Bits
49+
- `extraData`: `DATA`, 0 to 32 Bytes
50+
- `baseFeePerGas`: `QUANTITY`, 256 Bits
51+
- `blockHash`: `DATA`, 32 Bytes
52+
- `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)
53+
- `withdrawals`: `Array of WithdrawalV1` - Array of withdrawals, each object is an `OBJECT` containing the fields of a `WithdrawalV1` structure.
54+
- `dataGasUsed`: `QUANTITY`, 64 bits
55+
- `excessDataGas`: `QUANTITY`, 64 Bits
56+
57+
### BlobsBundleV1
58+
59+
The fields are encoded as follows:
60+
61+
- `commitments`: `Array of DATA` - Array of `KZGCommitment` as defined in [EIP-4844](https://eips.ethereum.org/EIPS/eip-4844), 48 bytes each (`DATA`).
62+
- `proofs`: `Array of DATA` - Array of `KZGProof` as defined in [EIP-4844](https://eips.ethereum.org/EIPS/eip-4844), 48 bytes each (`DATA`).
63+
- `blobs`: `Array of DATA` - Array of blobs, each blob is `FIELD_ELEMENTS_PER_BLOB * BYTES_PER_FIELD_ELEMENT = 4096 * 32 = 131072` bytes (`DATA`) representing a SSZ-encoded `Blob` as defined in [EIP-4844](https://eips.ethereum.org/EIPS/eip-4844)
64+
65+
All of the above three arrays **MUST** be of same length.
66+
67+
### PayloadAttributesV3
68+
69+
This structure has the syntax of [`PayloadAttributesV2`](./shanghai.md#payloadattributesv2) and appends a single field: `parentBeaconBlockRoot`.
70+
71+
- `timestamp`: `QUANTITY`, 64 Bits - value for the `timestamp` field of the new payload
72+
- `prevRandao`: `DATA`, 32 Bytes - value for the `prevRandao` field of the new payload
73+
- `suggestedFeeRecipient`: `DATA`, 20 Bytes - suggested value for the `feeRecipient` field of the new payload
74+
- `withdrawals`: `Array of WithdrawalV1` - Array of withdrawals, each object is an `OBJECT` containing the fields of a `WithdrawalV1` structure.
75+
- `parentBeaconBlockRoot`: `DATA`, 32 Bytes - Root of the parent beacon block.
76+
77+
## Methods
78+
79+
### engine_newPayloadV3
80+
81+
#### Request
82+
83+
* method: `engine_newPayloadV3`
84+
* params:
85+
1. `executionPayload`: [`ExecutionPayloadV3`](#ExecutionPayloadV3).
86+
2. `expectedBlobVersionedHashes`: `Array of DATA`, 32 Bytes - Array of expected blob versioned hashes to validate.
87+
3. `parentBeaconBlockRoot`: `DATA`, 32 Bytes - Root of the parent beacon block.
88+
89+
Client software **MUST** return `-32602: Invalid params` error unless all parameters and their fields are provided with non-`null` values.
90+
91+
#### Response
92+
93+
Refer to the response for [`engine_newPayloadV2`](./shanghai.md#engine_newpayloadv2).
94+
95+
#### Specification
96+
97+
This method follows the same specification as [`engine_newPayloadV2`](./shanghai.md#engine_newpayloadv2) with the addition of the following:
98+
99+
1. Given the expected array of blob versioned hashes client software **MUST** run its validation by taking the following steps:
100+
1. Obtain the actual array by concatenating blob versioned hashes lists (`tx.blob_versioned_hashes`) of each [blob transaction](https://eips.ethereum.org/EIPS/eip-4844#new-transaction-type) included in the payload, respecting the order of inclusion. If the payload has no blob transactions the expected array **MUST** be `[]`.
101+
2. Return `{status: INVALID, latestValidHash: null, validationError: errorMessage | null}` if the expected and the actual arrays don't match.
102+
103+
This validation **MUST** be instantly run in all cases even during active sync process.
104+
105+
2. Client software **MUST** return `-38005: Unsupported fork` error if the `timestamp` of the payload is less than the Cancun activation timestamp.
106+
107+
### engine_forkchoiceUpdatedV3
108+
109+
#### Request
110+
111+
* method: `engine_forkchoiceUpdatedV3`
112+
* params:
113+
1. `forkchoiceState`: [`ForkchoiceStateV1`](./paris.md#ForkchoiceStateV1).
114+
2. `payloadAttributes`: `Object|null` - Instance of [`PayloadAttributesV3`](#payloadattributesv3) or `null`.
115+
* timeout: 8s
116+
117+
Client software **MUST** return `-32602: Invalid params` error unless:
118+
* every field of `forkchoiceState` is provided with non-`null` value,
119+
* every field of `payloadAttributes` is provided with non-`null` values when `payloadAttributes` is not `null`.
120+
121+
#### Response
122+
123+
Refer to the response for [`engine_forkchoiceUpdatedV2`](./shanghai.md#engine_forkchoiceupdatedv2).
124+
125+
#### Specification
126+
127+
This method follows the same specification as [`engine_forkchoiceUpdatedV2`](./shanghai.md#engine_forkchoiceupdatedv2) with addition of the following:
128+
129+
1. Client software **MUST** return `-38005: Unsupported fork` error if the `payloadAttributes.timestamp` is less than the Cancun activation timestamp.
130+
131+
### engine_getPayloadV3
132+
133+
The response of this method is extended with [`BlobsBundleV1`](#blobsbundlev1) containing the blobs, their respective KZG commitments
134+
and proofs corresponding to the `versioned_hashes` included in the blob transactions of the execution payload.
135+
136+
#### Request
137+
138+
* method: `engine_getPayloadV3`
139+
* params:
140+
1. `payloadId`: `DATA`, 8 Bytes - Identifier of the payload build process
141+
* timeout: 1s
142+
143+
#### Response
144+
145+
* result: `object`
146+
- `executionPayload`: [`ExecutionPayloadV3`](#ExecutionPayloadV3)
147+
- `blockValue` : `QUANTITY`, 256 Bits - The expected value to be received by the `feeRecipient` in wei
148+
- `blobsBundle`: [`BlobsBundleV1`](#BlobsBundleV1) - Bundle with data corresponding to blob transactions included into `executionPayload`
149+
* error: code and message set in case an exception happens while getting the payload.
150+
151+
#### Specification
152+
153+
Refer to the specification for [`engine_getPayloadV2`](./shanghai.md#engine_getpayloadv2) with addition of the following:
154+
155+
1. The call **MUST** return `blobsBundle` with empty `blobs`, `commitments` and `proofs` if the payload doesn't contain any blob transactions.
156+
157+
2. The call **MUST** return `commitments` matching the versioned hashes of the transactions list of the execution payload, in the same order,
158+
i.e. `assert verify_kzg_commitments_against_transactions(payload.transactions, blobsBundle.commitments)` (see EIP-4844 consensus-specs).
159+
160+
3. The call **MUST** return `blobs` and `proofs` that match the `commitments` list, i.e. `assert len(blobsBundle.commitments) == len(blobsBundle.blobs) == len(blobsBundle.proofs)` and `assert verify_blob_kzg_proof_batch(blobsBundle.blobs, blobsBundle.commitments, blobsBundle.proofs)`.
161+
162+
4. Client software **MUST** return `-38005: Unsupported fork` error if the `timestamp` of the built payload is less than the Cancun activation timestamp.
163+
164+
### Deprecate `engine_exchangeTransitionConfigurationV1`
165+
166+
This document introduces deprecation of [`engine_exchangeTransitionConfigurationV1`](./paris.md#engine_exchangetransitionconfigurationv1). The deprecation is specified as follows:
167+
168+
1. Consensus layer clients **MUST NOT** call this method.
169+
170+
2. Execution layer clients **MUST NOT** surface an error message to the user if this method is not called.
171+
172+
3. Consensus and execution layer clients **MAY** remove support of this method after Cancun. If no longer supported, this method **MUST** be removed from the [`engine_exchangeCapabilities`](./common.md#engine_exchangecapabilities) request or response list depending on whether it is consensus or execution layer client.

‎src/engine/openrpc/methods/forkchoice.yaml

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,3 +44,30 @@
4444
message: Invalid forkchoice state
4545
- code: -38003
4646
message: Invalid payload attributes
47+
- name: engine_forkchoiceUpdatedV3
48+
summary: Updates the forkchoice state
49+
externalDocs:
50+
description: Method specification
51+
url: https://github.com/ethereum/execution-apis/blob/main/src/engine/cancun.md#engine_forkchoiceupdatedv3
52+
params:
53+
- name: Forkchoice state
54+
required: true
55+
schema:
56+
$ref: '#/components/schemas/ForkchoiceStateV1'
57+
- name: Payload attributes
58+
required: false
59+
schema:
60+
$ref: '#/components/schemas/PayloadAttributesV3'
61+
result:
62+
name: Response object
63+
schema:
64+
$ref: '#/components/schemas/ForkchoiceUpdatedResponseV1'
65+
errors:
66+
- code: -38002
67+
message: Invalid forkchoice state
68+
- code: -38003
69+
message: Invalid payload attributes
70+
- code: -32602
71+
message: Invalid params
72+
- code: -38005
73+
message: Unsupported fork

‎src/engine/openrpc/methods/payload.yaml

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,35 @@
3131
errors:
3232
- code: -32602
3333
message: Invalid params
34+
- name: engine_newPayloadV3
35+
summary: Runs execution payload validation
36+
externalDocs:
37+
description: Method specification
38+
url: https://github.com/ethereum/execution-apis/blob/main/src/engine/cancun.md#engine_newpayloadv3
39+
params:
40+
- name: Execution payload
41+
required: true
42+
schema:
43+
$ref: '#/components/schemas/ExecutionPayloadV3'
44+
- name: Expected blob versioned hashes
45+
required: true
46+
schema:
47+
type: array
48+
items:
49+
$ref: '#/components/schemas/hash32'
50+
- name: Root of the parent beacon block
51+
required: true
52+
schema:
53+
$ref: '#/components/schemas/hash32'
54+
result:
55+
name: Payload status
56+
schema:
57+
$ref: '#/components/schemas/PayloadStatusNoInvalidBlockHash'
58+
errors:
59+
- code: -32602
60+
message: Invalid params
61+
- code: -38005
62+
message: Unsupported fork
3463
- name: engine_getPayloadV1
3564
summary: Obtains execution payload from payload build process
3665
externalDocs:
@@ -77,6 +106,39 @@
77106
errors:
78107
- code: -38001
79108
message: Unknown payload
109+
- name: engine_getPayloadV3
110+
summary: Obtains execution payload from payload build process
111+
externalDocs:
112+
description: Method specification
113+
url: https://github.com/ethereum/execution-apis/blob/main/src/engine/cancun.md#engine_getpayloadv3
114+
params:
115+
- name: Payload id
116+
required: true
117+
schema:
118+
$ref: '#/components/schemas/bytes8'
119+
result:
120+
name: Response object
121+
schema:
122+
type: object
123+
required:
124+
- executionPayload
125+
- blockValue
126+
- blobsBundle
127+
properties:
128+
executionPayload:
129+
title: Execution payload
130+
$ref: '#/components/schemas/ExecutionPayloadV3'
131+
blockValue:
132+
title: Expected fee value
133+
$ref: '#/components/schemas/uint256'
134+
blobsBundle:
135+
title: Blobs bundle
136+
$ref: '#/components/schemas/BlobsBundleV1'
137+
errors:
138+
- code: -38001
139+
message: Unknown payload
140+
- code: -38005
141+
message: Unsupported fork
80142
- name: engine_getPayloadBodiesByHashV1
81143
summary: Given block hashes returns bodies of the corresponding execution payloads
82144
externalDocs:

‎src/engine/openrpc/schemas/forkchoice.yaml

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -64,3 +64,24 @@ PayloadAttributesV2:
6464
type: array
6565
items:
6666
$ref: '#/components/schemas/WithdrawalV1'
67+
PayloadAttributesV3:
68+
title: Payload attributes object V3
69+
type: object
70+
required:
71+
- timestamp
72+
- prevRandao
73+
- suggestedFeeRecipient
74+
- withdrawals
75+
- parentBeaconBlockRoot
76+
properties:
77+
timestamp:
78+
$ref: '#/components/schemas/PayloadAttributesV2/properties/timestamp'
79+
prevRandao:
80+
$ref: '#/components/schemas/PayloadAttributesV2/properties/prevRandao'
81+
suggestedFeeRecipient:
82+
$ref: '#/components/schemas/PayloadAttributesV2/properties/suggestedFeeRecipient'
83+
withdrawals:
84+
$ref: '#/components/schemas/PayloadAttributesV2/properties/withdrawals'
85+
parentBeaconBlockRoot:
86+
title: Parent beacon block root
87+
$ref: '#/components/schemas/hash32'

‎src/engine/openrpc/schemas/payload.yaml

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -185,6 +185,64 @@ ExecutionPayloadV2:
185185
type: array
186186
items:
187187
$ref: '#/components/schemas/WithdrawalV1'
188+
ExecutionPayloadV3:
189+
title: Execution payload object V3
190+
type: object
191+
required:
192+
- parentHash
193+
- feeRecipient
194+
- stateRoot
195+
- receiptsRoot
196+
- logsBloom
197+
- prevRandao
198+
- blockNumber
199+
- gasLimit
200+
- gasUsed
201+
- timestamp
202+
- extraData
203+
- baseFeePerGas
204+
- blockHash
205+
- transactions
206+
- withdrawals
207+
- dataGasUsed
208+
- excessDataGas
209+
properties:
210+
parentHash:
211+
$ref: '#/components/schemas/ExecutionPayloadV2/properties/parentHash'
212+
feeRecipient:
213+
$ref: '#/components/schemas/ExecutionPayloadV2/properties/feeRecipient'
214+
stateRoot:
215+
$ref: '#/components/schemas/ExecutionPayloadV2/properties/stateRoot'
216+
receiptsRoot:
217+
$ref: '#/components/schemas/ExecutionPayloadV2/properties/receiptsRoot'
218+
logsBloom:
219+
$ref: '#/components/schemas/ExecutionPayloadV2/properties/logsBloom'
220+
prevRandao:
221+
$ref: '#/components/schemas/ExecutionPayloadV2/properties/prevRandao'
222+
blockNumber:
223+
$ref: '#/components/schemas/ExecutionPayloadV2/properties/blockNumber'
224+
gasLimit:
225+
$ref: '#/components/schemas/ExecutionPayloadV2/properties/gasLimit'
226+
gasUsed:
227+
$ref: '#/components/schemas/ExecutionPayloadV2/properties/gasUsed'
228+
timestamp:
229+
$ref: '#/components/schemas/ExecutionPayloadV2/properties/timestamp'
230+
extraData:
231+
$ref: '#/components/schemas/ExecutionPayloadV2/properties/extraData'
232+
baseFeePerGas:
233+
$ref: '#/components/schemas/ExecutionPayloadV2/properties/baseFeePerGas'
234+
blockHash:
235+
$ref: '#/components/schemas/ExecutionPayloadV2/properties/blockHash'
236+
transactions:
237+
$ref: '#/components/schemas/ExecutionPayloadV2/properties/transactions'
238+
withdrawals:
239+
$ref: '#/components/schemas/ExecutionPayloadV2/properties/withdrawals'
240+
dataGasUsed:
241+
title: Data gas used
242+
$ref: '#/components/schemas/uint64'
243+
excessDataGas:
244+
title: Excess data gas
245+
$ref: '#/components/schemas/uint64'
188246
ExecutionPayloadBodyV1:
189247
title: Execution payload body object V1
190248
type: object
@@ -200,3 +258,26 @@ ExecutionPayloadBodyV1:
200258
- 'null'
201259
items:
202260
$ref: '#/components/schemas/WithdrawalV1'
261+
BlobsBundleV1:
262+
title: Blobs bundle object V1
263+
type: object
264+
required:
265+
- commitments
266+
- proofs
267+
- blobs
268+
properties:
269+
commitments:
270+
title: Commitments
271+
type: array
272+
items:
273+
$ref: '#/components/schemas/bytes48'
274+
proofs:
275+
title: Proofs
276+
type: array
277+
items:
278+
$ref: '#/components/schemas/bytes48'
279+
blobs:
280+
title: Blobs
281+
type: array
282+
items:
283+
$ref: '#/components/schemas/bytes'

0 commit comments

Comments
 (0)