From 5ad8fc0e6f0669bb6f0b40e2ad135387a5209c29 Mon Sep 17 00:00:00 2001 From: Mikhail Kalinin Date: Tue, 24 Jan 2023 13:24:33 +0100 Subject: [PATCH 1/5] Spec out getCapabilities --- src/engine/experimental/capabilities.md | 28 +++++++++++++++++++++++++ 1 file changed, 28 insertions(+) create mode 100644 src/engine/experimental/capabilities.md diff --git a/src/engine/experimental/capabilities.md b/src/engine/experimental/capabilities.md new file mode 100644 index 00000000..0834dca7 --- /dev/null +++ b/src/engine/experimental/capabilities.md @@ -0,0 +1,28 @@ +# Engine API -- Capabilities + +Specification of `engine_getCapabilities` method returning a list of Engine API methods supported by the server (execution layer client) down to a version of each method. + +The proposed method should become a part of [`common.md`](../common.md) document if accepted. + +## Methods + +### engine_getCapabilities + +*Note:* The method itself doesn't have a version suffix. + +#### Request + +* method: `engine_getCapabilities` +* 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. Client software **MUST** return a list of currently supported Engine API methods down to a version of each method. Consider the following response examples: + * `["engine_newPayloadV1", "engine_newPayloadV2", ...]` -- the software currently supports `V1` and `V2` versions of `engine_newPayload` method, + * `["engine_newPayloadV2", "engine_newPayloadV3", ...]` -- `V1` version has been deprecated, and `V3` have been introduced with respect to the above response. + +2. The `engine_getCapabilities` method **MUST NOT** be returned in the response list. From 7d29e03662cf54fc3d55efd5bc8186737136ac85 Mon Sep 17 00:00:00 2001 From: Mikhail Kalinin Date: Tue, 24 Jan 2023 16:02:03 +0100 Subject: [PATCH 2/5] Do exchange capabilities instead of get --- src/engine/experimental/capabilities.md | 21 +++++++++++++++------ 1 file changed, 15 insertions(+), 6 deletions(-) diff --git a/src/engine/experimental/capabilities.md b/src/engine/experimental/capabilities.md index 0834dca7..43909f79 100644 --- a/src/engine/experimental/capabilities.md +++ b/src/engine/experimental/capabilities.md @@ -1,18 +1,20 @@ # Engine API -- Capabilities -Specification of `engine_getCapabilities` method returning a list of Engine API methods supported by the server (execution layer client) down to a version of each method. +Specification of `engine_exchangeCapabilities` method exchanging with a list of Engine API methods supported by the server (execution layer client) and the client (consensus layer client) down to a version of each method. The proposed method should become a part of [`common.md`](../common.md) document if accepted. ## Methods -### engine_getCapabilities +### engine_exchangeCapabilities *Note:* The method itself doesn't have a version suffix. #### Request -* method: `engine_getCapabilities` +* 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 @@ -21,8 +23,15 @@ The proposed method should become a part of [`common.md`](../common.md) document #### Specification -1. Client software **MUST** return a list of currently supported Engine API methods down to a version of each method. Consider the following response examples: - * `["engine_newPayloadV1", "engine_newPayloadV2", ...]` -- the software currently supports `V1` and `V2` versions of `engine_newPayload` method, - * `["engine_newPayloadV2", "engine_newPayloadV3", ...]` -- `V1` version has been deprecated, and `V3` have been introduced with respect to the above response. +1. Consensus and execution layer client software **MUST** exchange with a list of currently supported Engine API methods down to a version of each method. 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 clonsensus layer client, so, both clients have the same capability set again: + * params: `["engine_newPayloadV2", "engine_newPayloadV3", ...]`, + * response: `["engine_newPayloadV2", "engine_newPayloadV3", ...]`. 2. The `engine_getCapabilities` method **MUST NOT** be returned in the response list. From ce06e22ad95332a4e1ca1c680b01f17e4ef898bf Mon Sep 17 00:00:00 2001 From: Mikhail Kalinin Date: Tue, 24 Jan 2023 18:17:27 +0100 Subject: [PATCH 3/5] Update capabilities.md --- src/engine/experimental/capabilities.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/engine/experimental/capabilities.md b/src/engine/experimental/capabilities.md index 43909f79..71d70042 100644 --- a/src/engine/experimental/capabilities.md +++ b/src/engine/experimental/capabilities.md @@ -30,7 +30,7 @@ The proposed method should become a part of [`common.md`](../common.md) document * `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 clonsensus layer client, so, both clients have the same capability set again: + * 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", ...]`. From b80db9f264dd6f397f2545a53f4c10ad19de93f6 Mon Sep 17 00:00:00 2001 From: Mikhail Kalinin Date: Wed, 25 Jan 2023 21:49:39 +0100 Subject: [PATCH 4/5] State that exchangeCapabilities is optional --- src/engine/experimental/capabilities.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/src/engine/experimental/capabilities.md b/src/engine/experimental/capabilities.md index 71d70042..9c90670c 100644 --- a/src/engine/experimental/capabilities.md +++ b/src/engine/experimental/capabilities.md @@ -23,7 +23,9 @@ The proposed method should become a part of [`common.md`](../common.md) document #### Specification -1. Consensus and execution layer client software **MUST** exchange with a list of currently supported Engine API methods down to a version of each method. Consider the following examples: +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", ...]`. @@ -34,4 +36,4 @@ The proposed method should become a part of [`common.md`](../common.md) document * params: `["engine_newPayloadV2", "engine_newPayloadV3", ...]`, * response: `["engine_newPayloadV2", "engine_newPayloadV3", ...]`. -2. The `engine_getCapabilities` method **MUST NOT** be returned in the response list. +3. The `engine_exchangeCapabilities` method **MUST NOT** be returned in the response list. From 984c906358bfe7d0b65dc09e15b5b2098d0e518a Mon Sep 17 00:00:00 2001 From: Mikhail Kalinin Date: Thu, 26 Jan 2023 23:28:35 +0100 Subject: [PATCH 5/5] Move exchangeCapabilities to common.md --- src/engine/common.md | 43 +++++++++++++++++++++++++ src/engine/experimental/capabilities.md | 39 ---------------------- 2 files changed, 43 insertions(+), 39 deletions(-) delete mode 100644 src/engine/experimental/capabilities.md diff --git a/src/engine/common.md b/src/engine/common.md index 8c654463..29bf49ea 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. diff --git a/src/engine/experimental/capabilities.md b/src/engine/experimental/capabilities.md deleted file mode 100644 index 9c90670c..00000000 --- a/src/engine/experimental/capabilities.md +++ /dev/null @@ -1,39 +0,0 @@ -# Engine API -- Capabilities - -Specification of `engine_exchangeCapabilities` method exchanging with a list of Engine API methods supported by the server (execution layer client) and the client (consensus layer client) down to a version of each method. - -The proposed method should become a part of [`common.md`](../common.md) document if accepted. - -## Methods - -### engine_exchangeCapabilities - -*Note:* The method itself doesn't have a version suffix. - -#### 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.