@lodestar/beacon-node 1.50.0-dev.456b75a81e → 1.50.0-dev.4b00f7bf39

package/src/execution/engine/index.ts

@@ -1,17 +1,24 @@
-import {fromHex, toPrintableUrl} from "@lodestar/utils";
+import {LodestarError, fromHex, toPrintableUrl} from "@lodestar/utils";
+import {getLodestarClientVersion} from "../../util/metadata.js";
 import {ExecutionEngineDisabled} from "./disabled.js";
 import {
+  EngineApiMode,
   ExecutionEngineHttp,
   ExecutionEngineHttpOpts,
   ExecutionEngineModules,
   defaultExecutionEngineHttpOpts,
+  engineApiModes,
 } from "./http.js";
 import {IExecutionEngine} from "./interface.js";
 import {JsonRpcHttpClient} from "./jsonRpcHttpClient.js";
+import {JsonRpcEngineTransport} from "./jsonRpcTransport.js";
 import {ExecutionEngineMockBackend, ExecutionEngineMockOpts} from "./mock.js";
+import {EngineRestHttpClient} from "./restHttpClient.js";
+import {RestEngineTransport, formatClientVersionHeader} from "./restTransport.js";
 import {ExecutionEngineMockJsonRpcClient, JsonRpcBackend} from "./utils.js";
 
-export {ExecutionEngineHttp, ExecutionEngineDisabled, defaultExecutionEngineHttpOpts};
+export {ExecutionEngineHttp, ExecutionEngineDisabled, defaultExecutionEngineHttpOpts, engineApiModes};
+export type {EngineApiMode};
 
 export type ExecutionEngineOpts =
   | ({mode?: "http"} & ExecutionEngineHttpOpts)
