Skip to content

Commit

Permalink
Add withdrawal operations (#195)
Browse files Browse the repository at this point in the history 
* 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 <14004106+lightclient@users.noreply.github.com>

* update `WithdrawalV1` definition with the validatorIndex

* clarify the handling of empty vs `null` withdrawals

* Update src/engine/specification.md

Co-authored-by: terencechain <terence@prysmaticlabs.com>

Co-authored-by: lightclient <14004106+lightclient@users.noreply.github.com>
Co-authored-by: terencechain <terence@prysmaticlabs.com>
  • Loading branch information
@ralexstokes @lightclient @terencechain
3 people committed Nov 3, 2022
1 parent 619c3f7 commit f33432b
Show file tree
Hide file tree
Showing 2 changed files with 124 additions and 7 deletions.
129 changes: 122 additions & 7 deletions src/engine/specification.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,8 +16,11 @@ This document specifies the Engine API methods that the Consensus Layer uses to
- [Timeouts](#timeouts)
- [Structures](#structures)
- [ExecutionPayloadV1](#executionpayloadv1)
- [WithdrawalV1](#withdrawalv1)
- [ExecutionPayloadV2](#executionpayloadv2)
- [ForkchoiceStateV1](#forkchoicestatev1)
- [PayloadAttributesV1](#payloadattributesv1)
- [PayloadAttributesV2](#payloadattributesv2)
- [PayloadStatusV1](#payloadstatusv1)
- [TransitionConfigurationV1](#transitionconfigurationv1)
- [Routines](#routines)
Expand All @@ -29,18 +32,30 @@ This document specifies the Engine API methods that the Consensus Layer uses to
- [Request](#request)
- [Response](#response)
- [Specification](#specification)
- [engine_forkchoiceUpdatedV1](#engine_forkchoiceupdatedv1)
- [engine_newPayloadV2](#engine_newpayloadv2)
- [Request](#request-1)
- [Response](#response-1)
- [Specification](#specification-1)
- [engine_getPayloadV1](#engine_getpayloadv1)
- [engine_forkchoiceUpdatedV1](#engine_forkchoiceupdatedv1)
- [Request](#request-2)
- [Response](#response-2)
- [Specification](#specification-2)
- [engine_exchangeTransitionConfigurationV1](#engine_exchangetransitionconfigurationv1)
- [engine_forkchoiceUpdatedV2](#engine_forkchoiceupdatedv2)
- [Request](#request-3)
- [Response](#response-3)
- [Specification](#specification-3)
- [engine_getPayloadV1](#engine_getpayloadv1)
- [Request](#request-4)
- [Response](#response-4)
- [Specification](#specification-4)
- [engine_getPayloadV2](#engine_getpayloadv2)
- [Request](#request-5)
- [Response](#response-5)
- [Specification](#specification-5)
- [engine_exchangeTransitionConfigurationV1](#engine_exchangetransitionconfigurationv1)
- [Request](#request-6)
- [Response](#response-6)
- [Specification](#specification-6)

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

Expand Down Expand Up @@ -112,7 +127,7 @@ The list of error codes introduced by this specification can be found below.
| -32700 | Parse error | Invalid JSON was received by the server. |
| -32600 | Invalid Request | The JSON sent is not a valid Request object. |
| -32601 | Method not found | The method does not exist / is not available. |
| -32602 | Invalid params | Invalid method parameter(s). |
| -32602 | Invalid params | Invalid method parameter(s). |
| -32603 | Internal error | Internal JSON-RPC error. |
| -32000 | Server error | Generic client error while processing request. |
| -38001 | Unknown payload | Payload does not exist / is not available. |
Expand Down Expand Up @@ -174,6 +189,38 @@ This structure maps on the [`ExecutionPayload`](https://github.com/ethereum/cons
- `blockHash`: `DATA`, 32 Bytes
- `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)

### WithdrawalV1

This structure maps onto the validator withdrawal object from the beacon chain spec.
The fields are encoded as follows:

- `index`: `QUANTITY`, 64 Bits
- `validatorIndex`: `QUANTITY`, 64 Bits
- `address`: `DATA`, 20 Bytes
- `amount`: `QUANTITY`, 256 Bits

*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.

### ExecutionPayloadV2

This structure has the syntax of `ExecutionPayloadV1` and appends a single field: `withdrawals`.

- `parentHash`: `DATA`, 32 Bytes
- `feeRecipient`: `DATA`, 20 Bytes
- `stateRoot`: `DATA`, 32 Bytes
- `receiptsRoot`: `DATA`, 32 Bytes
- `logsBloom`: `DATA`, 256 Bytes
- `prevRandao`: `DATA`, 32 Bytes
- `blockNumber`: `QUANTITY`, 64 Bits
- `gasLimit`: `QUANTITY`, 64 Bits
- `gasUsed`: `QUANTITY`, 64 Bits
- `timestamp`: `QUANTITY`, 64 Bits
- `extraData`: `DATA`, 0 to 32 Bytes
- `baseFeePerGas`: `QUANTITY`, 256 Bits
- `blockHash`: `DATA`, 32 Bytes
- `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)
- `withdrawals`: `Array of WithdrawalV1` - Array of withdrawals, each object is an `OBJECT` containing the fields of a `WithdrawalV1` structure.

### ForkchoiceStateV1

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

### PayloadAttributesV2

This structure has the syntax of `PayloadAttributesV1` and appends a single field: `withdrawals`.

- `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
- `suggestedFeeRecipient`: `DATA`, 20 Bytes - suggested value for the `feeRecipient` field of the new payload
- `withdrawals`: `Array of WithdrawalV1` - Array of withdrawals, each object is an `OBJECT` containing the fields of a `WithdrawalV1` structure.

### PayloadStatusV1

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

* method: `engine_newPayloadV1`
* params:
* params:
1. [`ExecutionPayloadV1`](#ExecutionPayloadV1)
* timeout: 8s

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

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.

### engine_newPayloadV2

#### Request

* method: `engine_newPayloadV2`
* params:
1. [`ExecutionPayloadV2`](#ExecutionPayloadV2)

#### Response

Refer to the response for [`engine_newPayloadV1`](#engine_newpayloadv1).

#### Specification

This method follows the same specification as [`engine_newPayloadV1`](#engine_newpayloadv1) with the exception of the following:

1. If withdrawal functionality is activated, client software **MUST** return an `INVALID` status with the appropriate `latestValidHash` if `payload.withdrawals` is `null`.
Similarly, if the functionality is not activated, client software **MUST** return an `INVALID` status with the appropriate `latestValidHash` if `payloadAttributes.withdrawals` is not `null`.
Blocks without withdrawals **MUST** be expressed with an explicit empty list `[]` value.
Refer to the validity conditions for [`engine_newPayloadV1`](#engine_newpayloadv1) to specification of the appropriate `latestValidHash` value.

### engine_forkchoiceUpdatedV1

#### Request

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

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.

### engine_forkchoiceUpdatedV2

#### Request

* method: "engine_forkchoiceUpdatedV2"
* params:
1. `forkchoiceState`: `Object` - instance of [`ForkchoiceStateV1`](#ForkchoiceStateV1)
2. `payloadAttributes`: `Object|null` - instance of [`PayloadAttributesV2`](#PayloadAttributesV2) or `null`

#### Response

Refer to the response for [`engine_forkchoiceUpdatedV1`](#engine_forkchoiceupdatedv1).

#### Specification

This method follows the same specification as [`engine_forkchoiceUpdatedV1`](#engine_forkchoiceupdatedv1) with the exception of the following:

1. If withdrawal functionality is activated, client software **MUST** return error `-38003: Invalid payload attributes` if `payloadAttributes.withdrawals` is `null`.
Similarly, if the functionality is not activated, client software **MUST** return error `-38003: Invalid payload attributes` if `payloadAttributes.withdrawals` is not `null`.
Blocks without withdrawals **MUST** be expressed with an explicit empty list `[]` value.

### engine_getPayloadV1

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

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

### engine_getPayloadV2

#### Request

* method: `engine_getPayloadV2`
* params:
1. `payloadId`: `DATA`, 8 Bytes - Identifier of the payload build process

#### Response

* result: [`ExecutionPayloadV2`](#ExecutionPayloadV2)
* error: code and message set in case an exception happens while getting the payload.

#### Specification

Refer to the specification for [`engine_getPayloadV1`](#engine_getpayloadv1).

### engine_exchangeTransitionConfigurationV1

#### Request
Expand Down Expand Up @@ -393,6 +508,6 @@ The payload build process is specified as follows:

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.

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.
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.

[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
2 changes: 2 additions & 0 deletions wordlist.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -46,3 +46,5 @@ ssz
kzg
besu
graphql
gwei
withdrawalv

0 comments on commit f33432b

Please sign in to comment.