Skip to content

Commit 4ec8e57

Browse files
nerolationnerolation
authored
Add Amsterdam execution-api specs (#691)
* Add EIP-7928 api specs * Clarify EIP-7928 api specs * add amsterdam hardfork * fix responce for missing field * Add examples to payload yaml
1 parent 95d042a commit 4ec8e57

File tree

5 files changed

+493
-1
lines changed

5 files changed

+493
-1
lines changed

‎src/engine/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
The Engine JSON-RPC API is a collection of methods that all execution clients implement.
44
This interface allows the communication between consensus and execution layers of the two-component post-Merge Ethereum Client.
55

6-
This API is in *active development* and currently specified in markdown documents specified by fork scopes ([Paris](./paris.md), [Shanghai](./shanghai.md), [Cancun](./cancun.md), [Prague](./prague.md)).
6+
This API is in *active development* and currently specified in markdown documents specified by fork scopes ([Paris](./paris.md), [Shanghai](./shanghai.md), [Cancun](./cancun.md), [Prague](./prague.md), [Osaka](./osaka.md), [Amsterdam](./amsterdam.md)).
77

88
## References
99
* [Engine API: A Visual Guide](https://hackmd.io/@danielrachi/engine_api)

‎src/engine/amsterdam.md‎

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
# Engine API -- Amsterdam
2+
3+
Engine API changes introduced in Amsterdam.
4+
5+
This specification is based on and extends [Engine API - Osaka](./osaka.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+
- [ExecutionPayloadV4](#executionpayloadv4)
14+
- [Methods](#methods)
15+
- [engine_newPayloadV5](#engine_newpayloadv5)
16+
- [Request](#request)
17+
- [Response](#response)
18+
- [Specification](#specification)
19+
- [engine_getPayloadV6](#engine_getpayloadv6)
20+
- [Request](#request-1)
21+
- [Response](#response-1)
22+
- [Specification](#specification-1)
23+
- [Update the methods of previous forks](#update-the-methods-of-previous-forks)
24+
- [Osaka API](#osaka-api)
25+
26+
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
27+
28+
## Structures
29+
30+
### ExecutionPayloadV4
31+
32+
This structure has the syntax of [`ExecutionPayloadV3`](./cancun.md#executionpayloadv3) and appends the new field: `blockAccessList`.
33+
34+
- `parentHash`: `DATA`, 32 Bytes
35+
- `feeRecipient`: `DATA`, 20 Bytes
36+
- `stateRoot`: `DATA`, 32 Bytes
37+
- `receiptsRoot`: `DATA`, 32 Bytes
38+
- `logsBloom`: `DATA`, 256 Bytes
39+
- `prevRandao`: `DATA`, 32 Bytes
40+
- `blockNumber`: `QUANTITY`, 64 Bits
41+
- `gasLimit`: `QUANTITY`, 64 Bits
42+
- `gasUsed`: `QUANTITY`, 64 Bits
43+
- `timestamp`: `QUANTITY`, 64 Bits
44+
- `extraData`: `DATA`, 0 to 32 Bytes
45+
- `baseFeePerGas`: `QUANTITY`, 256 Bits
46+
- `blockHash`: `DATA`, 32 Bytes
47+
- `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)
48+
- `withdrawals`: `Array of WithdrawalV1` - Array of withdrawals, each object is an `OBJECT` containing the fields of a `WithdrawalV1` structure.
49+
- `blobGasUsed`: `QUANTITY`, 64 Bits
50+
- `excessBlobGas`: `QUANTITY`, 64 Bits
51+
- `blockAccessList`: `DATA` - RLP-encoded block access list as defined in [EIP-7928](https://eips.ethereum.org/EIPS/eip-7928)
52+
53+
## Methods
54+
55+
### engine_newPayloadV5
56+
57+
This method is updated to support the new `ExecutionPayloadV4` structure.
58+
59+
#### Request
60+
61+
* method: `engine_newPayloadV5`
62+
* params:
63+
1. `executionPayload`: [`ExecutionPayloadV4`](#executionpayloadv4).
64+
2. `expectedBlobVersionedHashes`: `Array of DATA`, 32 Bytes - Array of expected blob versioned hashes to validate.
65+
3. `parentBeaconBlockRoot`: `DATA`, 32 Bytes - Root of the parent beacon block.
66+
4. `executionRequests`: `Array of DATA` - List of execution layer triggered requests.
67+
68+
#### Response
69+
70+
Refer to the response for [`engine_newPayloadV4`](./prague.md#engine_newpayloadv4).
71+
72+
#### Specification
73+
74+
This method follows the same specification as [`engine_newPayloadV4`](./prague.md#engine_newpayloadv4) with the following changes:
75+
76+
1. Client software **MUST** return `-38005: Unsupported fork` error if the `timestamp` of the payload does not fall within the time frame of the Amsterdam activation.
77+
78+
2. Client software **MUST** return `-32602: Invalid params` error if the `blockAccessList` field is missing.
79+
80+
3. Client software **MUST** validate the `blockAccessList` field by executing the payload's transactions and verifying that the computed access list matches the provided one.
81+
82+
4. If the `blockAccessList` field is malformed or doesn't match the computed access list, the call **MUST** return `{status: INVALID, latestValidHash: null, validationError: errorMessage | null}`.
83+
84+
### engine_getPayloadV6
85+
86+
This method is updated to return the new `ExecutionPayloadV4` structure.
87+
88+
#### Request
89+
90+
* method: `engine_getPayloadV6`
91+
* params:
92+
1. `payloadId`: `DATA`, 8 Bytes - Identifier of the payload build process
93+
* timeout: 1s
94+
95+
#### Response
96+
97+
* result: `object`
98+
- `executionPayload`: [`ExecutionPayloadV4`](#executionpayloadv4)
99+
- `blockValue` : `QUANTITY`, 256 Bits - The expected value to be received by the `feeRecipient` in wei
100+
- `blobsBundle`: [`BlobsBundleV2`](./osaka.md#blobsbundlev2) - Bundle with data corresponding to blob transactions included into `executionPayload`
101+
- `shouldOverrideBuilder` : `BOOLEAN` - Suggestion from the execution layer to use this `executionPayload` instead of an externally provided one
102+
- `executionRequests`: `Array of DATA` - Execution layer triggered requests obtained from the `executionPayload` transaction execution.
103+
* error: code and message set in case an exception happens while getting the payload.
104+
105+
#### Specification
106+
107+
This method follows the same specification as [`engine_getPayloadV5`](./osaka.md#engine_getpayloadv5) with the following changes:
108+
109+
1. Client software **MUST** return `-38005: Unsupported fork` error if the `timestamp` of the built payload does not fall within the time frame of the Amsterdam activation.
110+
111+
2. When building the block, client software **MUST** collect all account accesses and state changes during transaction execution and populate the `blockAccessList` field in the returned `ExecutionPayloadV4` with the RLP-encoded access list.
112+
113+
### Update the methods of previous forks
114+
115+
#### Osaka API
116+
117+
For the following methods:
118+
119+
- [`engine_newPayloadV4`](./prague.md#engine_newpayloadv4)
120+
- [`engine_getPayloadV5`](./osaka.md#engine_getpayloadv5)
121+
122+
a validation **MUST** be added:
123+
124+
1. Client software **MUST** return `-38005: Unsupported fork` error if the `timestamp` of payload greater or equal to the Amsterdam activation timestamp.
125+
126+
For the [`engine_forkchoiceUpdatedV3`](./cancun.md#engine_forkchoiceupdatedv3) the following modification **MUST** be made:
127+
1. Return `-38005: Unsupported fork` if `payloadAttributes.timestamp` doesn't fall within the time frame of the Cancun, Prague, Osaka *or Amsterdam* forks.

‎src/engine/eip7928.md‎

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
# Engine API -- EIP-7928
2+
3+
Engine API changes introduced in EIP-7928.
4+
5+
This specification is based on and extends [Engine API - Osaka](./osaka.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+
- [ExecutionPayloadV4](#executionpayloadv4)
14+
- [Methods](#methods)
15+
- [engine_newPayloadV5](#engine_newpayloadv5)
16+
- [Request](#request)
17+
- [Response](#response)
18+
- [Specification](#specification)
19+
- [engine_getPayloadV6](#engine_getpayloadv6)
20+
- [Request](#request-1)
21+
- [Response](#response-1)
22+
- [Specification](#specification-1)
23+
- [Update the methods of previous forks](#update-the-methods-of-previous-forks)
24+
- [Osaka API](#osaka-api)
25+
26+
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
27+
28+
## Structures
29+
30+
### ExecutionPayloadV4
31+
32+
This structure has the syntax of [`ExecutionPayloadV3`](./cancun.md#executionpayloadv3) and appends the new field: `blockAccessList`.
33+
34+
- `parentHash`: `DATA`, 32 Bytes
35+
- `feeRecipient`: `DATA`, 20 Bytes
36+
- `stateRoot`: `DATA`, 32 Bytes
37+
- `receiptsRoot`: `DATA`, 32 Bytes
38+
- `logsBloom`: `DATA`, 256 Bytes
39+
- `prevRandao`: `DATA`, 32 Bytes
40+
- `blockNumber`: `QUANTITY`, 64 Bits
41+
- `gasLimit`: `QUANTITY`, 64 Bits
42+
- `gasUsed`: `QUANTITY`, 64 Bits
43+
- `timestamp`: `QUANTITY`, 64 Bits
44+
- `extraData`: `DATA`, 0 to 32 Bytes
45+
- `baseFeePerGas`: `QUANTITY`, 256 Bits
46+
- `blockHash`: `DATA`, 32 Bytes
47+
- `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)
48+
- `withdrawals`: `Array of WithdrawalV1` - Array of withdrawals, each object is an `OBJECT` containing the fields of a `WithdrawalV1` structure.
49+
- `blobGasUsed`: `QUANTITY`, 64 Bits
50+
- `excessBlobGas`: `QUANTITY`, 64 Bits
51+
- `blockAccessList`: `DATA` - RLP-encoded block access list as defined in [EIP-7928](https://eips.ethereum.org/EIPS/eip-7928)
52+
53+
## Methods
54+
55+
### engine_newPayloadV5
56+
57+
This method is updated to support the new `ExecutionPayloadV4` structure.
58+
59+
#### Request
60+
61+
* method: `engine_newPayloadV5`
62+
* params:
63+
1. `executionPayload`: [`ExecutionPayloadV4`](#executionpayloadv4).
64+
2. `expectedBlobVersionedHashes`: `Array of DATA`, 32 Bytes - Array of expected blob versioned hashes to validate.
65+
3. `parentBeaconBlockRoot`: `DATA`, 32 Bytes - Root of the parent beacon block.
66+
4. `executionRequests`: `Array of DATA` - List of execution layer triggered requests.
67+
68+
#### Response
69+
70+
Refer to the response for [`engine_newPayloadV4`](./prague.md#engine_newpayloadv4).
71+
72+
#### Specification
73+
74+
This method follows the same specification as [`engine_newPayloadV4`](./prague.md#engine_newpayloadv4) with the following changes:
75+
76+
1. Client software **MUST** return `-38005: Unsupported fork` error if the `timestamp` of the payload does not fall within the time frame of the EIP-7928 activation.
77+
78+
2. Client software **MUST** validate the `blockAccessList` field by executing the payload's transactions and verifying that the computed access list matches the provided one.
79+
80+
3. If the `blockAccessList` field is missing, malformed, or doesn't match the computed access list, the call **MUST** return `{status: INVALID, latestValidHash: null, validationError: errorMessage | null}`.
81+
82+
### engine_getPayloadV6
83+
84+
This method is updated to return the new `ExecutionPayloadV4` structure.
85+
86+
#### Request
87+
88+
* method: `engine_getPayloadV6`
89+
* params:
90+
1. `payloadId`: `DATA`, 8 Bytes - Identifier of the payload build process
91+
* timeout: 1s
92+
93+
#### Response
94+
95+
* result: `object`
96+
- `executionPayload`: [`ExecutionPayloadV4`](#executionpayloadv4)
97+
- `blockValue` : `QUANTITY`, 256 Bits - The expected value to be received by the `feeRecipient` in wei
98+
- `blobsBundle`: [`BlobsBundleV2`](./osaka.md#blobsbundlev2) - Bundle with data corresponding to blob transactions included into `executionPayload`
99+
- `shouldOverrideBuilder` : `BOOLEAN` - Suggestion from the execution layer to use this `executionPayload` instead of an externally provided one
100+
- `executionRequests`: `Array of DATA` - Execution layer triggered requests obtained from the `executionPayload` transaction execution.
101+
* error: code and message set in case an exception happens while getting the payload.
102+
103+
#### Specification
104+
105+
This method follows the same specification as [`engine_getPayloadV5`](./osaka.md#engine_getpayloadv5) with the following changes:
106+
107+
1. Client software **MUST** return `-38005: Unsupported fork` error if the `timestamp` of the built payload does not fall within the time frame of the EIP-7928 activation.
108+
109+
2. When building the block, client software **MUST** collect all account accesses and state changes during transaction execution and populate the `blockAccessList` field in the returned `ExecutionPayloadV4` with the RLP-encoded access list.
110+
111+
### Update the methods of previous forks
112+
113+
#### Osaka API
114+
115+
For the following methods:
116+
117+
- [`engine_newPayloadV4`](./prague.md#engine_newpayloadv4)
118+
- [`engine_getPayloadV5`](./osaka.md#engine_getpayloadv5)
119+
120+
a validation **MUST** be added:
121+
122+
1. Client software **MUST** return `-38005: Unsupported fork` error if the `timestamp` of payload greater or equal to the EIP-7928 activation timestamp.
123+
124+
For the [`engine_forkchoiceUpdatedV3`](./cancun.md#engine_forkchoiceupdatedv3) the following modification **MUST** be made:
125+
1. Return `-38005: Unsupported fork` if `payloadAttributes.timestamp` doesn't fall within the time frame of the Cancun, Prague, Osaka *or EIP-7928* forks.

0 commit comments

Comments
 (0)