feat: include EL client info in graffiti

packages/api/src/beacon/routes/validator.ts

@@ -304,13 +304,13 @@ export type Endpoints = {
       /** The validator's randao reveal value */
       randaoReveal: BLSSignature;
       /** Arbitrary data validator wants to include in block */
-      graffiti: string;
+      graffiti?: string;
     } & Omit<ExtraProduceBlockOpts, "blindedLocal">,
     {
       params: {slot: number};
       query: {
         randao_reveal: string;
-        graffiti: string;
+        graffiti?: string;
         fee_recipient?: string;
         builder_selection?: string;
         strict_fee_recipient_check?: boolean;
@@ -333,15 +333,15 @@ export type Endpoints = {
       /** The validator's randao reveal value */
       randaoReveal: BLSSignature;
       /** Arbitrary data validator wants to include in block */
-      graffiti: string;
+      graffiti?: string;
       skipRandaoVerification?: boolean;
       builderBoostFactor?: UintBn64;
     } & ExtraProduceBlockOpts,
     {
       params: {slot: number};
       query: {
         randao_reveal: string;
-        graffiti: string;
+        graffiti?: string;
         skip_randao_verification?: string;
         fee_recipient?: string;
         builder_selection?: string;
@@ -359,9 +359,9 @@ export type Endpoints = {
     {
       slot: Slot;
       randaoReveal: BLSSignature;
-      graffiti: string;
+      graffiti?: string;
     },
-    {params: {slot: number}; query: {randao_reveal: string; graffiti: string}},
+    {params: {slot: number}; query: {randao_reveal: string; graffiti?: string}},
     BlindedBeaconBlock,
     VersionMeta
   >;

packages/api/src/utils/serdes.ts

@@ -77,7 +77,11 @@ export function fromValidatorIdsStr(ids?: string[]): (string | number)[] | undef
 
 const GRAFFITI_HEX_LENGTH = 66;
 
-export function toGraffitiHex(utf8: string): string {
+export function toGraffitiHex(utf8?: string): string | undefined {
+  if (utf8 === undefined) {
+    return undefined;
+  }
+
   const hex = toHexString(new TextEncoder().encode(utf8));
 
   if (hex.length > GRAFFITI_HEX_LENGTH) {
@@ -93,7 +97,10 @@ export function toGraffitiHex(utf8: string): string {
   return hex;
 }
 
-export function fromGraffitiHex(hex: string): string {
+export function fromGraffitiHex(hex?: string): string | undefined {
+  if (hex === undefined) {
+    return undefined;
+  }
   try {
     return new TextDecoder("utf8").decode(fromHexString(hex));
   } catch {

packages/beacon-node/src/api/impl/api.ts

@@ -21,6 +21,6 @@ export function getApi(opts: ApiOptions, modules: ApiModules): BeaconApiMethods
     lodestar: getLodestarApi(modules),
     node: getNodeApi(opts, modules),
     proof: getProofApi(opts, modules),
-    validator: getValidatorApi(modules),
+    validator: getValidatorApi(opts, modules),
   };
 }

packages/beacon-node/src/api/impl/validator/index.ts

@@ -53,7 +53,7 @@ import {validateApiAggregateAndProof} from "../../../chain/validation/index.js";
 import {ZERO_HASH} from "../../../constants/index.js";
 import {SyncState} from "../../../sync/index.js";
 import {isOptimisticBlock} from "../../../util/forkChoice.js";
-import {toGraffitiBuffer} from "../../../util/graffiti.js";
+import {getDefaultGraffiti, toGraffitiBuffer} from "../../../util/graffiti.js";
 import {ApiError, NodeIsSyncing, OnlySupportedByDVT} from "../errors.js";
 import {validateSyncCommitteeGossipContributionAndProof} from "../../../chain/validation/syncCommitteeContributionAndProof.js";
 import {CommitteeSubscription} from "../../../network/subnets/index.js";
@@ -63,6 +63,7 @@ import {getValidatorStatus} from "../beacon/state/utils.js";
 import {validateGossipFnRetryUnknownRoot} from "../../../network/processor/gossipHandlers.js";
 import {SCHEDULER_LOOKAHEAD_FACTOR} from "../../../chain/prepareNextSlot.js";
 import {ChainEvent, CheckpointHex, CommonBlockBody} from "../../../chain/index.js";
+import {ApiOptions} from "../../options.js";
 import {computeSubnetForCommitteesAtSlot, getPubkeysForIndices, selectBlockProductionSource} from "./utils.js";
 
 /**
@@ -110,14 +111,10 @@ type ProduceFullOrBlindedBlockOrContentsRes = {executionPayloadSource: ProducedB
  * Server implementation for handling validator duties.
  * See `@lodestar/validator/src/api` for the client implementation).
  */
-export function getValidatorApi({
-  chain,
-  config,
-  logger,
-  metrics,
-  network,
-  sync,
-}: ApiModules): ApplicationMethods<routes.validator.Endpoints> {
+export function getValidatorApi(
+  opts: ApiOptions,
+  {chain, config, logger, metrics, network, sync}: ApiModules
+): ApplicationMethods<routes.validator.Endpoints> {
   let genesisBlockRoot: Root | null = null;
 
   /**
@@ -348,7 +345,7 @@ export function getValidatorApi({
   async function produceBuilderBlindedBlock(
     slot: Slot,
     randaoReveal: BLSSignature,
-    graffiti: string,
+    graffiti?: string,
     // as of now fee recipient checks can not be performed because builder does not return bid recipient
     {
       skipHeadChecksAndUpdate,
@@ -406,7 +403,7 @@ export function getValidatorApi({
         slot,
         parentBlockRoot,
         randaoReveal,
-        graffiti: toGraffitiBuffer(graffiti || ""),
+        graffiti: toGraffitiBuffer(graffiti ?? getDefaultGraffiti(opts, chain.executionEngine.clientVersion)),
         commonBlockBody,
       });
 
@@ -432,7 +429,7 @@ export function getValidatorApi({
   async function produceEngineFullBlockOrContents(
     slot: Slot,
     randaoReveal: BLSSignature,
-    graffiti: string,
+    graffiti?: string,
     {
       feeRecipient,
       strictFeeRecipientCheck,
@@ -474,7 +471,7 @@ export function getValidatorApi({
         slot,
         parentBlockRoot,
         randaoReveal,
-        graffiti: toGraffitiBuffer(graffiti || ""),
+        graffiti: toGraffitiBuffer(graffiti ?? getDefaultGraffiti(opts, chain.executionEngine.clientVersion)),
         feeRecipient,
         commonBlockBody,
       });
@@ -522,7 +519,7 @@ export function getValidatorApi({
   async function produceEngineOrBuilderBlock(
     slot: Slot,
     randaoReveal: BLSSignature,
-    graffiti: string,
+    graffiti?: string,
     // TODO deneb: skip randao verification
     _skipRandaoVerification?: boolean,
     builderBoostFactor?: bigint,
@@ -585,7 +582,7 @@ export function getValidatorApi({
       slot,
       parentBlockRoot,
       randaoReveal,
-      graffiti: toGraffitiBuffer(graffiti || ""),
+      graffiti: toGraffitiBuffer(graffiti ?? getDefaultGraffiti(opts, chain.executionEngine.clientVersion)),
     });
     logger.debug("Produced common block body", loggerContext);
 

packages/beacon-node/src/api/options.ts

@@ -4,6 +4,7 @@ export type ApiOptions = {
   maxGindicesInProof?: number;
   rest: BeaconRestApiServerOpts;
   version?: string;
+  private?: boolean;
 };
 
 export const defaultApiOptions: ApiOptions = {

packages/beacon-node/src/execution/engine/disabled.ts

@@ -1,4 +1,4 @@
-import {ExecutionEngineState, IExecutionEngine, PayloadIdCache} from "./interface.js";
+import {ClientVersion, ExecutionEngineState, IExecutionEngine, PayloadIdCache} from "./interface.js";
 
 export class ExecutionEngineDisabled implements IExecutionEngine {
   state = ExecutionEngineState.OFFLINE;
@@ -28,4 +28,16 @@ export class ExecutionEngineDisabled implements IExecutionEngine {
   getPayloadBodiesByRange(): Promise<never> {
     throw Error("Execution engine disabled");
   }
+
+  getClientVersion(): Promise<ClientVersion[]> {
+    throw Error("Execution engine disabled");
+  }
+
+  getState(): ExecutionEngineState {
+    throw Error("Execution engine disabled");
+  }
+
+  getExecutionClientVersion(): ClientVersion {
+    throw Error("Execution engine disabled");
+  }
 }

packages/beacon-node/src/execution/engine/http.ts

@@ -12,6 +12,7 @@ import {Metrics} from "../../metrics/index.js";
 import {JobItemQueue} from "../../util/queue/index.js";
 import {EPOCHS_PER_BATCH} from "../../sync/constants.js";
 import {numToQuantity} from "../../eth1/provider/utils.js";
+import {getLodestarClientVersion} from "../../util/graffiti.js";
 import {
   ExecutionPayloadStatus,
   ExecutePayloadResponse,
@@ -21,6 +22,8 @@ import {
   BlobsBundle,
   VersionedHashes,
   ExecutionEngineState,
+  ClientVersion,
+  ClientCode,
 } from "./interface.js";
 import {PayloadIdCache} from "./payloadIdCache.js";
 import {
@@ -63,6 +66,14 @@ export type ExecutionEngineHttpOpts = {
    * A version string that will be set in `clv` field of jwt claims
    */
   jwtVersion?: string;
+  /**
+   * Lodestar version to be used for `ClientVersion`
+   */
+  version?: string;
+  /**
+   * Lodestar commit to be used for `ClientVersion`
+   */
+  commit?: string;
 };
 
 export const defaultExecutionEngineHttpOpts: ExecutionEngineHttpOpts = {
@@ -105,6 +116,9 @@ export class ExecutionEngineHttp implements IExecutionEngine {
   // It's safer to to avoid false positives and assume that the EL is syncing until we receive the first payload
   state: ExecutionEngineState = ExecutionEngineState.ONLINE;
 
+  // Cache EL client version from the latest getClientVersion call
+  clientVersion?: ClientVersion;
+
   readonly payloadIdCache = new PayloadIdCache();
   /**
    * A queue to serialize the fcUs and newPayloads calls:
@@ -126,7 +140,8 @@ export class ExecutionEngineHttp implements IExecutionEngine {
 
   constructor(
     private readonly rpc: IJsonRpcHttpClient,
-    {metrics, signal, logger}: ExecutionEngineModules
+    {metrics, signal, logger}: ExecutionEngineModules,
+    private readonly opts?: ExecutionEngineHttpOpts
   ) {
     this.rpcFetchQueue = new JobItemQueue<[EngineRequest], EngineResponse>(
       this.jobQueueProcessor,
@@ -142,6 +157,11 @@ export class ExecutionEngineHttp implements IExecutionEngine {
     this.rpc.emitter.on(JsonRpcHttpClientEvent.RESPONSE, () => {
       this.updateEngineState(getExecutionEngineState({targetState: ExecutionEngineState.ONLINE, oldState: this.state}));
     });
+
+    // Initial engine state is ONLINE. Need to explicitly call `getClientVersion` once on startup
+    this.getClientVersion(getLodestarClientVersion(this.opts)).catch((e) => {
+      this.logger.error("Unable to get client version", {caller: "ExecutionEngineHttp constructor"}, e);
+    });
   }
 
   /**
@@ -417,6 +437,35 @@ export class ExecutionEngineHttp implements IExecutionEngine {
     return response.map(deserializeExecutionPayloadBody);
   }
 
+  getState(): ExecutionEngineState {
+    return this.state;
+  }
+
+  async getClientVersion(clientVersion: ClientVersion): Promise<ClientVersion[]> {
+    const method = "engine_getClientVersionV1";
+
+    const response = await this.rpc.fetchWithRetries<
+      EngineApiRpcReturnTypes[typeof method],
+      EngineApiRpcParamTypes[typeof method]
+    >({method, params: [clientVersion]});
+
+    const clientVersions = response.map((cv) => {
+      const code = cv.code in ClientCode ? ClientCode[cv.code as keyof typeof ClientCode] : ClientCode.XX;
+      return {code, name: cv.name, version: cv.version, commit: cv.commit};
+    });
+
+    if (clientVersions.length > 0) {
+      this.clientVersion = clientVersions[0];
+      this.logger.info("Execution client version is updated", this.clientVersion);
+    }
+
+    return clientVersions;
+  }
+
+  get executionClientVersion(): ClientVersion | undefined {
+    return this.clientVersion;
+  }
+
   private updateEngineState(newState: ExecutionEngineState): void {
     const oldState = this.state;
 
@@ -425,6 +474,9 @@ export class ExecutionEngineHttp implements IExecutionEngine {
     switch (newState) {
       case ExecutionEngineState.ONLINE:
         this.logger.info("Execution client became online", {oldState, newState});
+        this.getClientVersion(getLodestarClientVersion(this.opts)).catch((e) => {
+          this.logger.error("Unable to get client version", {caller: "updateEngineState"}, e);
+        });
         break;
       case ExecutionEngineState.OFFLINE:
         this.logger.error("Execution client went offline", {oldState, newState});

packages/beacon-node/src/execution/engine/index.ts

@@ -40,7 +40,7 @@ export function getExecutionEngineHttp(
     jwtVersion: opts.jwtVersion,
   });
   modules.logger.info("Execution client", {urls: opts.urls.map(toSafePrintableUrl).toString()});
-  return new ExecutionEngineHttp(rpc, modules);
+  return new ExecutionEngineHttp(rpc, modules, opts);
 }
 
 export function initializeExecutionEngine(

packages/beacon-node/src/execution/engine/interface.ts

@@ -38,6 +38,26 @@ export enum ExecutionEngineState {
   AUTH_FAILED = "AUTH_FAILED",
 }
 
+/**
+ * Client code as defined in https://github.com/ethereum/execution-apis/blob/v1.0.0-beta.4/src/engine/identification.md#clientcode
+ * ClientCode.XX is dedicated to other clients which do not have their own code
+ */
+export enum ClientCode {
+  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",
+  XX = "unknown",
+}
+
 export type ExecutePayloadResponse =
   | {
       status: ExecutionPayloadStatus.SYNCING | ExecutionPayloadStatus.ACCEPTED;
@@ -80,6 +100,13 @@ export type BlobsBundle = {
   proofs: KZGProof[];
 };
 
+export type ClientVersion = {
+  code: ClientCode;
+  name: string;
+  version: string;
+  commit: string;
+};
+
 export type VersionedHashes = Uint8Array[];
 
 /**
@@ -91,6 +118,7 @@ export type VersionedHashes = Uint8Array[];
 export interface IExecutionEngine {
   readonly state: ExecutionEngineState;
 
+  readonly clientVersion?: ClientVersion;
   payloadIdCache: PayloadIdCache;
   /**
    * A state transition function which applies changes to the self.execution_state.
@@ -148,4 +176,8 @@ export interface IExecutionEngine {
   getPayloadBodiesByHash(blockHash: DATA[]): Promise<(ExecutionPayloadBody | null)[]>;
 
   getPayloadBodiesByRange(start: number, count: number): Promise<(ExecutionPayloadBody | null)[]>;
+
+  getClientVersion(clientVersion: ClientVersion): Promise<ClientVersion[]>;
+
+  getState(): ExecutionEngineState;
 }

packages/beacon-node/src/execution/engine/mock.ts

@@ -96,6 +96,7 @@ export class ExecutionEngineMockBackend implements JsonRpcBackend {
       engine_getPayloadV3: this.getPayload.bind(this),
       engine_getPayloadBodiesByHashV1: this.getPayloadBodiesByHash.bind(this),
       engine_getPayloadBodiesByRangeV1: this.getPayloadBodiesByRange.bind(this),
+      engine_getClientVersionV1: () => [],
     };
   }