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

changes required for EIP-7742 #574

Closed
wants to merge 8 commits into from
Closed

changes required for EIP-7742 #574

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
7e57676
changes required for EIP-7742
ralexstokes Aug 21, 2024
ec49a5f
provide `maximumBlobCount` for payload construction
ralexstokes Aug 22, 2024
3e8f327
Apply suggestions from @ppopth
mkalinin Dec 3, 2024
558cd9a
Merge branch 'main' into eip-7742-blob-uncoupling
mkalinin Dec 3, 2024
f9bb55b
Add fork time constraint to fcUV4
mkalinin Dec 3, 2024
3d695a3
Change definition order
mkalinin Dec 3, 2024
6840596
Add schema for fcUV4
mkalinin Dec 3, 2024
d0d88cd
add updates to execution payload for extended header under EIP-7742
ralexstokes Dec 9, 2024
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
60 changes: 60 additions & 0 deletions src/engine/openrpc/methods/forkchoice.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -153,3 +153,63 @@
latestValidHash: '0x3559e851470f6e7bbed1db474980683e8c315bfce99b2a6ef47c057c04de7858'
validationError: null
payloadId: '0x0000000021f32cc1'
- name: engine_forkchoiceUpdatedV4
summary: Updates the forkchoice state
externalDocs:
description: Method specification
url: https://github.com/ethereum/execution-apis/blob/main/src/engine/prague.md#engine_forkchoiceupdatedv4
params:
- name: Forkchoice state
required: true
schema:
$ref: '#/components/schemas/ForkchoiceStateV1'
- name: Payload attributes
required: false
schema:
$ref: '#/components/schemas/PayloadAttributesV4'
result:
name: Response object
schema:
$ref: '#/components/schemas/ForkchoiceUpdatedResponseV1'
errors:
- code: -38002
message: Invalid forkchoice state
- code: -38003
message: Invalid payload attributes
- code: -32602
message: Invalid params
- code: -38005
message: Unsupported fork
examples:
- name: engine_forkchoiceUpdatedV4 example
params:
- name: Forkchoice state
value:
headBlockHash: '0x3559e851470f6e7bbed1db474980683e8c315bfce99b2a6ef47c057c04de7858'
safeBlockHash: '0x3559e851470f6e7bbed1db474980683e8c315bfce99b2a6ef47c057c04de7858'
finalizedBlockHash: '0x3b8fb240d288781d4aac94d3fd16809ee413bc99294a085798a589dae51ddd4a'
- name: Payload attributes
value:
timestamp: '0x64e7785b'
prevRandao: '0xc130d5e63c61c935f6089e61140ca9136172677cf6aa5800dcc1cf0a02152a14'
suggestedFeeRecipient: '0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b'
withdrawals:
- index: '0xf0'
validatorIndex: '0xf0'
address: '0x00000000000000000000000000000000000010f0'
amount: '0x1'
- index: '0xf1'
validatorIndex: '0xf1'
address: '0x00000000000000000000000000000000000010f1'
amount: '0x1'
parentBeaconBlockRoot: '0x11f780a954bcba8889998e4e61deaae6388dd2391e9c810bd9c94962cc1eadc1'
targetBlobsPerBlock: '0x3'
maxBlobsPerBlock: '0x6'
result:
name: Response object
value:
payloadStatus:
status: VALID
latestValidHash: '0x3559e851470f6e7bbed1db474980683e8c315bfce99b2a6ef47c057c04de7858'
validationError: null
payloadId: '0x0000000021f32cc1'
26 changes: 26 additions & 0 deletions src/engine/openrpc/schemas/forkchoice.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -85,3 +85,29 @@ PayloadAttributesV3:
parentBeaconBlockRoot:
title: Parent beacon block root
$ref: '#/components/schemas/hash32'
PayloadAttributesV4:
title: Payload attributes object V4
type: object
required:
- timestamp
- prevRandao
- suggestedFeeRecipient
- withdrawals
- parentBeaconBlockRoot
- targetBlobsPerBlock
- maxBlobsPerBlock
properties:
timestamp:
$ref: '#/components/schemas/PayloadAttributesV3/properties/timestamp'
prevRandao:
$ref: '#/components/schemas/PayloadAttributesV3/properties/prevRandao'
suggestedFeeRecipient:
$ref: '#/components/schemas/PayloadAttributesV3/properties/suggestedFeeRecipient'
withdrawals:
$ref: '#/components/schemas/PayloadAttributesV3/properties/withdrawals'
parentBeaconBlockRoot:
$ref: '#/components/schemas/PayloadAttributesV3/properties/parentBeaconBlockRoot'
targetBlobsPerBlock:
$ref: '#/components/schemas/uint64'
maxBlobsPerBlock:
$ref: '#/components/schemas/uint64'
71 changes: 68 additions & 3 deletions src/engine/prague.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,19 +9,63 @@ This specification is based on and extends [Engine API - Cancun](./cancun.md) sp
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->

