Engine API: introduce exchangeCapabilities

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