Add engine_newPayloadSyncContextV1

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)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
@@ -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).