@@ -24,23 +31,51 @@ export function getExecutionEngineFromBackend(
   modules: ExecutionEngineModules
 ): IExecutionEngine {
   const rpc = new ExecutionEngineMockJsonRpcClient(backend);
-  return new ExecutionEngineHttp(rpc, modules);
+  return new ExecutionEngineHttp({jsonRpc: new JsonRpcEngineTransport(rpc)}, modules);
 }
 
 export function getExecutionEngineHttp(
   opts: ExecutionEngineHttpOpts,
   modules: ExecutionEngineModules
 ): IExecutionEngine {
+  const jwtSecret = opts.jwtSecretHex ? fromHex(opts.jwtSecretHex) : undefined;
+  const metrics = modules.metrics?.executionEnginerHttpClient;
+  const engineApi = opts.engineApi ?? "auto";
+  if (engineApi === "ssz" && opts.urls.length !== 1) {
+    throw new LodestarError({code: "ENGINE_REST_REQUIRES_SINGLE_URL", count: opts.urls.length});
+  }
+  if (engineApi === "auto" && opts.urls.length > 1) {
+    modules.logger.debug("Using JSON-RPC for multiple execution URLs", {count: opts.urls.length});
+  }
+
   const rpc = new JsonRpcHttpClient(opts.urls, {
     ...opts,
     signal: modules.signal,
-    metrics: modules.metrics?.executionEnginerHttpClient,
-    jwtSecret: opts.jwtSecretHex ? fromHex(opts.jwtSecretHex) : undefined,
+    metrics,
+    jwtSecret,
     jwtId: opts.jwtId,
     jwtVersion: opts.jwtVersion,
   });
-  modules.logger.info("Execution client", {urls: opts.urls.map(toPrintableUrl).toString()});
-  return new ExecutionEngineHttp(rpc, modules, opts);
+
+  const rest =
+    engineApi === "json-rpc" || opts.urls.length !== 1
+      ? undefined
+      : new RestEngineTransport(
+          new EngineRestHttpClient(opts.urls, {
+            signal: modules.signal,
+            timeout: opts.timeout,
+            retries: opts.retries,
+            retryDelay: opts.retryDelay,
+            jwtSecret,
+            jwtId: opts.jwtId,
+            clientVersion: formatClientVersionHeader(getLodestarClientVersion(opts)),
+            metrics,
+          }),
+          metrics
+        );
+
+  modules.logger.info("Execution client", {urls: opts.urls.map(toPrintableUrl).toString(), engineApi});
+  return new ExecutionEngineHttp({jsonRpc: new JsonRpcEngineTransport(rpc), rest}, modules, opts);
 }
 
 export function initializeExecutionEngine(

package/src/execution/engine/interface.ts

@@ -13,7 +13,7 @@ import {BlobsBundle, ExecutionPayload, ExecutionRequests, Root, RootHex, Wei, ca
 import {BlobAndProof} from "@lodestar/types/deneb";
 import {BlobAndProofV2} from "@lodestar/types/fulu";
 import {PayloadId, PayloadIdCache, WithdrawalV1} from "./payloadIdCache.js";
-import {ExecutionPayloadBody, ExecutionPayloadBodyV2} from "./types.js";
+import {ExecutionPayloadBodyV2} from "./types.js";
 import {DATA} from "./utils.js";
 
 export {PayloadIdCache, type PayloadId, type WithdrawalV1};
@@ -170,13 +170,9 @@ export interface IExecutionEngine {
     shouldOverrideBuilder?: boolean;
   }>;
 
-  getPayloadBodiesByHash(fork: ForkName, blockHash: DATA[]): Promise<(ExecutionPayloadBody | null)[]>;
-
-  /** Amsterdam: like V1 but also returns the block access list (null if the EL no longer has it) */
+  /** Amsterdam: includes the block access list; REST returns null for bodies outside the Amsterdam era. */
   getPayloadBodiesByHashV2(blockHash: DATA[]): Promise<(ExecutionPayloadBodyV2 | null)[]>;
 
-  getPayloadBodiesByRange(fork: ForkName, start: number, count: number): Promise<(ExecutionPayloadBody | null)[]>;
-
   getBlobs(
     fork: ForkPostFulu,
     versionedHashes: VersionedHashes,

package/src/execution/engine/jsonRpcHttpClient.ts

@@ -284,7 +284,12 @@ export class JsonRpcHttpClient implements IJsonRpcHttpClient {
       });
 
       const streamTimer = this.metrics?.streamTime.startTimer({routeId});
-      const bodyText = await res.text();
+      let bodyText: string;
+      try {
+        bodyText = await res.text();
+      } finally {
+        streamTimer?.();
+      }
       this.metrics?.responseBytes.inc({routeId}, bodyText.length);
       if (!res.ok) {
         // Infura errors:
@@ -292,10 +297,12 @@ export class JsonRpcHttpClient implements IJsonRpcHttpClient {
         throw new HttpRpcError(res.status, `${res.statusText}: ${bodyText.slice(0, maxStringLengthToPrint)}`);
       }
 
-      const bodyJson = parseJson<R>(bodyText);
-      streamTimer?.();
-
-      return bodyJson;
+      const parseTimer = this.metrics?.responseParseTime.startTimer({routeId, encoding: "json"});
+      try {
+        return parseJson<R>(bodyText);
+      } finally {
+        parseTimer?.();
+      }
     } catch (e) {
       this.metrics?.requestErrors.inc({routeId});
       if (controller.signal.aborted) {

package/src/execution/engine/jsonRpcTransport.ts

@@ -0,0 +1,247 @@
+import {ForkName, ForkSeq} from "@lodestar/params";
+import {ExecutionPayload, ExecutionRequests, Root, RootHex} from "@lodestar/types";
+import {BlobAndProof} from "@lodestar/types/deneb";
+import {BlobAndProofV2} from "@lodestar/types/fulu";
+import {strip0xPrefix} from "@lodestar/utils";
+import {ClientCode, ClientVersion, PayloadAttributes, PayloadId, VersionedHashes} from "./interface.js";
+import {IJsonRpcHttpClient, JsonRpcHttpClientEventEmitter, ReqOpts} from "./jsonRpcHttpClient.js";
+import {ForkchoiceUpdatedResult, GetPayloadResult, IEngineTransport, PayloadStatusResult} from "./transport.js";
+import {
+  BLOB_AND_PROOF_V2_RPC_BYTES,
+  EngineApiRpcParamTypes,
+  EngineApiRpcReturnTypes,
+  ExecutionPayloadBodyV2,
+  assertReqSizeLimit,
+  deserializeBlobAndProofs,
+  deserializeBlobAndProofsV2,
+  deserializeBlobAndProofsV2IntoBytes,
+  deserializeExecutionPayloadBodyV2,
+  parseExecutionPayload,
+  serializeBeaconBlockRoot,
+  serializeExecutionPayload,
+  serializeExecutionRequests,
+  serializePayloadAttributes,
+  serializeVersionedHashes,
+} from "./types.js";
+import {bytesToData} from "./utils.js";
+
+/**
+ * Maximum number of version hashes that can be sent in a getBlobs request
+ * Clients must support at least 128 versionedHashes, so we avoid sending more
+ * https://github.com/ethereum/execution-apis/blob/main/src/engine/cancun.md#specification-3
+ */
+const MAX_VERSIONED_HASHES = 128;
+
+// Define static options once to prevent extra allocations
+const notifyNewPayloadOpts: ReqOpts = {routeId: "notifyNewPayload"};
+const forkchoiceUpdatedOpts: ReqOpts = {routeId: "forkchoiceUpdated"};
+const getPayloadOpts: ReqOpts = {routeId: "getPayload"};
+const getPayloadBodiesByHashOpts: ReqOpts = {routeId: "getPayloadBodiesByHash"};
+const getBlobsV1Opts: ReqOpts = {routeId: "getBlobsV1"};
+const getBlobsV2Opts: ReqOpts = {routeId: "getBlobsV2"};
+const getClientVersionOpts: ReqOpts = {routeId: "getClientVersion"};
+
+/**
+ * Legacy `engine_*` JSON-RPC methods
+ * https://github.com/ethereum/execution-apis/tree/main/src/engine
+ */
+export class JsonRpcEngineTransport implements IEngineTransport {
+  constructor(private readonly rpc: IJsonRpcHttpClient) {}
+
+  get emitter(): JsonRpcHttpClientEventEmitter {
+    return this.rpc.emitter;
+  }
+
+  async newPayload(
+    fork: ForkName,
+    executionPayload: ExecutionPayload,
+    versionedHashes?: VersionedHashes,
+    parentBeaconBlockRoot?: Root,
+    executionRequests?: ExecutionRequests
+  ): Promise<PayloadStatusResult> {
+    const serializedExecutionPayload = serializeExecutionPayload(fork, executionPayload);
+
+    if (ForkSeq[fork] >= ForkSeq.deneb) {
+      if (versionedHashes === undefined) {
+        throw Error(`versionedHashes required in notifyNewPayload for fork=${fork}`);
+      }
+      if (parentBeaconBlockRoot === undefined) {
+        throw Error(`parentBlockRoot required in notifyNewPayload for fork=${fork}`);
+      }
+
+      const serializedVersionedHashes = serializeVersionedHashes(versionedHashes);
+      const serializedParentBeaconBlockRoot = serializeBeaconBlockRoot(parentBeaconBlockRoot);
+
+      if (ForkSeq[fork] >= ForkSeq.electra) {
+        if (executionRequests === undefined) {
+          throw Error(`executionRequests required in notifyNewPayload for fork=${fork}`);
+        }
+        const method = ForkSeq[fork] >= ForkSeq.gloas ? "engine_newPayloadV5" : "engine_newPayloadV4";
+        return this.rpc.fetchWithRetries<EngineApiRpcReturnTypes[typeof method], EngineApiRpcParamTypes[typeof method]>(
+          {
+            method,
+            params: [
+              serializedExecutionPayload,
+              serializedVersionedHashes,
+              serializedParentBeaconBlockRoot,
+              serializeExecutionRequests(fork, executionRequests),
+            ],
+          },
+          notifyNewPayloadOpts
+        );
+      }
+
+      const method = "engine_newPayloadV3";
+      return this.rpc.fetchWithRetries<EngineApiRpcReturnTypes[typeof method], EngineApiRpcParamTypes[typeof method]>(
+        {method, params: [serializedExecutionPayload, serializedVersionedHashes, serializedParentBeaconBlockRoot]},
+        notifyNewPayloadOpts
+      );
+    }
+
+    const method = ForkSeq[fork] >= ForkSeq.capella ? "engine_newPayloadV2" : "engine_newPayloadV1";
+    return this.rpc.fetchWithRetries<EngineApiRpcReturnTypes[typeof method], EngineApiRpcParamTypes[typeof method]>(
+      {method, params: [serializedExecutionPayload]},
+      notifyNewPayloadOpts
+    );
+  }
+
+  async forkchoiceUpdated(
+    fork: ForkName,
+    headBlockHash: RootHex,
+    safeBlockHash: RootHex,
+    finalizedBlockHash: RootHex,
+    payloadAttributes?: PayloadAttributes
+  ): Promise<ForkchoiceUpdatedResult> {
+    const method =
+      ForkSeq[fork] >= ForkSeq.gloas
+        ? "engine_forkchoiceUpdatedV4"
+        : ForkSeq[fork] >= ForkSeq.deneb
+          ? "engine_forkchoiceUpdatedV3"
+          : ForkSeq[fork] >= ForkSeq.capella
+            ? "engine_forkchoiceUpdatedV2"
+            : "engine_forkchoiceUpdatedV1";
+    const payloadAttributesRpc = payloadAttributes ? serializePayloadAttributes(payloadAttributes) : undefined;
+    // If we are just fcUing and not asking execution for payload, retry is not required
+    // and we can move on, as the next fcU will be issued soon on the new slot
+    const fcUReqOpts = payloadAttributes !== undefined ? forkchoiceUpdatedOpts : {...forkchoiceUpdatedOpts, retries: 0};
+
+    const {payloadStatus, payloadId} = await this.rpc.fetchWithRetries<
+      EngineApiRpcReturnTypes[typeof method],
+      EngineApiRpcParamTypes[typeof method]
+    >({method, params: [{headBlockHash, safeBlockHash, finalizedBlockHash}, payloadAttributesRpc]}, fcUReqOpts);
+
+    return {payloadStatus, payloadId: payloadId && payloadId !== "0x" ? payloadId : null};
+  }
+
+  async getPayload(fork: ForkName, payloadId: PayloadId): Promise<GetPayloadResult> {
+    let method: keyof EngineApiRpcReturnTypes;
+    switch (fork) {
+      case ForkName.phase0:
+      case ForkName.altair:
+      case ForkName.bellatrix:
+        method = "engine_getPayloadV1";
+        break;
+      case ForkName.capella:
+        method = "engine_getPayloadV2";
+        break;
+      case ForkName.deneb:
+        method = "engine_getPayloadV3";
+        break;
+      case ForkName.electra:
+        method = "engine_getPayloadV4";
+        break;
+      case ForkName.fulu:
+        method = "engine_getPayloadV5";
+        break;
+      default:
+        method = "engine_getPayloadV6";
+        break;
+    }
+    const payloadResponse = await this.rpc.fetchWithRetries<
+      EngineApiRpcReturnTypes[typeof method],
+      EngineApiRpcParamTypes[typeof method]
+    >({method, params: [payloadId]}, getPayloadOpts);
+    return parseExecutionPayload(fork, payloadResponse);
+  }
+
+  async getPayloadBodiesByHashV2(blockHashes: RootHex[]): Promise<(ExecutionPayloadBodyV2 | null)[]> {
+    const method = "engine_getPayloadBodiesByHashV2";
+    assertReqSizeLimit(blockHashes.length, 32);
+    const response = await this.rpc.fetchWithRetries<
+      EngineApiRpcReturnTypes[typeof method],
+      EngineApiRpcParamTypes[typeof method]
+    >({method, params: [blockHashes]}, getPayloadBodiesByHashOpts);
+    return response.map(deserializeExecutionPayloadBodyV2);
+  }
+
+  async getBlobsV1(versionedHashes: VersionedHashes): Promise<(BlobAndProof | null)[]> {
+    assertReqSizeLimit(versionedHashes.length, MAX_VERSIONED_HASHES);
+    const versionedHashesHex = versionedHashes.map(bytesToData);
+    const response = await this.rpc.fetchWithRetries<
+      EngineApiRpcReturnTypes["engine_getBlobsV1"],
+      EngineApiRpcParamTypes["engine_getBlobsV1"]
+    >({method: "engine_getBlobsV1", params: [versionedHashesHex]}, getBlobsV1Opts);
+
+    if (response.length !== versionedHashesHex.length) {
+      throw Error(
+        `Invalid engine_getBlobsV1 response length=${response.length} versionedHashes=${versionedHashesHex.length}`
+      );
+    }
+
+    return response.map(deserializeBlobAndProofs);
+  }
+
+  async getBlobsV2(versionedHashes: VersionedHashes, buffers?: Uint8Array[]): Promise<BlobAndProofV2[] | null> {
+    assertReqSizeLimit(versionedHashes.length, MAX_VERSIONED_HASHES);
+    const versionedHashesHex = versionedHashes.map(bytesToData);
+    if (buffers) {
+      // Callers preallocate one buffer per max blobs of the epoch, only the first entries are used
+      if (buffers.length < versionedHashesHex.length) {
+        throw Error(`Not enough buffers length=${buffers.length} versionedHashes=${versionedHashesHex.length}`);
+      }
+
+      for (const [i, buffer] of buffers.entries()) {
+        if (buffer.length !== BLOB_AND_PROOF_V2_RPC_BYTES) {
+          throw Error(`Invalid buffer[${i}] length=${buffer.length} expected=${BLOB_AND_PROOF_V2_RPC_BYTES}`);
+        }
+      }
+    }
+
+    const response = await this.rpc.fetchWithRetries<
+      EngineApiRpcReturnTypes["engine_getBlobsV2"],
+      EngineApiRpcParamTypes["engine_getBlobsV2"]
+    >({method: "engine_getBlobsV2", params: [versionedHashesHex]}, getBlobsV2Opts);
+
+    // engine_getBlobsV2 does not return partial responses. It returns null if any blob is not found
+    if (response == null) {
+      return null;
+    }
+
+    if (response.length !== versionedHashesHex.length) {
+      throw Error(
+        `Invalid engine_getBlobsV2 response length=${response.length} versionedHashes=${versionedHashesHex.length}`
+      );
+    }
+
+    if (buffers) {
+      // getBlobsV2() is designed to called once per slot so we expect to have buffers
+      return response.map((data, i) => deserializeBlobAndProofsV2IntoBytes(data, buffers[i]));
+    }
+
+    return response.map(deserializeBlobAndProofsV2);
+  }
+
+  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, commit: `0x${clientVersion.commit}`}]}, getClientVersionOpts);
+
+    return 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: strip0xPrefix(cv.commit)};
+    });
+  }
+}

