diff --git a/src/engine/openrpc/methods/forkchoice.yaml b/src/engine/openrpc/methods/forkchoice.yaml index 66479d12a..91170328b 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' + targetGasLimit: '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..dcfea6154 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 + - 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' diff --git a/src/engine/prague.md b/src/engine/prague.md index fb63407eb..c2e9b70a2 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 `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`.