From f871314e0639575c4c6898e5903e8285a2afa41e Mon Sep 17 00:00:00 2001
From: Nico Flaig <nflaig@protonmail.com>
Date: Mon, 11 May 2026 17:18:13 +0200
Subject: [PATCH 1/2] engine: add targetGasLimit to PayloadAttributesV4

---
 src/engine/amsterdam.md                    | 8 ++++++--
 src/engine/openrpc/schemas/forkchoice.yaml | 4 ++++
 2 files changed, 10 insertions(+), 2 deletions(-)

diff --git a/src/engine/amsterdam.md b/src/engine/amsterdam.md
index ab13b6c51..d2c52e80b 100644
--- a/src/engine/amsterdam.md
+++ b/src/engine/amsterdam.md
@@ -84,7 +84,7 @@ This structure has the syntax of [`ExecutionPayloadBodyV1`](./shanghai.md#execut
 
 ### PayloadAttributesV4
 
-This structure has the syntax of [`PayloadAttributesV3`](./cancun.md#payloadattributesv3) and appends a single field: `slotNumber`.
+This structure has the syntax of [`PayloadAttributesV3`](./cancun.md#payloadattributesv3) and appends two new fields: `slotNumber` and `targetGasLimit`.
 
 - `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
@@ -92,6 +92,7 @@ This structure has the syntax of [`PayloadAttributesV3`](./cancun.md#payloadattr
 - `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.
 - `slotNumber`: `QUANTITY`, 64 Bits - value for the `slotNumber` field of the new payload
+- `targetGasLimit`: `QUANTITY`, 64 Bits - target value for the `gasLimit` field of the new payload
 
 
 ### BlobCellsAndProofsV1
@@ -236,6 +237,8 @@ This method follows the same specification as [`engine_forkchoiceUpdatedV3`](./c
 
     4. If any of the above checks fails, the `forkchoiceState` update **MUST NOT** be rolled back.
 
+2. Client software **MUST** use the target gas limit supplied in `payloadAttributes.targetGasLimit` when constructing a payload.
+
 3. If `custodyColumns` is provided (non-null), the following rules apply:
 
     1. `custodyColumns` **MUST** be a 16-byte `DATA` value. If it is not, the client software **MUST** return `-32602: Invalid params`.
@@ -280,7 +283,7 @@ Consensus layer clients **MAY** use this method to fetch blob cells from the exe
 
 ### PayloadAttributesV4
 
-This structure has the syntax of [`PayloadAttributesV3`](./cancun.md#payloadattributesv3) and appends a single field: `slotNumber`.
+This structure has the syntax of [`PayloadAttributesV3`](./cancun.md#payloadattributesv3) and appends two new fields: `slotNumber` and `targetGasLimit`.
 
 - `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
@@ -288,6 +291,7 @@ This structure has the syntax of [`PayloadAttributesV3`](./cancun.md#payloadattr
 - `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.
 - `slotNumber`: `QUANTITY`, 64 Bits - value for the `slotNumber` field of the new payload
+- `targetGasLimit`: `QUANTITY`, 64 Bits - target value for the `gasLimit` field of the new payload
 
 ### Update the methods of previous forks
 
diff --git a/src/engine/openrpc/schemas/forkchoice.yaml b/src/engine/openrpc/schemas/forkchoice.yaml
index b5f6da4cc..ca7ae796f 100644
--- a/src/engine/openrpc/schemas/forkchoice.yaml
+++ b/src/engine/openrpc/schemas/forkchoice.yaml
@@ -95,6 +95,7 @@ PayloadAttributesV4:
     - withdrawals
     - parentBeaconBlockRoot
     - slotNumber
+    - targetGasLimit
   properties:
     timestamp:
       $ref: '#/components/schemas/PayloadAttributesV3/properties/timestamp'
@@ -108,4 +109,7 @@ PayloadAttributesV4:
       $ref: '#/components/schemas/PayloadAttributesV3/properties/parentBeaconBlockRoot'
     slotNumber:
       title: Slot number
+      $ref: '#/components/schemas/uint64'
+    targetGasLimit:
+      title: Target gas limit
       $ref: '#/components/schemas/uint64'
\ No newline at end of file

From dbae1bb2497d764ee0bbbe262c59652985558ccd Mon Sep 17 00:00:00 2001
From: Nico Flaig <nflaig@protonmail.com>
Date: Mon, 11 May 2026 17:55:03 +0200
Subject: [PATCH 2/2] add new line

---
 src/engine/openrpc/schemas/forkchoice.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/engine/openrpc/schemas/forkchoice.yaml b/src/engine/openrpc/schemas/forkchoice.yaml
index ca7ae796f..af9f7d067 100644
--- a/src/engine/openrpc/schemas/forkchoice.yaml
+++ b/src/engine/openrpc/schemas/forkchoice.yaml
@@ -112,4 +112,4 @@ PayloadAttributesV4:
       $ref: '#/components/schemas/uint64'
     targetGasLimit:
       title: Target gas limit
-      $ref: '#/components/schemas/uint64'
\ No newline at end of file
+      $ref: '#/components/schemas/uint64'