From 3016309345a22d96e3e6357ace9b9b0be38c471a Mon Sep 17 00:00:00 2001 From: Mark Mackey Date: Fri, 26 Jan 2024 15:21:09 +0800 Subject: [PATCH 01/11] Expose web3_clientVersion on Engine API --- src/engine/common.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/src/engine/common.md b/src/engine/common.md index 735f8d9e..8402516f 100644 --- a/src/engine/common.md +++ b/src/engine/common.md @@ -44,6 +44,11 @@ the client **MUST** also expose the following subset of `eth` methods: * `eth_sendRawTransaction` * `eth_syncing` +To facilitate a more accurate measurement of execution layer client diversity statistics, the client **SHOULD** also expose +the following `web3` method: + +* `web3_clientVersion` + These methods are described in [Ethereum JSON-RPC Specification][json-rpc-spec]. ### Authentication From 70c3f0ef962798a2a9a1ea71674aa7a60036f8b7 Mon Sep 17 00:00:00 2001 From: Mark Mackey Date: Mon, 29 Jan 2024 13:16:14 +0800 Subject: [PATCH 02/11] Specify `engine_clientIdentificationV1` --- src/engine/identification.md | 73 ++++++++++++++++++++++++++++++++++++ 1 file changed, 73 insertions(+) create mode 100644 src/engine/identification.md diff --git a/src/engine/identification.md b/src/engine/identification.md new file mode 100644 index 00000000..ea378889 --- /dev/null +++ b/src/engine/identification.md @@ -0,0 +1,73 @@ +# Engine API -- Client Identification + +Engine API structures and methods specified for client identification. + +## Table of contents + + + + +- [Client Identification](#client-identification) +- [Structures](#structures) + - [ClientCode](#clientcode) + - [ClientIdentificationV1](#clientidentificationv1) +- [Methods](#methods) + - [engine_clientIdentificationV1](#engine_clientidentificationv1) + - [Request](#request) + - [Response](#response) + - [Specification](#specification) + + + +## Client Identification + +To facilitate a more accurate measurement of execution layer client diversity statistics, execution clients **SHOULD** support the methods described in this document. + +## Structures + +### ClientCode + +This enum defines a standard for specifying a client with just two letters. Clients teams which have a code reserved in this list **MUST** use this code when identifying themselves. The code is specified here only to facilitate standardization and NOT to imply that these are the only supported Ethereum clients. Any clients not listed here are free to use any two letters which don't collide with an existing client code. They are encouraged to make a PR to this repo to reserve their own code. Existing codes are as follows: + + - `BU`: besu + - `EJ`: ethereumJS + - `EG`: erigon + - `GE`: go-ethereum + - `LH`: lighthouse + - `LS`: lodestar + - `NM`: nethermind + - `NB`: nimbus + - `TK`: teku + - `PM`: prysm + - `RH`: reth + +### ClientIdentificationV1 + +This structure contains information which identifies a client implementatiopn. The fields are encoded as follows: + +- `code`: `ClientCode`, e.g. `NB` or `BU` +- `clientName`: `string`, Human-readable name of the client, e.g. `Lighthouse` or `go-ethereum` +- `version`: `string`, the standard semantic version string of the current implementation e.g. `v4.6.0` or `1.0.0-alpha.1` or `1.0.0+20130313144700` +- `commit`: `string`, the hex of the first 4 bytes of the latest commit hash of this build e.g. `fa4ff922` + +Rationale: Human-readable fields like `clientName` and `version` are useful for log messages while fields like `code` and `commit` are useful for uniquely specifying clients within a limited space (e.g. in block `graffiti`). + +## Methods + +### engine_clientIdentificationV1 + +#### Request + +* method: `engine_clientIdentificationV1` +* params: + 1. [`ClientIdentificationV1`](#ClientIdentificationV1) - identifies the consensus client +* timeout: 1s + +#### Response + +* result: [`ClientIdentificationV1`](#ClientIdentificationV1) - identifies the execution client + +#### Specification + +1. Consensus and execution layer clients **MAY** exchange `ClientIdentificationV1` objects. Execution clients **MUST NOT** log any error messages if this method has either never been called or hasn't been called for a significant amount of time. +2. Clients **MUST** accomodate receiving any two-letter `ClientCode`, even if they are not reserved in the list above. Clients **MAY** log messages upon receiving an unlisted client code. \ No newline at end of file From 662693ae233e20d4da71a6ab98375be5fd6fa99c Mon Sep 17 00:00:00 2001 From: Mark Mackey Date: Mon, 29 Jan 2024 14:28:01 +0800 Subject: [PATCH 03/11] Rename to `engine_clientVersionV1` Also specify Grandine abbreviation and accomodate other versioning systems. --- src/engine/identification.md | 25 +++++++++++++------------ 1 file changed, 13 insertions(+), 12 deletions(-) diff --git a/src/engine/identification.md b/src/engine/identification.md index ea378889..e4401b68 100644 --- a/src/engine/identification.md +++ b/src/engine/identification.md @@ -1,6 +1,6 @@ -# Engine API -- Client Identification +# Engine API -- Client Version Specification -Engine API structures and methods specified for client identification. +Engine API structures and methods specified for client version specification. ## Table of contents @@ -10,16 +10,16 @@ Engine API structures and methods specified for client identification. - [Client Identification](#client-identification) - [Structures](#structures) - [ClientCode](#clientcode) - - [ClientIdentificationV1](#clientidentificationv1) + - [ClientVersionV1](#clientversionv1) - [Methods](#methods) - - [engine_clientIdentificationV1](#engine_clientidentificationv1) + - [engine_clientVersionV1](#engine_clientversionv1) - [Request](#request) - [Response](#response) - [Specification](#specification) -## Client Identification +## Client Version Specification To facilitate a more accurate measurement of execution layer client diversity statistics, execution clients **SHOULD** support the methods described in this document. @@ -33,6 +33,7 @@ This enum defines a standard for specifying a client with just two letters. Clie - `EJ`: ethereumJS - `EG`: erigon - `GE`: go-ethereum + - `GR`: grandine - `LH`: lighthouse - `LS`: lodestar - `NM`: nethermind @@ -41,33 +42,33 @@ This enum defines a standard for specifying a client with just two letters. Clie - `PM`: prysm - `RH`: reth -### ClientIdentificationV1 +### ClientVersionV1 This structure contains information which identifies a client implementatiopn. The fields are encoded as follows: - `code`: `ClientCode`, e.g. `NB` or `BU` - `clientName`: `string`, Human-readable name of the client, e.g. `Lighthouse` or `go-ethereum` -- `version`: `string`, the standard semantic version string of the current implementation e.g. `v4.6.0` or `1.0.0-alpha.1` or `1.0.0+20130313144700` +- `version`: `string`, the version string of the current implementation e.g. `v4.6.0` or `1.0.0-alpha.1` or `1.0.0+20130313144700` - `commit`: `string`, the hex of the first 4 bytes of the latest commit hash of this build e.g. `fa4ff922` Rationale: Human-readable fields like `clientName` and `version` are useful for log messages while fields like `code` and `commit` are useful for uniquely specifying clients within a limited space (e.g. in block `graffiti`). ## Methods -### engine_clientIdentificationV1 +### engine_clientVersionV1 #### Request -* method: `engine_clientIdentificationV1` +* method: `engine_clientVersionV1` * params: - 1. [`ClientIdentificationV1`](#ClientIdentificationV1) - identifies the consensus client + 1. [`ClientVersionV1`](#ClientVersionV1) - identifies the consensus client * timeout: 1s #### Response -* result: [`ClientIdentificationV1`](#ClientIdentificationV1) - identifies the execution client +* result: [`ClientVersionV1`](#ClientVersionV1) - identifies the execution client #### Specification -1. Consensus and execution layer clients **MAY** exchange `ClientIdentificationV1` objects. Execution clients **MUST NOT** log any error messages if this method has either never been called or hasn't been called for a significant amount of time. +1. Consensus and execution layer clients **MAY** exchange `ClientVersionV1` objects. Execution clients **MUST NOT** log any error messages if this method has either never been called or hasn't been called for a significant amount of time. 2. Clients **MUST** accomodate receiving any two-letter `ClientCode`, even if they are not reserved in the list above. Clients **MAY** log messages upon receiving an unlisted client code. \ No newline at end of file From b05fae55a4a0d95e05c735f31c3d23597ac704c7 Mon Sep 17 00:00:00 2001 From: Mark Mackey Date: Mon, 29 Jan 2024 14:31:20 +0800 Subject: [PATCH 04/11] Fix broken TOC link --- src/engine/identification.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/engine/identification.md b/src/engine/identification.md index e4401b68..d1a3577b 100644 --- a/src/engine/identification.md +++ b/src/engine/identification.md @@ -7,7 +7,7 @@ Engine API structures and methods specified for client version specification. -- [Client Identification](#client-identification) +- [Client Version Specification](#client-version-specification) - [Structures](#structures) - [ClientCode](#clientcode) - [ClientVersionV1](#clientversionv1) From 7d5718e9c92e57a652f575d5d92a578e425a16f1 Mon Sep 17 00:00:00 2001 From: Mark Mackey Date: Mon, 29 Jan 2024 14:38:04 +0800 Subject: [PATCH 05/11] fix spelling --- src/engine/identification.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/engine/identification.md b/src/engine/identification.md index d1a3577b..5affd2e6 100644 --- a/src/engine/identification.md +++ b/src/engine/identification.md @@ -44,7 +44,7 @@ This enum defines a standard for specifying a client with just two letters. Clie ### ClientVersionV1 -This structure contains information which identifies a client implementatiopn. The fields are encoded as follows: +This structure contains information which identifies a client implementation. The fields are encoded as follows: - `code`: `ClientCode`, e.g. `NB` or `BU` - `clientName`: `string`, Human-readable name of the client, e.g. `Lighthouse` or `go-ethereum` From ad6eeb7ad765e6e65a4efd49dd7d87b928c0e851 Mon Sep 17 00:00:00 2001 From: Mark Mackey Date: Wed, 31 Jan 2024 11:28:38 +0800 Subject: [PATCH 06/11] Remove References to web3_clientVersion --- src/engine/common.md | 5 ----- src/engine/identification.md | 2 +- 2 files changed, 1 insertion(+), 6 deletions(-) diff --git a/src/engine/common.md b/src/engine/common.md index 8402516f..735f8d9e 100644 --- a/src/engine/common.md +++ b/src/engine/common.md @@ -44,11 +44,6 @@ the client **MUST** also expose the following subset of `eth` methods: * `eth_sendRawTransaction` * `eth_syncing` -To facilitate a more accurate measurement of execution layer client diversity statistics, the client **SHOULD** also expose -the following `web3` method: - -* `web3_clientVersion` - These methods are described in [Ethereum JSON-RPC Specification][json-rpc-spec]. ### Authentication diff --git a/src/engine/identification.md b/src/engine/identification.md index 5affd2e6..ae8acc8f 100644 --- a/src/engine/identification.md +++ b/src/engine/identification.md @@ -41,7 +41,7 @@ This enum defines a standard for specifying a client with just two letters. Clie - `TK`: teku - `PM`: prysm - `RH`: reth - + ### ClientVersionV1 This structure contains information which identifies a client implementation. The fields are encoded as follows: From 68bdbd6b6afa69b43a5070c5ff2fa281c4750966 Mon Sep 17 00:00:00 2001 From: Mark Mackey Date: Fri, 2 Feb 2024 12:59:55 +0800 Subject: [PATCH 07/11] Rename & Accommodate Multiplexers --- src/engine/identification.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/src/engine/identification.md b/src/engine/identification.md index ae8acc8f..c66f7598 100644 --- a/src/engine/identification.md +++ b/src/engine/identification.md @@ -12,7 +12,7 @@ Engine API structures and methods specified for client version specification. - [ClientCode](#clientcode) - [ClientVersionV1](#clientversionv1) - [Methods](#methods) - - [engine_clientVersionV1](#engine_clientversionv1) + - [engine_getClientVersionV1](#engine_getclientversionv1) - [Request](#request) - [Response](#response) - [Specification](#specification) @@ -55,20 +55,22 @@ Rationale: Human-readable fields like `clientName` and `version` are useful for ## Methods -### engine_clientVersionV1 +### engine_getClientVersionV1 #### Request -* method: `engine_clientVersionV1` +* method: `engine_getClientVersionV1` * params: 1. [`ClientVersionV1`](#ClientVersionV1) - identifies the consensus client * timeout: 1s #### Response - -* result: [`ClientVersionV1`](#ClientVersionV1) - identifies the execution client +* result: `Array of ClientVersionV1` - Array of [`ClientVersionV1`](#ClientVersionV1) #### Specification 1. Consensus and execution layer clients **MAY** exchange `ClientVersionV1` objects. Execution clients **MUST NOT** log any error messages if this method has either never been called or hasn't been called for a significant amount of time. -2. Clients **MUST** accomodate receiving any two-letter `ClientCode`, even if they are not reserved in the list above. Clients **MAY** log messages upon receiving an unlisted client code. \ No newline at end of file +2. Clients **MUST** accommodate receiving any two-letter `ClientCode`, even if they are not reserved in the list above. Clients **MAY** log messages upon receiving an unlisted client code. +3. When connected to a single execution client, the consensus client **MUST** receieve an array with a single +`ClientVersionV1` object. When connected to multiple execution clients via a multiplexer, the multiplexer **MUST** concatenate the responses from each execution client into a single, flat array before returning the +response to the consensus client. \ No newline at end of file From 79ffb4eb8dbbffe969fc56f735aca5a47d69753a Mon Sep 17 00:00:00 2001 From: Mark Mackey Date: Fri, 2 Feb 2024 13:02:25 +0800 Subject: [PATCH 08/11] spelling.. --- src/engine/identification.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/engine/identification.md b/src/engine/identification.md index c66f7598..3114fafe 100644 --- a/src/engine/identification.md +++ b/src/engine/identification.md @@ -71,6 +71,6 @@ Rationale: Human-readable fields like `clientName` and `version` are useful for 1. Consensus and execution layer clients **MAY** exchange `ClientVersionV1` objects. Execution clients **MUST NOT** log any error messages if this method has either never been called or hasn't been called for a significant amount of time. 2. Clients **MUST** accommodate receiving any two-letter `ClientCode`, even if they are not reserved in the list above. Clients **MAY** log messages upon receiving an unlisted client code. -3. When connected to a single execution client, the consensus client **MUST** receieve an array with a single +3. When connected to a single execution client, the consensus client **MUST** receive an array with a single `ClientVersionV1` object. When connected to multiple execution clients via a multiplexer, the multiplexer **MUST** concatenate the responses from each execution client into a single, flat array before returning the response to the consensus client. \ No newline at end of file From 1383036faed9021027f34a7a081fb475b57b1818 Mon Sep 17 00:00:00 2001 From: ethDreamer <37123614+ethDreamer@users.noreply.github.com> Date: Mon, 5 Feb 2024 10:23:15 +0800 Subject: [PATCH 09/11] Update src/engine/identification.md Co-authored-by: lightclient <14004106+lightclient@users.noreply.github.com> --- src/engine/identification.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/engine/identification.md b/src/engine/identification.md index 3114fafe..11b4bd81 100644 --- a/src/engine/identification.md +++ b/src/engine/identification.md @@ -47,7 +47,7 @@ This enum defines a standard for specifying a client with just two letters. Clie This structure contains information which identifies a client implementation. The fields are encoded as follows: - `code`: `ClientCode`, e.g. `NB` or `BU` -- `clientName`: `string`, Human-readable name of the client, e.g. `Lighthouse` or `go-ethereum` +- `name`: `string`, Human-readable name of the client, e.g. `Lighthouse` or `go-ethereum` - `version`: `string`, the version string of the current implementation e.g. `v4.6.0` or `1.0.0-alpha.1` or `1.0.0+20130313144700` - `commit`: `string`, the hex of the first 4 bytes of the latest commit hash of this build e.g. `fa4ff922` From 364ad1b09de709ea288b475bdd9b6de2a8ef7f3a Mon Sep 17 00:00:00 2001 From: ethDreamer <37123614+ethDreamer@users.noreply.github.com> Date: Mon, 5 Feb 2024 10:23:45 +0800 Subject: [PATCH 10/11] Update src/engine/identification.md Co-authored-by: lightclient <14004106+lightclient@users.noreply.github.com> --- src/engine/identification.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/engine/identification.md b/src/engine/identification.md index 11b4bd81..7898c75a 100644 --- a/src/engine/identification.md +++ b/src/engine/identification.md @@ -49,7 +49,7 @@ This structure contains information which identifies a client implementation. Th - `code`: `ClientCode`, e.g. `NB` or `BU` - `name`: `string`, Human-readable name of the client, e.g. `Lighthouse` or `go-ethereum` - `version`: `string`, the version string of the current implementation e.g. `v4.6.0` or `1.0.0-alpha.1` or `1.0.0+20130313144700` -- `commit`: `string`, the hex of the first 4 bytes of the latest commit hash of this build e.g. `fa4ff922` +- `commit`: `DATA`, 4 bytes - first four bytes of the latest commit hash of this build e.g. `fa4ff922` Rationale: Human-readable fields like `clientName` and `version` are useful for log messages while fields like `code` and `commit` are useful for uniquely specifying clients within a limited space (e.g. in block `graffiti`). From 3b1e1b1d41d2fa33d1ba11e35fd221a657627721 Mon Sep 17 00:00:00 2001 From: Mark Mackey Date: Mon, 5 Feb 2024 10:28:01 +0800 Subject: [PATCH 11/11] Add words to wordlist.txt --- wordlist.txt | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/wordlist.txt b/wordlist.txt index fef7a4af..1a4dd1b8 100644 --- a/wordlist.txt +++ b/wordlist.txt @@ -4,6 +4,7 @@ bodyv bodiesbyrangev bodiesbyhashv bytecode +clientversionv configurationv crypto eip @@ -11,6 +12,9 @@ endian enum eth ethereum +ethereumjs +erigon +getclientversionv interop json mempool @@ -29,6 +33,7 @@ secp statev statusv sha +teku uint updatedv url