diff --git a/src/engine/common.md b/src/engine/common.md index 8c6544635..29bf49ead 100644 --- a/src/engine/common.md +++ b/src/engine/common.md @@ -15,6 +15,11 @@ This document specifies common definitions and requirements affecting Engine API - [Errors](#errors) - [Timeouts](#timeouts) - [Encoding](#encoding) +- [Capabilities](#capabilities) + - [engine_exchangeCapabilities](#engine_exchangecapabilities) + - [Request](#request) + - [Response](#response) + - [Specification](#specification) @@ -130,3 +135,41 @@ Values of a field of `QUANTITY` type **MUST** be encoded as a hexadecimal string *Note:* Byte order of encoded value having `QUANTITY` type is big-endian. [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 + +## Capabilities + +Execution and consensus layer client software may exchange with a list of supported Engine API methods by calling `engine_exchangeCapabilities` method. + +Execution layer clients **MUST** support `engine_exchangeCapabilities` method, while consensus layer clients are free to choose whether to call it or not. + +*Note:* The method itself doesn't have a version suffix. + +### engine_exchangeCapabilities + +#### Request + +* method: `engine_exchangeCapabilities` +* params: + 1. `Array of string` -- Array of strings, each string is a name of a method supported by consensus layer client software. +* timeout: 1s + +#### Response + +`Array of string` -- Array of strings, each string is a name of a method supported by execution layer client software. + +#### Specification + +1. Consensus and execution layer client software **MAY** exchange with a list of currently supported Engine API methods. Execution layer client software **MUST NOT** log any error messages if this method has either never been called or haven't been called for a significant amount of time. + +2. Request and response lists **MUST** contain Engine API methods that are currently supported by consensus and execution client software respectively. Name of each method in both lists **MUST** include suffixed version. Consider the following examples: + * Client software of both layers currently supports `V1` and `V2` versions of `engine_newPayload` method: + * params: `["engine_newPayloadV1", "engine_newPayloadV2", ...]`, + * response: `["engine_newPayloadV1", "engine_newPayloadV2", ...]`. + * `V1` method has been deprecated and `V3` method has been introduced on execution layer side since the last call: + * params: `["engine_newPayloadV1", "engine_newPayloadV2", ...]`, + * response: `["engine_newPayloadV2", "engine_newPayloadV3", ...]`. + * The same capabilities modification has happened in consensus layer client, so, both clients have the same capability set again: + * params: `["engine_newPayloadV2", "engine_newPayloadV3", ...]`, + * response: `["engine_newPayloadV2", "engine_newPayloadV3", ...]`. + +3. The `engine_exchangeCapabilities` method **MUST NOT** be returned in the response list.