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

A Typescript implementation of the beacon chain

import { routes } from "@lodestar/api";
import { CONSOLIDATION_REQUEST_TYPE, DEPOSIT_REQUEST_TYPE, ForkName, ForkPostFulu, ForkPreFulu, WITHDRAWAL_REQUEST_TYPE } from "@lodestar/params";
import { BlobsBundle, ExecutionPayload, ExecutionRequests, Root, RootHex, Wei, capella } from "@lodestar/types";
import { BlobAndProof } from "@lodestar/types/deneb";
import { BlobAndProofV2 } from "@lodestar/types/fulu";
import { PayloadId, PayloadIdCache, WithdrawalV1 } from "./payloadIdCache.js";
import { ExecutionPayloadBody } from "./types.js";
import { DATA } from "./utils.js";
export { PayloadIdCache, type PayloadId, type WithdrawalV1 };
export type ClientVersion = routes.node.ClientVersion;
export declare const ClientCode: typeof routes.node.ClientCode;
export declare enum ExecutionPayloadStatus {
    /** given payload is valid */
    VALID = "VALID",
    /** given payload is invalid */
    INVALID = "INVALID",
    /** sync process is in progress */
    SYNCING = "SYNCING",
    /**
     * blockHash is valid, but payload is not part of canonical chain and hasn't been fully
     * validated
     */
    ACCEPTED = "ACCEPTED",
    /** blockHash is invalid */
    INVALID_BLOCK_HASH = "INVALID_BLOCK_HASH",
    /** EL error */
    ELERROR = "ELERROR",
    /** EL unavailable */
    UNAVAILABLE = "UNAVAILABLE",
    /** EL replied with SYNCING or ACCEPTED when its not safe to import optimistic blocks */
    UNSAFE_OPTIMISTIC_STATUS = "UNSAFE_OPTIMISTIC_STATUS"
}
export declare enum ExecutionEngineState {
    ONLINE = "ONLINE",
    OFFLINE = "OFFLINE",
    SYNCING = "SYNCING",
    SYNCED = "SYNCED",
    AUTH_FAILED = "AUTH_FAILED"
}
export type ExecutionRequestType = typeof DEPOSIT_REQUEST_TYPE | typeof WITHDRAWAL_REQUEST_TYPE | typeof CONSOLIDATION_REQUEST_TYPE;
export declare function isExecutionRequestType(type: number): type is ExecutionRequestType;
export type ExecutePayloadResponse = {
    status: ExecutionPayloadStatus.SYNCING | ExecutionPayloadStatus.ACCEPTED;
    latestValidHash: null;
    validationError: null;
} | {
    status: ExecutionPayloadStatus.VALID;
    latestValidHash: RootHex;
    validationError: null;
} | {
    status: ExecutionPayloadStatus.INVALID;
    latestValidHash: RootHex | null;
    validationError: string | null;
} | {
    status: ExecutionPayloadStatus.INVALID_BLOCK_HASH | ExecutionPayloadStatus.ELERROR | ExecutionPayloadStatus.UNAVAILABLE;
    latestValidHash: null;
    validationError: string;
};
export type ForkChoiceUpdateStatus = ExecutionPayloadStatus.VALID | ExecutionPayloadStatus.INVALID | ExecutionPayloadStatus.SYNCING;
export type PayloadAttributes = {
    timestamp: number;
    prevRandao: Uint8Array;
    suggestedFeeRecipient: string;
    withdrawals?: capella.Withdrawal[];
    parentBeaconBlockRoot?: Uint8Array;
    slotNumber?: number;
};
export type VersionedHashes = Uint8Array[];
/**
 * Execution engine represents an abstract protocol to interact with execution clients. Potential transports include:
 * - JSON RPC over network
 * - IPC
 * - Integrated code into the same binary
 */
export interface IExecutionEngine {
    readonly state: ExecutionEngineState;
    readonly clientVersion?: ClientVersion | null;
    payloadIdCache: PayloadIdCache;
    /**
     * A state transition function which applies changes to the self.execution_state.
     * Returns ``True`` iff ``execution_payload`` is valid with respect to ``self.execution_state``.
     *
     * Required for block processing in the beacon state transition function.
     * https://github.com/ethereum/consensus-specs/blob/0eb0a934a3/specs/merge/beacon-chain.md#on_payload
     *
     * Should be called in advance before, after or in parallel to block processing
     */
    notifyNewPayload(fork: ForkName, executionPayload: ExecutionPayload, versionedHashes?: VersionedHashes, parentBeaconBlockRoot?: Root, executionRequests?: ExecutionRequests): Promise<ExecutePayloadResponse>;
    /**
     * Signal fork choice updates
     * This function performs two actions atomically:
     * - Re-organizes the execution payload chain and corresponding state to make head_block_hash the head.
     * - Applies finality to the execution state: it irreversibly persists the chain of all execution payloads and
     *   corresponding state, up to and including finalized_block_hash.
     *
     * The call of the notify_forkchoice_updated function maps on the POS_FORKCHOICE_UPDATED event defined in the EIP-3675.
     * https://github.com/ethereum/consensus-specs/blob/v1.1.7/specs/merge/fork-choice.md#notify_forkchoice_updated
     *
     * Should be called in response to fork-choice head and finalized events
     */
    notifyForkchoiceUpdate(fork: ForkName, headBlockHash: RootHex, safeBlockHash: RootHex, finalizedBlockHash: RootHex, payloadAttributes?: PayloadAttributes): Promise<PayloadId | null>;
    /**
     * Given the payload_id, get_payload returns the most recent version of the execution payload that has been built
     * since the corresponding call to prepare_payload method.
     *
     * Required for block producing
     * https://github.com/ethereum/consensus-specs/blob/v1.1.7/specs/merge/validator.md#get_payload
     */
    getPayload(fork: ForkName, payloadId: PayloadId): Promise<{
        executionPayload: ExecutionPayload;
        executionPayloadValue: Wei;
        blobsBundle?: BlobsBundle;
        executionRequests?: ExecutionRequests;
        shouldOverrideBuilder?: boolean;
    }>;
    getPayloadBodiesByHash(fork: ForkName, blockHash: DATA[]): Promise<(ExecutionPayloadBody | null)[]>;
    getPayloadBodiesByRange(fork: ForkName, start: number, count: number): Promise<(ExecutionPayloadBody | null)[]>;
    getBlobs(fork: ForkPostFulu, versionedHashes: VersionedHashes, buffers?: Uint8Array[]): Promise<BlobAndProofV2[] | null>;
    getBlobs(fork: ForkPreFulu, versionedHashes: VersionedHashes, buffers?: Uint8Array[]): Promise<(BlobAndProof | null)[]>;
}
//# sourceMappingURL=interface.d.ts.map