diff --git a/src/engine/specification.md b/src/engine/specification.md index 7d502d18b..a4c05907a 100644 --- a/src/engine/specification.md +++ b/src/engine/specification.md @@ -18,6 +18,7 @@ This document specifies the Engine API methods that the Consensus Layer uses to - [ExecutionPayloadV1](#executionpayloadv1) - [WithdrawalV1](#withdrawalv1) - [ExecutionPayloadV2](#executionpayloadv2) + - [ExecutionPayloadSyncContextV1](#executionpayloadsynccontextv1) - [ForkchoiceStateV1](#forkchoicestatev1) - [PayloadAttributesV1](#payloadattributesv1) - [PayloadAttributesV2](#payloadattributesv2) @@ -56,6 +57,11 @@ This document specifies the Engine API methods that the Consensus Layer uses to - [Request](#request-6) - [Response](#response-6) - [Specification](#specification-6) +- [Optional endpoints](#optional-endpoints) + - [engine_newPayloadSyncContextV1](#engine_newpayloadsynccontextv1) + - [Request](#request-7) + - [Response](#response-7) + - [Specification](#specification-7) @@ -221,6 +227,15 @@ This structure has the syntax of `ExecutionPayloadV1` and appends a single field - `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. +### ExecutionPayloadSyncContextV1 + +This structure provides a subset of `ExecutionPayload` fields to allow triggering sync without supplying the full `ExecutionPayload`. The fields are encoded as follows: + +- `parentHash`: `DATA`, 32 Bytes +- `stateRoot`: `DATA`, 32 Bytes +- `blockNumber`: `QUANTITY`, 64 Bits +- `blockHash`: `DATA`, 32 Bytes + ### ForkchoiceStateV1 This structure encapsulates the fork choice state. The fields are encoded as follows: @@ -511,3 +526,32 @@ Refer to the specification for [`engine_getPayloadV1`](#engine_getpayloadv1). 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 + +## Optional endpoints + +### engine_newPayloadSyncContextV1 + +#### Request + +* method: `engine_newPayloadSyncContextV1` +* params: + 1. [`ExecutionPayloadSyncContextV1`](#executionpayloadsynccontextv1) +* timeout: 8s + +#### Response + +Refer to the response for [`engine_newPayloadV2`](#engine_newpayloadv2). + +#### Specification + +1. Execution Layer client software **MAY** initiate a sync process if the described block is not locally available. Sync process is specified in the [Sync](#sync) section. Execution Layer client software **MUST** support syncing solely based on calls to this endpoint and `engine_forkchoiceUpdated`. Notably, syncing **MUST** be possible without `engine_newPayload` calls. + +2. Execution Layer client software **MUST** respond to this method call in the following way: + * `{status: SYNCING, latestValidHash: null, validationError: null}` if the request was processed + * An error object in any error conditions unrelated to the normal processing flow of the method + +3. Consensus Layer client software **MUST NOT** use this endpoint for validator duties. Instead, the [`engine_newPayloadV2`](#engine_getpayloadv2) endpoint **MUST** be used to validate the full `ExecutionPayload` structure. + +4. Consensus Layer client software **MAY** use this endpoint during an ongoing sync to inform Execution Layer client software about blocks far in the future (e.g., by running a [light client](https://github.com/ethereum/consensus-specs/blob/dev/specs/altair/light-client/sync-protocol.md) during [optimistic sync](https://github.com/ethereum/consensus-specs/blob/dev/sync/optimistic.md)). Execution Layer client software **SHOULD** consider interrupting the ongoing sync when requested to switch to the provided `blockHash` using `engine_forkchoiceUpdated`. + +5. Client software **MAY** offer configuration options to limit the sync scope to use case dependent data (e.g., only sync data related to a certain wallet).