- [Structures](#structures)
Copy link
Member

Choose a reason for hiding this comment

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

gotta add execution payload v4 here I think

Copy link
Member Author

Choose a reason for hiding this comment

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

ty, fixed

- [ExecutionPayloadV4](#executionpayloadv4)
- [PayloadAttributesV4](#payloadattributesv4)
- [Methods](#methods)
- [engine_newPayloadV4](#engine_newpayloadv4)
- [Request](#request)
- [Response](#response)
- [Specification](#specification)
- [engine_getPayloadV4](#engine_getpayloadv4)
- [engine_forkchoiceUpdatedV4](#engine_forkchoiceupdatedv4)
- [Request](#request-1)
- [Response](#response-1)
- [Specification](#specification-1)
- [engine_getPayloadV4](#engine_getpayloadv4)
- [Request](#request-2)
- [Response](#response-2)
- [Specification](#specification-2)
- [Update the methods of previous forks](#update-the-methods-of-previous-forks)

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

## Structures

### ExecutionPayloadV4
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 we need a new ExecutionPayload definition, since we have targetBlobsPerBlock passed as a param to newPayloadV4

Copy link
Member Author

Choose a reason for hiding this comment

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

that's the value coming from the CL, the EL needs a way to capture what is on-chain

the EL's job here is to verify the value in the EL header matches what the CL is sending

Copy link
Contributor

Choose a reason for hiding this comment

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

right, but the treatment of this value looks similar to parentBeaconBlockRoot, i don’t get why the targetBlobsPerBlock should be a part of the payload

Copy link
Member Author

Choose a reason for hiding this comment

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

if we don't do it this way, we would need to have the CL validate this field in the ExecutionPayload

and I just took a look at how we handle the parent beacon block root, and kind of agree we should do this check there and can skip passing it via the ExecutionPayloadV4 here

let's see if we decide to ship EIP-7742 in pectra and we can make these updates in that case


This structure has the syntax of [`ExecutionPayloadV3`](./cancun.md#executionpayloadv3) and appends the new field(s): `targetBlobsPerBlock`.

- `parentHash`: `DATA`, 32 Bytes
- `feeRecipient`: `DATA`, 20 Bytes
- `stateRoot`: `DATA`, 32 Bytes
- `receiptsRoot`: `DATA`, 32 Bytes
- `logsBloom`: `DATA`, 256 Bytes
- `prevRandao`: `DATA`, 32 Bytes
- `blockNumber`: `QUANTITY`, 64 Bits
- `gasLimit`: `QUANTITY`, 64 Bits
- `gasUsed`: `QUANTITY`, 64 Bits
- `timestamp`: `QUANTITY`, 64 Bits
- `extraData`: `DATA`, 0 to 32 Bytes
- `baseFeePerGas`: `QUANTITY`, 256 Bits
- `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)
- `withdrawals`: `Array of WithdrawalV1` - Array of withdrawals, each object is an `OBJECT` containing the fields of a `WithdrawalV1` structure.
- `blobGasUsed`: `QUANTITY`, 64 Bits
- `excessBlobGas`: `QUANTITY`, 64 Bits
- `targetBlobsPerBlock`: `QUANTITY`, 64 Bits

### PayloadAttributesV4

This structure has the syntax of [`PayloadAttributesV3`](./cancun.md#payloadattributesv3) and appends the fields: `targetBlobsPerBlock`, `maxBlobsPerBlock`.

- `timestamp`: `QUANTITY`, 64 Bits - value for the `timestamp` field of the new payload
- `prevRandao`: `DATA`, 32 Bytes - value for the `prevRandao` field of the new payload
- `suggestedFeeRecipient`: `DATA`, 20 Bytes - suggested value for the `feeRecipient` field of the new payload
- `withdrawals`: `Array of WithdrawalV1` - Array of withdrawals, each object is an `OBJECT` containing the fields of a `WithdrawalV1` structure.
- `parentBeaconBlockRoot`: `DATA`, 32 Bytes - Root of the parent beacon block.
- `targetBlobsPerBlock`: `QUANTITY`, 64 Bits - Average number of blobs to include per payload.
- `maxBlobsPerBlock`: `QUANTITY`, 64 Bits - Maximum number of blobs allowed per payload.

## Methods

### engine_newPayloadV4
Expand All @@ -32,10 +76,11 @@ Method parameter list is extended with `executionRequests`.

* method: `engine_newPayloadV4`
* params:
1. `executionPayload`: [`ExecutionPayloadV3`](./cancun.md#executionpayloadv3).
1. `executionPayload`: [`ExecutionPayloadV4`](#ExecutionPayloadV4).
2. `expectedBlobVersionedHashes`: `Array of DATA`, 32 Bytes - Array of expected blob versioned hashes to validate.
3. `parentBeaconBlockRoot`: `DATA`, 32 Bytes - Root of the parent beacon block.
4. `executionRequests`: `Array of DATA` - List of execution layer triggered requests. Each list element is a `requests` byte array as defined by [EIP-7685](https://eips.ethereum.org/EIPS/eip-7685). The first byte of each element is the `request_type` and the remaining bytes are the `request_data`. Elements of the list **MUST** be ordered by `request_type` in ascending order. Elements with empty `request_data` **MUST** be excluded from the list.
5. `targetBlobsPerBlock`: `QUANTITY`, 64 Bits - Average number of blobs to include per payload.

#### Response

Expand All @@ -52,6 +97,26 @@ and incorporate it into the `blockHash` validation process.
That is, if the computed commitment does not match the corresponding commitment in the execution layer block header,
the call **MUST** return `{status: INVALID, latestValidHash: null, validationError: errorMessage | null}`.

### engine_forkchoiceUpdatedV4

#### Request

* method: `engine_forkchoiceUpdatedV4`
* params:
1. `forkchoiceState`: [`ForkchoiceStateV1`](./paris.md#ForkchoiceStateV1).
2. `payloadAttributes`: `Object|null` - Instance of [`PayloadAttributesV4`](#payloadattributesv4) or `null`.
* timeout: 8s

#### Response

Refer to the response for [`engine_forkchoiceUpdatedV3`](./cancun.md#engine_forkchoiceupdatedv3).

#### Specification

This method follows the same specification as [`engine_forkchoiceUpdatedV3`](./cancun.md#engine_forkchoiceupdatedv3) with the following modifications:
1. `payloadAttributes` **MUST** match the [`PayloadAttributesV4`](#payloadattributesv4) structure.
2. `payloadAttributes.timestamp` **MUST** fall within the time frame of the Prague fork.

### engine_getPayloadV4

The response of this method is extended with the `executionRequests` field.
Expand All @@ -66,7 +131,7 @@ The response of this method is extended with the `executionRequests` field.
#### Response

* result: `object`
- `executionPayload`: [`ExecutionPayloadV3`](./cancun.md#executionpayloadv3)
- `executionPayload`: [`ExecutionPayloadV4`](#ExecutionPayloadv4)
- `blockValue` : `QUANTITY`, 256 Bits - The expected value to be received by the `feeRecipient` in wei
- `blobsBundle`: [`BlobsBundleV1`](#BlobsBundleV1) - Bundle with data corresponding to blob transactions included into `executionPayload`
- `shouldOverrideBuilder` : `BOOLEAN` - Suggestion from the execution layer to use this `executionPayload` instead of an externally provided one
Expand Down
Loading