From d79298ea502c2ade06f17d7948e7a2d967049832 Mon Sep 17 00:00:00 2001
From: ethDreamer <37123614+ethDreamer@users.noreply.github.com>
Date: Wed, 14 Feb 2024 00:06:05 +1100
Subject: [PATCH] Specify Client Versions on Engine API (#517)

* Expose web3_clientVersion on Engine API

* Specify `engine_clientIdentificationV1`

* Rename to `engine_clientVersionV1`

Also specify Grandine abbreviation and accomodate other versioning
systems.

* Fix broken TOC link

* fix spelling

* Remove References to web3_clientVersion

* Rename & Accommodate Multiplexers

* spelling..

* Update src/engine/identification.md

Co-authored-by: lightclient <14004106+lightclient@users.noreply.github.com>

* Update src/engine/identification.md

Co-authored-by: lightclient <14004106+lightclient@users.noreply.github.com>

* Add words to wordlist.txt

---------

Co-authored-by: lightclient <14004106+lightclient@users.noreply.github.com>
---
 src/engine/identification.md | 76 ++++++++++++++++++++++++++++++++++++
 wordlist.txt                 |  5 +++
 2 files changed, 81 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 000000000..7898c75ae
--- /dev/null
+++ b/src/engine/identification.md
@@ -0,0 +1,76 @@
+# Engine API -- Client Version Specification
+
+Engine API structures and methods specified for client version specification.
+
+## Table of contents
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+
+- [Client Version Specification](#client-version-specification)
+- [Structures](#structures)
+  - [ClientCode](#clientcode)
+  - [ClientVersionV1](#clientversionv1)
+- [Methods](#methods)
+  - [engine_getClientVersionV1](#engine_getclientversionv1)
+    - [Request](#request)
+    - [Response](#response)
+    - [Specification](#specification)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+## 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.
+
+## 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
+ - `GR`: grandine
+ - `LH`: lighthouse
+ - `LS`: lodestar
+ - `NM`: nethermind
+ - `NB`: nimbus
+ - `TK`: teku
+ - `PM`: prysm
+ - `RH`: reth
+
+### ClientVersionV1
+
+This structure contains information which identifies a client implementation. The fields are encoded as follows:
+
+- `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`: `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`).
+
+## Methods
+
+### engine_getClientVersionV1
+
+#### Request
+
+* method: `engine_getClientVersionV1`
+* params:
+  1. [`ClientVersionV1`](#ClientVersionV1) - identifies the consensus client
+* timeout: 1s
+
+#### Response
+* 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** 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** 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
diff --git a/wordlist.txt b/wordlist.txt
index fef7a4af8..1a4dd1b84 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