changes required for EIP-7742

src/engine/openrpc/methods/forkchoice.yaml

@@ -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'

src/engine/openrpc/schemas/forkchoice.yaml

@@ -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'

src/engine/prague.md

@@ -9,19 +9,39 @@ 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)
+  - [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
+
+### 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
@@ -36,6 +56,7 @@ Method parameter list is extended with `executionRequests`.
   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
 
@@ -52,6 +73,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.