package/src/execution/engine/mock.ts

@@ -22,7 +22,6 @@ import {
   BlobsBundleRpc,
   EngineApiRpcParamTypes,
   EngineApiRpcReturnTypes,
-  ExecutionPayloadBodyRpc,
   ExecutionPayloadBodyV2Rpc,
   ExecutionPayloadRpc,
   ExecutionRequestsRpc,
@@ -50,7 +49,7 @@ type ExecutionBlock = {
   blockHash: RootHex;
   timestamp: number;
   blockNumber: number;
-  /** Bodies as received via newPayload, served back by engine_getPayloadBodiesByHash{V1,V2} */
+  /** Bodies as received via newPayload, served back by engine_getPayloadBodiesByHashV2 */
   body: ExecutionPayloadBodyV2Rpc;
 };
 
@@ -148,23 +147,13 @@ export class ExecutionEngineMockBackend implements JsonRpcBackend {
       engine_getPayloadV4: this.getPayloadV5.bind(this),
       engine_getPayloadV5: this.getPayloadV5.bind(this),
       engine_getPayloadV6: this.getPayloadV5.bind(this),
-      engine_getPayloadBodiesByHashV1: this.getPayloadBodiesByHash.bind(this),
       engine_getPayloadBodiesByHashV2: this.getPayloadBodiesByHashV2.bind(this),
-      engine_getPayloadBodiesByRangeV1: this.getPayloadBodiesByRange.bind(this),
       engine_getClientVersionV1: this.getClientVersionV1.bind(this),
       engine_getBlobsV1: this.getBlobs.bind(this),
       engine_getBlobsV2: this.getBlobsV2.bind(this),
     };
   }
 
