Skip to content

Commit f33432b

Browse files
ralexstokeslightclientterencechain
authored
Add withdrawal operations (#195)
* whitespace edits * add support for withdrawals * update wordlist for spellcheck * run doctoc * Apply PR feedback * Apply suggestions from code review * Condense spec with prior response * Update src/engine/specification.md Co-authored-by: lightclient <[email protected]> * update `WithdrawalV1` definition with the validatorIndex * clarify the handling of empty vs `null` withdrawals * Update src/engine/specification.md Co-authored-by: terencechain <[email protected]> Co-authored-by: lightclient <[email protected]> Co-authored-by: terencechain <[email protected]>
1 parent 619c3f7 commit f33432b

File tree

2 files changed

+124
-7
lines changed

2 files changed

+124
-7
lines changed

‎src/engine/specification.md‎

Lines changed: 122 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -16,8 +16,11 @@ This document specifies the Engine API methods that the Consensus Layer uses to
1616
- [Timeouts](#timeouts)
1717
- [Structures](#structures)
1818
- [ExecutionPayloadV1](#executionpayloadv1)
19+
- [WithdrawalV1](#withdrawalv1)
20+
- [ExecutionPayloadV2](#executionpayloadv2)
1921
- [ForkchoiceStateV1](#forkchoicestatev1)
2022
- [PayloadAttributesV1](#payloadattributesv1)
23+
- [PayloadAttributesV2](#payloadattributesv2)
2124
- [PayloadStatusV1](#payloadstatusv1)
2225
- [TransitionConfigurationV1](#transitionconfigurationv1)
2326
- [Routines](#routines)
@@ -29,18 +32,30 @@ This document specifies the Engine API methods that the Consensus Layer uses to
2932
- [Request](#request)
3033
- [Response](#response)
3134
- [Specification](#specification)
32-
- [engine_forkchoiceUpdatedV1](#engine_forkchoiceupdatedv1)
35+
- [engine_newPayloadV2](#engine_newpayloadv2)
3336
- [Request](#request-1)
3437
- [Response](#response-1)
3538
- [Specification](#specification-1)
36-
- [engine_getPayloadV1](#engine_getpayloadv1)
39+
- [engine_forkchoiceUpdatedV1](#engine_forkchoiceupdatedv1)
3740
- [Request](#request-2)
3841
- [Response](#response-2)
3942
- [Specification](#specification-2)
40-
- [engine_exchangeTransitionConfigurationV1](#engine_exchangetransitionconfigurationv1)
43+
- [engine_forkchoiceUpdatedV2](#engine_forkchoiceupdatedv2)
4144
- [Request](#request-3)
4245
- [Response](#response-3)
4346
- [Specification](#specification-3)
47+
- [engine_getPayloadV1](#engine_getpayloadv1)
48+
- [Request](#request-4)
49+
- [Response](#response-4)
50+
- [Specification](#specification-4)
51+
- [engine_getPayloadV2](#engine_getpayloadv2)
52+
- [Request](#request-5)
53+
- [Response](#response-5)
54+
- [Specification](#specification-5)
55+
- [engine_exchangeTransitionConfigurationV1](#engine_exchangetransitionconfigurationv1)
56+
- [Request](#request-6)
57+
- [Response](#response-6)
58+
- [Specification](#specification-6)
4459

4560
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
4661

@@ -112,7 +127,7 @@ The list of error codes introduced by this specification can be found below.
112127
| -32700 | Parse error | Invalid JSON was received by the server. |
113128
| -32600 | Invalid Request | The JSON sent is not a valid Request object. |
114129
| -32601 | Method not found | The method does not exist / is not available. |
115-
| -32602 | Invalid params | Invalid method parameter(s). |
130+
| -32602 | Invalid params | Invalid method parameter(s). |
116131
| -32603 | Internal error | Internal JSON-RPC error. |
117132
| -32000 | Server error | Generic client error while processing request. |
118133
| -38001 | Unknown payload | Payload does not exist / is not available. |
@@ -174,6 +189,38 @@ This structure maps on the [`ExecutionPayload`](https://github.com/ethereum/cons
174189
- `blockHash`: `DATA`, 32 Bytes
175190
- `transactions`: `Array of DATA` - Array of transaction objects, each object is a byte list (`DATA`) representing `TransactionType || TransactionPayload` or `LegacyTransaction` as defined in [EIP-2718](https://eips.ethereum.org/EIPS/eip-2718)
176191

192+
### WithdrawalV1
193+
194+
This structure maps onto the validator withdrawal object from the beacon chain spec.
195+
The fields are encoded as follows:
196+
197+
- `index`: `QUANTITY`, 64 Bits
198+
- `validatorIndex`: `QUANTITY`, 64 Bits
199+
- `address`: `DATA`, 20 Bytes
200+
- `amount`: `QUANTITY`, 256 Bits
201+
202+
*Note*: the `amount` value is represented on the beacon chain as a little-endian value in units of Gwei, whereas the `amount` in this structure *MUST* be converted to a big-endian value in units of Wei.
203+
204+
### ExecutionPayloadV2
205+
206+
This structure has the syntax of `ExecutionPayloadV1` and appends a single field: `withdrawals`.
207+
208+
- `parentHash`: `DATA`, 32 Bytes
209+
- `feeRecipient`: `DATA`, 20 Bytes
210+
- `stateRoot`: `DATA`, 32 Bytes
211+
- `receiptsRoot`: `DATA`, 32 Bytes
212+
- `logsBloom`: `DATA`, 256 Bytes
213+
- `prevRandao`: `DATA`, 32 Bytes
214+
- `blockNumber`: `QUANTITY`, 64 Bits
215+
- `gasLimit`: `QUANTITY`, 64 Bits
216+
- `gasUsed`: `QUANTITY`, 64 Bits
217+
- `timestamp`: `QUANTITY`, 64 Bits
218+
- `extraData`: `DATA`, 0 to 32 Bytes
219+
- `baseFeePerGas`: `QUANTITY`, 256 Bits
220+
- `blockHash`: `DATA`, 32 Bytes
221+
- `transactions`: `Array of DATA` - Array of transaction objects, each object is a byte list (`DATA`) representing `TransactionType || TransactionPayload` or `LegacyTransaction` as defined in [EIP-2718](https://eips.ethereum.org/EIPS/eip-2718)
222+
- `withdrawals`: `Array of WithdrawalV1` - Array of withdrawals, each object is an `OBJECT` containing the fields of a `WithdrawalV1` structure.
223+
177224
### ForkchoiceStateV1
178225

179226
This structure encapsulates the fork choice state. The fields are encoded as follows:
@@ -192,6 +239,15 @@ This structure contains the attributes required to initiate a payload build proc
192239
- `prevRandao`: `DATA`, 32 Bytes - value for the `prevRandao` field of the new payload
193240
- `suggestedFeeRecipient`: `DATA`, 20 Bytes - suggested value for the `feeRecipient` field of the new payload
194241

242+
### PayloadAttributesV2
243+
244+
This structure has the syntax of `PayloadAttributesV1` and appends a single field: `withdrawals`.
245+
246+
- `timestamp`: `QUANTITY`, 64 Bits - value for the `timestamp` field of the new payload
247+
- `prevRandao`: `DATA`, 32 Bytes - value for the `prevRandao` field of the new payload
248+
- `suggestedFeeRecipient`: `DATA`, 20 Bytes - suggested value for the `feeRecipient` field of the new payload
249+
- `withdrawals`: `Array of WithdrawalV1` - Array of withdrawals, each object is an `OBJECT` containing the fields of a `WithdrawalV1` structure.
250+
195251
### PayloadStatusV1
196252

197253
This structure contains the result of processing a payload. The fields are encoded as follows:
@@ -260,7 +316,7 @@ The payload build process is specified as follows:
260316
#### Request
261317

262318
* method: `engine_newPayloadV1`
263-
* params:
319+
* params:
264320
1. [`ExecutionPayloadV1`](#ExecutionPayloadV1)
265321
* timeout: 8s
266322

@@ -292,12 +348,33 @@ The payload build process is specified as follows:
292348

293349
6. If any of the above fails due to errors unrelated to the normal processing flow of the method, client software **MUST** respond with an error object.
294350

351+
### engine_newPayloadV2
352+
353+
#### Request
354+
355+
* method: `engine_newPayloadV2`
356+
* params:
357+
1. [`ExecutionPayloadV2`](#ExecutionPayloadV2)
358+
359+
#### Response
360+
361+
Refer to the response for [`engine_newPayloadV1`](#engine_newpayloadv1).
362+
363+
#### Specification
364+
365+
This method follows the same specification as [`engine_newPayloadV1`](#engine_newpayloadv1) with the exception of the following:
366+
367+
1. If withdrawal functionality is activated, client software **MUST** return an `INVALID` status with the appropriate `latestValidHash` if `payload.withdrawals` is `null`.
368+
Similarly, if the functionality is not activated, client software **MUST** return an `INVALID` status with the appropriate `latestValidHash` if `payloadAttributes.withdrawals` is not `null`.
369+
Blocks without withdrawals **MUST** be expressed with an explicit empty list `[]` value.
370+
Refer to the validity conditions for [`engine_newPayloadV1`](#engine_newpayloadv1) to specification of the appropriate `latestValidHash` value.
371+
295372
### engine_forkchoiceUpdatedV1
296373

297374
#### Request
298375

299376
* method: "engine_forkchoiceUpdatedV1"
300-
* params:
377+
* params:
301378
1. `forkchoiceState`: `Object` - instance of [`ForkchoiceStateV1`](#ForkchoiceStateV1)
302379
2. `payloadAttributes`: `Object|null` - instance of [`PayloadAttributesV1`](#PayloadAttributesV1) or `null`
303380
* timeout: 8s
@@ -343,6 +420,27 @@ The payload build process is specified as follows:
343420

344421
10. If any of the above fails due to errors unrelated to the normal processing flow of the method, client software **MUST** respond with an error object.
345422

423+
### engine_forkchoiceUpdatedV2
424+
425+
#### Request
426+
427+
* method: "engine_forkchoiceUpdatedV2"
428+
* params:
429+
1. `forkchoiceState`: `Object` - instance of [`ForkchoiceStateV1`](#ForkchoiceStateV1)
430+
2. `payloadAttributes`: `Object|null` - instance of [`PayloadAttributesV2`](#PayloadAttributesV2) or `null`
431+
432+
#### Response
433+
434+
Refer to the response for [`engine_forkchoiceUpdatedV1`](#engine_forkchoiceupdatedv1).
435+
436+
#### Specification
437+
438+
This method follows the same specification as [`engine_forkchoiceUpdatedV1`](#engine_forkchoiceupdatedv1) with the exception of the following:
439+
440+
1. If withdrawal functionality is activated, client software **MUST** return error `-38003: Invalid payload attributes` if `payloadAttributes.withdrawals` is `null`.
441+
Similarly, if the functionality is not activated, client software **MUST** return error `-38003: Invalid payload attributes` if `payloadAttributes.withdrawals` is not `null`.
442+
Blocks without withdrawals **MUST** be expressed with an explicit empty list `[]` value.
443+
346444
### engine_getPayloadV1
347445

348446
#### Request
@@ -365,6 +463,23 @@ The payload build process is specified as follows:
365463

366464
3. Client software **MAY** stop the corresponding build process after serving this call.
367465

466+
### engine_getPayloadV2
467+
468+
#### Request
469+
470+
* method: `engine_getPayloadV2`
471+
* params:
472+
1. `payloadId`: `DATA`, 8 Bytes - Identifier of the payload build process
473+
474+
#### Response
475+
476+
* result: [`ExecutionPayloadV2`](#ExecutionPayloadV2)
477+
* error: code and message set in case an exception happens while getting the payload.
478+
479+
#### Specification
480+
481+
Refer to the specification for [`engine_getPayloadV1`](#engine_getpayloadv1).
482+
368483
### engine_exchangeTransitionConfigurationV1
369484

370485
#### Request
@@ -393,6 +508,6 @@ The payload build process is specified as follows:
393508

394509
6. Considering the absence of the `TERMINAL_BLOCK_NUMBER` setting, Consensus Layer client software **MAY** use `0` value for the `terminalBlockNumber` field in the input parameters of this call.
395510

396-
7. Considering the absence of the `TERMINAL_TOTAL_DIFFICULTY` value (i.e. when a value has not been decided), Consensus Layer and Execution Layer client software **MUST** use `115792089237316195423570985008687907853269984665640564039457584007913129638912` value (equal to`2**256-2**10`) for the `terminalTotalDifficulty` input parameter of this call.
511+
7. Considering the absence of the `TERMINAL_TOTAL_DIFFICULTY` value (i.e. when a value has not been decided), Consensus Layer and Execution Layer client software **MUST** use `115792089237316195423570985008687907853269984665640564039457584007913129638912` value (equal to`2**256-2**10`) for the `terminalTotalDifficulty` input parameter of this call.
397512

398513
[json-rpc-spec]: https://playground.open-rpc.org/?schemaUrl=https://raw.githubusercontent.com/ethereum/execution-apis/assembled-spec/openrpc.json&uiSchema[appBar][ui:splitView]=false&uiSchema[appBar][ui:input]=false&uiSchema[appBar][ui:examplesDropdown]=false

‎wordlist.txt‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -46,3 +46,5 @@ ssz
4646
kzg
4747
besu
4848
graphql
49+
gwei
50+
withdrawalv

0 commit comments

Comments
 (0)