Skip to content

Engine API: introduce exchangeCapabilities #364

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Jan 26, 2023
Merged

Engine API: introduce exchangeCapabilities #364

Changes from 3 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
5ad8fc0
Spec out getCapabilities
mkalinin Jan 24, 2023
7d29e03
Do exchange capabilities instead of get
mkalinin Jan 24, 2023
ce06e22
Update capabilities.md
mkalinin Jan 24, 2023
b80db9f
State that exchangeCapabilities is optional
mkalinin Jan 25, 2023
984c906
Move exchangeCapabilities to common.md
mkalinin Jan 26, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 37 additions & 0 deletions src/engine/experimental/capabilities.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
# 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 **MUST** exchange with a list of currently supported Engine API methods down to a version of each method. Consider the following examples:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The call to getCapabilities is strictly redundant / there's no real need to call it for communication to work and MUST makes it impossible to restart an execution client without notifying the CL - ie the CL cannot generally detect that the EL went down, meaning both EL and CL must support this function not having been called at all.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've made it in a bit different way. But the first statement in the spec is clearly saying that this method may be used and that EL must not surface any error messages based on the time when this method was or was not called. Hopefully, this addresses the concern.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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** optionally 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 consensus 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.