Add engine_forkchoiceUpdatedV4

src/engine/openrpc/methods/forkchoice.yaml

@@ -153,3 +153,62 @@
             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/cancun.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'
+            targetGasLimit: '0x1c9c380'
+      result:
+        name: Response object
+        value:
+          payloadStatus:
+            status: VALID
+            latestValidHash: '0x3559e851470f6e7bbed1db474980683e8c315bfce99b2a6ef47c057c04de7858'
+            validationError: null
+          payloadId: '0x0000000021f32cc1'

src/engine/openrpc/schemas/forkchoice.yaml

@@ -85,3 +85,27 @@ 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
+    - targetGasLimit
+  properties:
+    timestamp:
+      $ref: '#/components/schemas/PayloadAttributesV2/properties/timestamp'
+    prevRandao:
+      $ref: '#/components/schemas/PayloadAttributesV2/properties/prevRandao'
+    suggestedFeeRecipient:
+      $ref: '#/components/schemas/PayloadAttributesV2/properties/suggestedFeeRecipient'
+    withdrawals:
+      $ref: '#/components/schemas/PayloadAttributesV2/properties/withdrawals'
+    parentBeaconBlockRoot:
+      title: Parent beacon block root
+      $ref: '#/components/schemas/hash32'
+    targetGasLimit:
+      $ref: '#/components/schemas/uint64'

src/engine/prague.md

@@ -10,6 +10,10 @@ This specification is based on and extends [Engine API - Cancun](./cancun.md) sp
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 
 - [Methods](#methods)
+  - [engine_forkchoiceUpdatedV4](#engine_forkchoiceupdatedv4)
+    - [Request](#request)
+    - [Response](#response)
+    - [Specification](#specification)
   - [engine_newPayloadV4](#engine_newpayloadv4)
     - [Request](#request)
     - [Response](#response)
@@ -24,6 +28,28 @@ This specification is based on and extends [Engine API - Cancun](./cancun.md) sp
 
 ## Methods
 
+### engine_forkchoiceUpdatedV4
+
+Method parameter list is extended with `targetGasLimit`.
+
+#### 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_forkchoiceUpdatedV2`](./shanghai.md#engine_forkchoiceupdatedv2).
+
+#### Specification
+
+This method follows the same specification as [`engine_forkchoiceUpdatedV3`](./cancun.md#engine_forkchoiceupdatedv3) with the following changes to the processing flow:
+
+1. Client software **MUST** use the target gas limit supplied in `payloadAttributes.targetGasLimit` when constructing a payload.
+
 ### engine_newPayloadV4
 
 Method parameter list is extended with `executionRequests`.