@lodestar/beacon-node/lib/execution/engine/http.d.ts

A Typescript implementation of the beacon chain

import { Logger } from "@lodestar/logger";
import { ForkName } from "@lodestar/params";
import { ExecutionPayload, ExecutionRequests, Root, RootHex, Wei } from "@lodestar/types";
import { BlobAndProof } from "@lodestar/types/deneb";
import { IJsonRpcHttpClient } from "../../eth1/provider/jsonRpcHttpClient.js";
import { Metrics } from "../../metrics/index.js";
import { BlobsBundle, ClientVersion, ExecutePayloadResponse, ExecutionEngineState, IExecutionEngine, PayloadAttributes, PayloadId, VersionedHashes } from "./interface.js";
import { PayloadIdCache } from "./payloadIdCache.js";
import { ExecutionPayloadBody } from "./types.js";
export type ExecutionEngineModules = {
    signal: AbortSignal;
    metrics?: Metrics | null;
    logger: Logger;
};
export type ExecutionEngineHttpOpts = {
    urls: string[];
    retries: number;
    retryDelay: number;
    timeout?: number;
    /**
     * 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
     * request, as the EL auth specs mandate the fresh of the token (iat) to be checked within
     * +-5 seconds interval.
     */
    jwtSecretHex?: string;
    /**
     * An identifier string passed as CLI arg that will be set in `id` field of jwt claims
     */
    jwtId?: string;
    /**
     * 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 declare const defaultExecutionEngineHttpOpts: ExecutionEngineHttpOpts;
/**
 * 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
 *
 * 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
 */
export declare class ExecutionEngineHttp implements IExecutionEngine {
    private readonly rpc;
    private readonly opts?;
    private logger;
    private lastGetBlobsErrorTime;
    state: ExecutionEngineState;
    /** Cached EL client version from the latest getClientVersion call */
    clientVersion?: ClientVersion | null;
    readonly payloadIdCache: PayloadIdCache;
    /**
     * A queue to serialize the fcUs and newPayloads calls:
     *
     * While syncing, lodestar has a batch processing module which calls new payloads in batch followed by fcUs.
     * Even though we await for responses to new payloads serially, we just trigger fcUs consecutively. This
     * may lead to the EL receiving the fcUs out of the order and may break the EL's backfill/beacon sync. Since
     * 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);
    /**
     * `engine_newPayloadV1`
     * From: https://github.com/ethereum/execution-apis/blob/v1.0.0-alpha.6/src/engine/specification.md#engine_newpayloadv1
     *
     * Client software MUST respond to this method call in the following way:
     *
     *   1. {status: INVALID_BLOCK_HASH, latestValidHash: null, validationError:
     *      errorMessage | null} if the blockHash validation has failed
     *
     *   2. {status: INVALID_TERMINAL_BLOCK, latestValidHash: null, validationError:
     *      errorMessage | null} if terminal block conditions are not satisfied
     *
     *   3. {status: SYNCING, latestValidHash: null, validationError: null} if the payload
     *      extends the canonical chain and requisite data for its validation is missing
     *      with the payload status obtained from the Payload validation process if the payload
     *      has been fully validated while processing the call
     *
     *   4. {status: ACCEPTED, latestValidHash: null, validationError: null} if the
     *      following conditions are met:
     *        i) the blockHash of the payload is valid
     *        ii) the payload doesn't extend the canonical chain
     *        iii) the payload hasn't been fully validated.
     *
     * If any of the above fails due to errors unrelated to the normal processing flow of the method, client software MUST respond with an error object.
     */
    notifyNewPayload(fork: ForkName, executionPayload: ExecutionPayload, versionedHashes?: VersionedHashes, parentBlockRoot?: Root, executionRequests?: ExecutionRequests): Promise<ExecutePayloadResponse>;
    /**
     * `engine_forkchoiceUpdatedV1`
     * From: https://github.com/ethereum/execution-apis/blob/v1.0.0-alpha.6/src/engine/specification.md#engine_forkchoiceupdatedv1
     *
     * Client software MUST respond to this method call in the following way:
     *
     *   1. {payloadStatus: {status: SYNCING, latestValidHash: null, validationError: null}
     *      , payloadId: null}
     *      if forkchoiceState.headBlockHash references an unknown payload or a payload that
     *      can't be validated because requisite data for the validation is missing
     *
     *   2. {payloadStatus: {status: INVALID, latestValidHash: null, validationError:
     *      errorMessage | null}, payloadId: null}
     *      obtained from the Payload validation process if the payload is deemed INVALID
     *
     *   3. {payloadStatus: {status: INVALID_TERMINAL_BLOCK, latestValidHash: null,
     *      validationError: errorMessage | null}, payloadId: null}
     *      either obtained from the Payload validation process or as a result of validating a
     *      PoW block referenced by forkchoiceState.headBlockHash
     *
     *   4. {payloadStatus: {status: VALID, latestValidHash: forkchoiceState.headBlockHash,
     *      validationError: null}, payloadId: null}
     *      if the payload is deemed VALID and a build process hasn't been started
     *
     *   5. {payloadStatus: {status: VALID, latestValidHash: forkchoiceState.headBlockHash,
     *      validationError: null}, payloadId: buildProcessId}
     *      if the payload is deemed VALID and the build process has begun.
     *
     * If any of the above fails due to errors unrelated to the normal processing flow of the method, client software MUST respond with an error object.
     */
    notifyForkchoiceUpdate(fork: ForkName, headBlockHash: RootHex, safeBlockHash: RootHex, finalizedBlockHash: RootHex, payloadAttributes?: PayloadAttributes): Promise<PayloadId | null>;
    /**
     * `engine_getPayloadV1`
     *
     * 1. Given the payloadId client software MUST respond with the most recent version of the payload that is available in the corresponding building process at the time of receiving the call.
     * 2. The call MUST be responded with 5: Unavailable payload error if the building process identified by the payloadId doesn't exist.
     * 3. Client software MAY stop the corresponding building process after serving this call.
     */
    getPayload(fork: ForkName, payloadId: PayloadId): Promise<{
        executionPayload: ExecutionPayload;
        executionPayloadValue: Wei;
        blobsBundle?: BlobsBundle;
        executionRequests?: ExecutionRequests;
        shouldOverrideBuilder?: boolean;
    }>;
    prunePayloadIdCache(): Promise<void>;
    getPayloadBodiesByHash(_fork: ForkName, blockHashes: RootHex[]): Promise<(ExecutionPayloadBody | null)[]>;
    getPayloadBodiesByRange(_fork: ForkName, startBlockNumber: number, blockCount: number): Promise<(ExecutionPayloadBody | null)[]>;
    getBlobs(_fork: ForkName, versionedHashes: VersionedHashes): Promise<(BlobAndProof | null)[]>;
    private getClientVersion;
    private updateEngineState;
}
//# sourceMappingURL=http.d.ts.map