-  private getPayloadBodiesByHash(
-    blockHashes: EngineApiRpcParamTypes["engine_getPayloadBodiesByHashV1"][0]
-  ): EngineApiRpcReturnTypes["engine_getPayloadBodiesByHashV1"] {
-    return this.getPayloadBodiesByHashV2(blockHashes).map((body) =>
-      body ? {transactions: body.transactions, withdrawals: body.withdrawals} : null
-    );
-  }
-
   private getPayloadBodiesByHashV2(
     blockHashes: EngineApiRpcParamTypes["engine_getPayloadBodiesByHashV2"][0]
   ): EngineApiRpcReturnTypes["engine_getPayloadBodiesByHashV2"] {
@@ -172,13 +161,6 @@ export class ExecutionEngineMockBackend implements JsonRpcBackend {
     return blockHashes.map((hash) => this.validBlocks.get(hash)?.body ?? null);
   }
 
-  private getPayloadBodiesByRange(
-    _start: EngineApiRpcParamTypes["engine_getPayloadBodiesByRangeV1"][0],
-    _count: EngineApiRpcParamTypes["engine_getPayloadBodiesByRangeV1"][1]
-  ): EngineApiRpcReturnTypes["engine_getPayloadBodiesByRangeV1"] {
-    return [] as ExecutionPayloadBodyRpc[];
-  }
-
   /**
    * Mock manipulator to add predefined responses before execution engine client calls
    */