From c26866665cf33df243ad6402fc1c10a018df689f Mon Sep 17 00:00:00 2001 From: Jim McDonald Date: Tue, 10 Dec 2024 10:29:03 +0000 Subject: [PATCH 1/3] Add engine_forkchoiceUpdatedV4 --- src/engine/openrpc/methods/forkchoice.yaml | 59 ++++++++++++++++++++++ src/engine/openrpc/schemas/forkchoice.yaml | 24 +++++++++ src/engine/prague.md | 26 ++++++++++ 3 files changed, 109 insertions(+) diff --git a/src/engine/openrpc/methods/forkchoice.yaml b/src/engine/openrpc/methods/forkchoice.yaml index 66479d12a..a472245d6 100644 --- a/src/engine/openrpc/methods/forkchoice.yaml +++ b/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' + gasLimit: '0x1c9c380' + result: + name: Response object + value: + payloadStatus: + status: VALID + latestValidHash: '0x3559e851470f6e7bbed1db474980683e8c315bfce99b2a6ef47c057c04de7858' + validationError: null + payloadId: '0x0000000021f32cc1' diff --git a/src/engine/openrpc/schemas/forkchoice.yaml b/src/engine/openrpc/schemas/forkchoice.yaml index c398de23f..46f17d87c 100644 --- a/src/engine/openrpc/schemas/forkchoice.yaml +++ b/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 + - gasLimit + 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' + gasLimit: + $ref: '#/components/schemas/uint64' diff --git a/src/engine/prague.md b/src/engine/prague.md index fb63407eb..089f41403 100644 --- a/src/engine/prague.md +++ b/src/engine/prague.md @@ -10,6 +10,10 @@ This specification is based on and extends [Engine API - Cancun](./cancun.md) sp - [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 `gasLimit`. + +#### 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 gas limit supplied in `payloadAttributes.gasLimit` when constructing a payload. + ### engine_newPayloadV4 Method parameter list is extended with `executionRequests`. From 58b820c353cd236117664643bf5c10c1322c37f0 Mon Sep 17 00:00:00 2001 From: Jim McDonald Date: Tue, 10 Dec 2024 12:10:09 +0000 Subject: [PATCH 2/3] Update src/engine/openrpc/methods/forkchoice.yaml Co-authored-by: g11tech --- src/engine/openrpc/methods/forkchoice.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/engine/openrpc/methods/forkchoice.yaml b/src/engine/openrpc/methods/forkchoice.yaml index a472245d6..91170328b 100644 --- a/src/engine/openrpc/methods/forkchoice.yaml +++ b/src/engine/openrpc/methods/forkchoice.yaml @@ -203,7 +203,7 @@ address: '0x00000000000000000000000000000000000010f1' amount: '0x1' parentBeaconBlockRoot: '0x11f780a954bcba8889998e4e61deaae6388dd2391e9c810bd9c94962cc1eadc1' - gasLimit: '0x1c9c380' + targetGasLimit: '0x1c9c380' result: name: Response object value: From 48d1b766bb7f4d36f8ea8d381bc5a597873abf91 Mon Sep 17 00:00:00 2001 From: Jim McDonald Date: Tue, 10 Dec 2024 12:12:10 +0000 Subject: [PATCH 3/3] gasLimit -> targetGasLimit --- src/engine/openrpc/schemas/forkchoice.yaml | 4 ++-- src/engine/prague.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/src/engine/openrpc/schemas/forkchoice.yaml b/src/engine/openrpc/schemas/forkchoice.yaml index 46f17d87c..dcfea6154 100644 --- a/src/engine/openrpc/schemas/forkchoice.yaml +++ b/src/engine/openrpc/schemas/forkchoice.yaml @@ -94,7 +94,7 @@ PayloadAttributesV4: - suggestedFeeRecipient - withdrawals - parentBeaconBlockRoot - - gasLimit + - targetGasLimit properties: timestamp: $ref: '#/components/schemas/PayloadAttributesV2/properties/timestamp' @@ -107,5 +107,5 @@ PayloadAttributesV4: parentBeaconBlockRoot: title: Parent beacon block root $ref: '#/components/schemas/hash32' - gasLimit: + targetGasLimit: $ref: '#/components/schemas/uint64' diff --git a/src/engine/prague.md b/src/engine/prague.md index 089f41403..c2e9b70a2 100644 --- a/src/engine/prague.md +++ b/src/engine/prague.md @@ -30,7 +30,7 @@ This specification is based on and extends [Engine API - Cancun](./cancun.md) sp ### engine_forkchoiceUpdatedV4 -Method parameter list is extended with `gasLimit`. +Method parameter list is extended with `targetGasLimit`. #### Request @@ -48,7 +48,7 @@ Refer to the response for [`engine_forkchoiceUpdatedV2`](./shanghai.md#engine_fo 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 gas limit supplied in `payloadAttributes.gasLimit` when constructing a payload. +1. Client software **MUST** use the target gas limit supplied in `payloadAttributes.targetGasLimit` when constructing a payload. ### engine_newPayloadV4