@lodestar/beacon-node 1.50.0-dev.023ad6c012 → 1.50.0-dev.03c05fa09a

package/lib/execution/engine/http.d.ts

@@ -5,19 +5,29 @@ import { BlobAndProof } from "@lodestar/types/deneb";
 import { BlobAndProofV2 } from "@lodestar/types/fulu";
 import { Metrics } from "../../metrics/index.js";
 import { ClientVersion, ExecutePayloadResponse, ExecutionEngineState, IExecutionEngine, PayloadAttributes, PayloadId, VersionedHashes } from "./interface.js";
-import { IJsonRpcHttpClient } from "./jsonRpcHttpClient.js";
 import { PayloadIdCache } from "./payloadIdCache.js";
-import { ExecutionPayloadBody, ExecutionPayloadBodyV2 } from "./types.js";
+import { RestEngineTransport } from "./restTransport.js";
+import { IEngineTransport } from "./transport.js";
+import { ExecutionPayloadBodyV2 } from "./types.js";
 export type ExecutionEngineModules = {
     signal: AbortSignal;
     metrics?: Metrics | null;
     logger: Logger;
 };
+/**
+ * Engine API transport selection
+ * - `auto`: negotiate REST with one execution URL; use JSON-RPC for multiple URLs or unadvertised features
+ * - `ssz`: always use the REST API with SSZ encoding
+ * - `json-rpc`: always use the legacy JSON-RPC API
+ */
+export type EngineApiMode = "auto" | "ssz" | "json-rpc";
+export declare const engineApiModes: EngineApiMode[];
 export type ExecutionEngineHttpOpts = {
     urls: string[];
     retries: number;
     retryDelay: number;
     timeout?: number;
+    engineApi?: EngineApiMode;
     /**
      * 256 bit jwt secret in hex format without the leading 0x. If provided, the execution engine
      * rpc requests will be bundled by an authorization header having a fresh jwt token on each
@@ -43,17 +53,21 @@ export type ExecutionEngineHttpOpts = {
     commit?: string;
 };
 export declare const defaultExecutionEngineHttpOpts: ExecutionEngineHttpOpts;
+export type ExecutionEngineTransports = {
+    jsonRpc: IEngineTransport;
+    rest?: RestEngineTransport;
+};
 /**
- * based on Ethereum JSON-RPC API and inherits the following properties of this standard:
- * - Supported communication protocols (HTTP and WebSocket)
- * - Message format and encoding notation
- * - Error codes improvement proposal
+ * Drives the execution client over the engine API, either the legacy `engine_*` JSON-RPC methods
+ * or the REST API with SSZ encoded bodies.
+ * https://github.com/ethereum/execution-apis/tree/main/src/engine
  *
- * Client software MUST expose Engine API at a port independent from JSON-RPC API. The default port for the Engine API is 8550 for HTTP and 8551 for WebSocket.
- * https://github.com/ethereum/execution-apis/blob/v1.0.0-alpha.1/src/engine/interop/specification.md
+ * In `auto` mode a capabilities response from a server without the REST API, a 4xx other than
+ * 401/403, selects JSON-RPC until the EL reconnects. Transient discovery failures use JSON-RPC while
+ * awaiting another probe; authentication failures fail visibly, malformed capabilities fall back to
+ * JSON-RPC with a warning. Forks and blob revisions the EL does not advertise also use JSON-RPC.
  */
 export declare class ExecutionEngineHttp implements IExecutionEngine {
-    private readonly rpc;
     private readonly opts?;
     private logger;
     private metrics;
@@ -70,9 +84,15 @@ export declare class ExecutionEngineHttp implements IExecutionEngine {
      * the order of new payloads and fcUs is pretty important to EL, this queue will serialize the calls in the
      * order with which we make them.
      */
-    private readonly rpcFetchQueue;
-    private jobQueueProcessor;
-    constructor(rpc: IJsonRpcHttpClient, { metrics, signal, logger }: ExecutionEngineModules, opts?: ExecutionEngineHttpOpts | undefined);
+    private readonly queue;
+    private readonly jsonRpc;
+    private readonly rest;
+    private readonly engineApi;
+    private restSupport;
+    private restProbe;
+    private lastRestProbeMs;
+    private readonly loggedRestFallbacks;
+    constructor({ jsonRpc, rest }: ExecutionEngineTransports, { metrics, signal, logger }: ExecutionEngineModules, opts?: ExecutionEngineHttpOpts | undefined);
     /**
      * `engine_newPayloadV1`
      * From: https://github.com/ethereum/execution-apis/blob/v1.0.0-alpha.6/src/engine/specification.md#engine_newpayloadv1
@@ -137,13 +157,23 @@ export declare class ExecutionEngineHttp implements IExecutionEngine {
         shouldOverrideBuilder?: boolean;
     }>;
     prunePayloadIdCache(): Promise<void>;
-    getPayloadBodiesByHash(_fork: ForkName, blockHashes: RootHex[]): Promise<(ExecutionPayloadBody | null)[]>;
     getPayloadBodiesByHashV2(blockHashes: RootHex[]): Promise<(ExecutionPayloadBodyV2 | null)[]>;
-    getPayloadBodiesByRange(_fork: ForkName, startBlockNumber: number, blockCount: number): Promise<(ExecutionPayloadBody | null)[]>;
     getBlobs(fork: ForkPostFulu, versionedHashes: VersionedHashes, buffers?: Uint8Array[]): Promise<BlobAndProofV2[] | null>;
     getBlobs(fork: ForkPreFulu, versionedHashes: VersionedHashes, buffers?: Uint8Array[]): Promise<(BlobAndProof | null)[]>;
-    private getBlobsV1;
-    private getBlobsV2;
+    private enqueue;
+    /**
+     * Run a call on the selected transport. An execution client that advertises a fork in its
+     * capabilities but rejects it with `unsupported-fork` is not spec compliant, keep the node
+     * functional by serving that fork over JSON-RPC from then on.
+     */
+    private withTransport;
+    private disableRestForFork;
+    /**
+     * Pick the transport for a call. Fork-scoped calls only go over REST if the execution client
+     * advertises that fork, blob requests only if it serves the needed `/blobs/vN` revision.
+     */
+    private getTransport;
+    private probeRestSupport;
     private getClientVersion;
     private updateEngineState;
 }

package/lib/execution/engine/http.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../../src/execution/engine/http.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../../src/execution/engine/http.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,MAAM,EAAC,MAAM,kBAAkB,CAAC;AACxC,OAAO,EACL,QAAQ,EACR,YAAY,EACZ,WAAW,EAKZ,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAC,WAAW,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,EAAC,MAAM,iBAAiB,CAAC;AACrG,OAAO,EAAC,YAAY,EAAC,MAAM,uBAAuB,CAAC;AACnD,OAAO,EAAC,cAAc,EAAC,MAAM,sBAAsB,CAAC;AAEpD,OAAO,EAAC,OAAO,EAAC,MAAM,wBAAwB,CAAC;AAK/C,OAAO,EACL,aAAa,EACb,sBAAsB,EACtB,oBAAoB,EAEpB,gBAAgB,EAChB,iBAAiB,EACjB,SAAS,EACT,eAAe,EAChB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAAC,cAAc,EAAC,MAAM,qBAAqB,CAAC;AAEnD,OAAO,EAAqB,mBAAmB,EAAC,MAAM,oBAAoB,CAAC;AAE3E,OAAO,EAAC,gBAAgB,EAAsB,MAAM,gBAAgB,CAAC;AACrE,OAAO,EAAC,sBAAsB,EAA6B,MAAM,YAAY,CAAC;AAG9E,MAAM,MAAM,sBAAsB,GAAG;IACnC,MAAM,EAAE,WAAW,CAAC;IACpB,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,KAAK,GAAG,UAAU,CAAC;AACxD,eAAO,MAAM,cAAc,EAAE,aAAa,EAAgC,CAAC;AAE3E,MAAM,MAAM,uBAAuB,GAAG;IACpC,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,eAAO,MAAM,8BAA8B,EAAE,uBAW5C,CAAC;AAEF,MAAM,MAAM,yBAAyB,GAAG;IACtC,OAAO,EAAE,gBAAgB,CAAC;IAC1B,IAAI,CAAC,EAAE,mBAAmB,CAAC;CAC5B,CAAC;AAgBF;;;;;;;;;GASG;AACH,qBAAa,mBAAoB,YAAW,gBAAgB;IAmCxD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC;IAlCxB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,OAAO,CAAiB;IAKhC,KAAK,EAAE,oBAAoB,CAA+B;IAE1D,qEAAqE;IACrE,aAAa,CAAC,EAAE,aAAa,GAAG,IAAI,CAAC;IAErC,QAAQ,CAAC,cAAc,iBAAwB;IAC/C;;;;;;;;OAQG;IACH,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAkD;IAExE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAmB;IAC3C,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA6B;IAClD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAgB;IAC1C,OAAO,CAAC,WAAW,CAAmC;IACtD,OAAO,CAAC,SAAS,CAAqC;IACtD,OAAO,CAAC,eAAe,CAA4B;IACnD,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAqC;IAEzE,YACE,EAAC,OAAO,EAAE,IAAI,EAAC,EAAE,yBAAyB,EAC1C,EAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAC,EAAE,sBAAsB,EAChC,IAAI,CAAC,EAAE,uBAAuB,YAAA,EAoChD;IAED;;;;;;;;;;;;;;;;;;;;;OAqBG;IACG,gBAAgB,CACpB,IAAI,EAAE,QAAQ,EACd,gBAAgB,EAAE,gBAAgB,EAClC,eAAe,CAAC,EAAE,eAAe,EACjC,eAAe,CAAC,EAAE,IAAI,EACtB,iBAAiB,CAAC,EAAE,iBAAiB,GACpC,OAAO,CAAC,sBAAsB,CAAC,CAoEjC;IAED;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACG,sBAAsB,CAC1B,IAAI,EAAE,QAAQ,EACd,aAAa,EAAE,OAAO,EACtB,aAAa,EAAE,OAAO,EACtB,kBAAkB,EAAE,OAAO,EAC3B,iBAAiB,CAAC,EAAE,iBAAiB,GACpC,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CA4C3B;IAED;;;;;;OAMG;IACG,UAAU,CACd,IAAI,EAAE,QAAQ,EACd,SAAS,EAAE,SAAS,GACnB,OAAO,CAAC;QACT,gBAAgB,EAAE,gBAAgB,CAAC;QACnC,qBAAqB,EAAE,GAAG,CAAC;QAC3B,WAAW,CAAC,EAAE,WAAW,CAAC;QAC1B,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;QACtC,qBAAqB,CAAC,EAAE,OAAO,CAAC;KACjC,CAAC,CAED;IAEK,mBAAmB,IAAI,OAAO,CAAC,IAAI,CAAC,CAEzC;IAEK,wBAAwB,CAAC,WAAW,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,CAAC,sBAAsB,GAAG,IAAI,CAAC,EAAE,CAAC,CAIjG;IAEK,QAAQ,CACZ,IAAI,EAAE,YAAY,EAClB,eAAe,EAAE,eAAe,EAChC,OAAO,CAAC,EAAE,UAAU,EAAE,GACrB,OAAO,CAAC,cAAc,EAAE,GAAG,IAAI,CAAC,CAAC;IAC9B,QAAQ,CACZ,IAAI,EAAE,WAAW,EACjB,eAAe,EAAE,eAAe,EAChC,OAAO,CAAC,EAAE,UAAU,EAAE,GACrB,OAAO,CAAC,CAAC,YAAY,GAAG,IAAI,CAAC,EAAE,CAAC,CAAC;IAYpC,OAAO,CAAC,OAAO;IAIf;;;;OAIG;YACW,aAAa;IAsB3B,OAAO,CAAC,kBAAkB;IAiB1B;;;OAGG;YACW,YAAY;IAwC1B,OAAO,CAAC,gBAAgB;YA4DV,gBAAgB;IAe9B,OAAO,CAAC,iBAAiB;CAwC1B"}