@lodestar/fork-choice 1.35.0-dev.f80d2d52da → 1.35.0-dev.fcf8d024ea

package/src/forkChoice/interface.ts

@@ -0,0 +1,269 @@
+import {
+  CachedBeaconStateAllForks,
+  DataAvailabilityStatus,
+  EffectiveBalanceIncrements,
+} from "@lodestar/state-transition";
+import {
+  AttesterSlashing,
+  BeaconBlock,
+  Epoch,
+  IndexedAttestation,
+  Root,
+  RootHex,
+  Slot,
+  ValidatorIndex,
+} from "@lodestar/types";
+import {LVHExecResponse, MaybeValidExecutionStatus, ProtoBlock, ProtoNode} from "../protoArray/interface.js";
+import {UpdateAndGetHeadOpt} from "./forkChoice.js";
+import {CheckpointWithHex} from "./store.js";
+
+export type CheckpointHex = {
+  epoch: Epoch;
+  root: RootHex;
+};
+
+export type CheckpointsWithHex = {
+  justifiedCheckpoint: CheckpointWithHex;
+  finalizedCheckpoint: CheckpointWithHex;
+};
+
+export type CheckpointHexWithBalance = {
+  checkpoint: CheckpointWithHex;
+  balances: EffectiveBalanceIncrements;
+};
+
+export type CheckpointHexWithTotalBalance = CheckpointHexWithBalance & {
+  totalBalance: number;
+};
+
+export enum EpochDifference {
+  current = 0,
+  previous = 1,
+}
+
+export enum AncestorStatus {
+  CommonAncestor,
+  Descendant,
+  NoCommonAncenstor,
+  BlockUnknown,
+}
+
+export type AncestorResult =
+  | {code: AncestorStatus.CommonAncestor; depth: number}
+  | {code: AncestorStatus.Descendant}
+  | {code: AncestorStatus.NoCommonAncenstor}
+  | {code: AncestorStatus.BlockUnknown};
+
+// Reason for not proposer boost reorging
+export enum NotReorgedReason {
+  HeadBlockIsTimely = "headBlockIsTimely",
+  ParentBlockNotAvailable = "parentBlockNotAvailable",
+  ProposerBoostReorgDisabled = "proposerBoostReorgDisabled",
+  NotShufflingStable = "notShufflingStable",
+  NotFFGCompetitive = "notFFGCompetitive",
+  ChainLongUnfinality = "chainLongUnfinality",
+  ParentBlockDistanceMoreThanOneSlot = "parentBlockDistanceMoreThanOneSlot",
+  ReorgMoreThanOneSlot = "reorgMoreThanOneSlot",
+  ProposerBoostNotWornOff = "proposerBoostNotWornOff",
+  HeadBlockNotWeak = "headBlockNotWeak",
+  ParentBlockNotStrong = "parentBlockNotStrong",
+  NotProposingOnTime = "notProposingOnTime",
+  NotProposerOfNextSlot = "notProposerOfNextSlot",
+  HeadBlockNotAvailable = "headBlockNotAvailable", // Should not happen because head block should be in cache
+  Unknown = "unknown", // A placeholder in case reason is not provided
+}
+
+export type ShouldOverrideForkChoiceUpdateResult =
+  | {shouldOverrideFcu: true; parentBlock: ProtoBlock}
+  | {shouldOverrideFcu: false; reason: NotReorgedReason};
+
+export interface IForkChoice {
+  irrecoverableError?: Error;
+
+  /**
+   * Returns the block root of an ancestor of `block_root` at the given `slot`. (Note: `slot` refers
+   * to the block that is *returned*, not the one that is supplied.)
+   *
+   * ## Specification
+   *
+   * Equivalent to:
+   *
+   * https://github.com/ethereum/consensus-specs/blob/v1.1.10/specs/phase0/fork-choice.md#get_ancestor
+   */
+  getAncestor(blockRoot: RootHex, ancestorSlot: Slot): RootHex;
+  /**
+   * Run the fork choice rule to determine the head.
+   *
+   * ## Specification
+   *
+   * Is equivalent to:
+   *
+   * https://github.com/ethereum/consensus-specs/blob/v1.1.10/specs/phase0/fork-choice.md#get_head
+   */
+  getHeadRoot(): RootHex;
+  getHead(): ProtoBlock;
+  updateAndGetHead(mode: UpdateAndGetHeadOpt): {
+    head: ProtoBlock;
+    isHeadTimely?: boolean;
+    notReorgedReason?: NotReorgedReason;
+  };
+  /**
+   * This is called during block import when proposerBoostReorg is enabled
+   * fcu call in `importBlock()` will be suppressed if this returns true. It is also
+   * called by `predictProposerHead()` during `prepareNextSlot()`.
+   */
+  shouldOverrideForkChoiceUpdate(
+    blockRoot: RootHex,
+    secFromSlot: number,
+    currentSlot: Slot
+  ): ShouldOverrideForkChoiceUpdateResult;
+  /**
+   * Retrieves all possible chain heads (leaves of fork choice tree).
+   */
+  getHeads(): ProtoBlock[];
+  /**
+   * Retrieve all nodes for the debug API.
+   */
+  getAllNodes(): ProtoNode[];
+  getFinalizedCheckpoint(): CheckpointWithHex;
+  getJustifiedCheckpoint(): CheckpointWithHex;
+  /**
+   * Add `block` to the fork choice DAG.
+   *
+   * ## Specification
+   *
+   * Approximates:
+   *
+   * https://github.com/ethereum/consensus-specs/blob/v1.1.10/specs/phase0/fork-choice.md#on_block
+   *
+   * It only approximates the specification since it does not run the `state_transition` check.
+   * That should have already been called upstream and it's too expensive to call again.
+   *
+   * ## Notes:
+   *
+   * The supplied block **must** pass the `state_transition` function as it will not be run here.
+   */
+  onBlock(
+    block: BeaconBlock,
+    state: CachedBeaconStateAllForks,
+    blockDelaySec: number,
+    currentSlot: Slot,
+    executionStatus: MaybeValidExecutionStatus,
+    dataAvailabilityStatus: DataAvailabilityStatus
+  ): ProtoBlock;
+  /**
+   * Register `attestation` with the fork choice DAG so that it may influence future calls to `getHead`.
+   *
+   * ## Specification
+   *
+   * Approximates:
+   *
+   * https://github.com/ethereum/consensus-specs/blob/v1.1.10/specs/phase0/fork-choice.md#on_attestation
+   *
+   * It only approximates the specification since it does not perform
+   * `is_valid_indexed_attestation` since that should already have been called upstream and it's
+   * too expensive to call again.
+   *
+   * ## Notes:
+   *
+   * The supplied `attestation` **must** pass the `in_valid_indexed_attestation` function as it
+   * will not be run here.
+   */
+  onAttestation(attestation: IndexedAttestation, attDataRoot: string, forceImport?: boolean): void;
+  /**
+   * Register attester slashing in order not to consider their votes in `getHead`
+   *
+   * ## Specification
+   *
+   * https://github.com/ethereum/consensus-specs/blob/v1.2.0-rc.3/specs/phase0/fork-choice.md#on_attester_slashing
+   */
+  onAttesterSlashing(slashing: AttesterSlashing): void;
+  getLatestMessage(validatorIndex: ValidatorIndex): LatestMessage | undefined;
+  /**
+   * Call `onTick` for all slots between `fcStore.getCurrentSlot()` and the provided `currentSlot`.
+   */
+  updateTime(currentSlot: Slot): void;
+
+  /**
+   * Returns current time slot.
+   */
+  getTime(): Slot;
+  /**
+   * Returns `true` if the block is known **and** a descendant of the finalized root.
+   */
+  hasBlock(blockRoot: Root): boolean;
+  hasBlockHex(blockRoot: RootHex): boolean;
+  /**
+   * Same to hasBlock, but without checking if the block is a descendant of the finalized root.
+   */
+  hasBlockUnsafe(blockRoot: Root): boolean;
+  hasBlockHexUnsafe(blockRoot: RootHex): boolean;
+  getSlotsPresent(windowStart: number): number;
+  /**
+   * Returns a `ProtoBlock` if the block is known **and** a descendant of the finalized root.
+   */
+  getBlock(blockRoot: Root): ProtoBlock | null;
+  getBlockHex(blockRoot: RootHex): ProtoBlock | null;
+  getFinalizedBlock(): ProtoBlock;
+  getJustifiedBlock(): ProtoBlock;
+  /**
+   * Returns true if the `descendantRoot` has an ancestor with `ancestorRoot`.
+   *
+   * Always returns `false` if either input roots are unknown.
+   * Still returns `true` if `ancestorRoot===descendantRoot` (and the roots are known)
+   */
+  isDescendant(ancestorRoot: RootHex, descendantRoot: RootHex): boolean;
+  /**
+   * Prune items up to a finalized root.
+   */
+  prune(finalizedRoot: RootHex): ProtoBlock[];
+  setPruneThreshold(threshold: number): void;
+  /**
+   * Iterates backwards through ancestor block summaries, starting from a block root
+   */
+  iterateAncestorBlocks(blockRoot: RootHex): IterableIterator<ProtoBlock>;
+  getAllAncestorBlocks(blockRoot: RootHex): ProtoBlock[];
+  /**
+   * The same to iterateAncestorBlocks but this gets non-ancestor nodes instead of ancestor nodes.
+   */
+  getAllNonAncestorBlocks(blockRoot: RootHex): ProtoBlock[];
+  /**
+   * Returns both ancestor and non-ancestor blocks in a single traversal.
+   */
+  getAllAncestorAndNonAncestorBlocks(blockRoot: RootHex): {ancestors: ProtoBlock[]; nonAncestors: ProtoBlock[]};
+  getCanonicalBlockAtSlot(slot: Slot): ProtoBlock | null;
+  getCanonicalBlockClosestLteSlot(slot: Slot): ProtoBlock | null;
+  /**
+   * Returns all ProtoBlock known to fork-choice. Must not mutated the returned array
+   */
+  forwarditerateAncestorBlocks(): ProtoBlock[];
+  /**
+   * Iterates forward descendants of blockRoot. Does not yield blockRoot itself
+   */
+  forwardIterateDescendants(blockRoot: RootHex): IterableIterator<ProtoBlock>;
+  getBlockSummariesByParentRoot(parentRoot: RootHex): ProtoBlock[];
+  getBlockSummariesAtSlot(slot: Slot): ProtoBlock[];
+  /** Returns the distance of common ancestor of nodes to the max of the newNode and the prevNode. */
+  getCommonAncestorDepth(prevBlock: ProtoBlock, newBlock: ProtoBlock): AncestorResult;
+  /**
+   * Optimistic sync validate till validated latest hash, invalidate any decendant branch if invalidated branch decendant provided
+   */
+  validateLatestHash(execResponse: LVHExecResponse): void;
+
+  /**
+   * A dependent root is the block root of the last block before the state transition that decided a specific shuffling
+   */
+  getDependentRoot(block: ProtoBlock, atEpochDiff: EpochDifference): RootHex;
+}
+
+/** Same to the PowBlock but we want RootHex to work with forkchoice conveniently */
+export type PowBlockHex = {
+  blockHash: RootHex;
+  parentHash: RootHex;
+  totalDifficulty: bigint;
+};
+
+export type LatestMessage = {
+  epoch: Epoch;
+  root: RootHex;
+};

package/src/forkChoice/store.ts

@@ -0,0 +1,124 @@
+import {CachedBeaconStateAllForks, EffectiveBalanceIncrements} from "@lodestar/state-transition";
+import {RootHex, Slot, ValidatorIndex, phase0} from "@lodestar/types";
+import {toRootHex} from "@lodestar/utils";
+import {CheckpointHexWithBalance, CheckpointHexWithTotalBalance} from "./interface.js";
+
+/**
+ * Stores checkpoints in a hybrid format:
+ * - Original checkpoint for fast consumption in Lodestar's side
+ * - Root in string hex for fast comparisons inside the fork-choice
+ */
+export type CheckpointWithHex = phase0.Checkpoint & {rootHex: RootHex};
+
+export type JustifiedBalances = EffectiveBalanceIncrements;
+
+/**
+ * Returns the justified balances of checkpoint.
+ * MUST not throw an error in any case, related to cache miss. Either trigger regen or approximate from a close state.
+ * `blockState` is maybe used as a fallback state to get balances since it's very close to desired justified state.
+ * @param blockState state that declares justified checkpoint `checkpoint`
+ */
+export type JustifiedBalancesGetter = (
+  checkpoint: CheckpointWithHex,
+  blockState: CachedBeaconStateAllForks
+) => JustifiedBalances;
+
+/**
+ * Approximates the `Store` in "Ethereum Consensus -- Beacon Chain Fork Choice":
+ *
+ * https://github.com/ethereum/consensus-specs/blob/v1.1.10/specs/phase0/fork-choice.md#store
+ *
+ * ## Detail
+ *
+ * This is only an approximation for two reasons:
+ *
+ * - The actual block DAG in `ProtoArray`.
+ * - `time` is represented using `Slot` instead of UNIX epoch `u64`.
+ */
+export interface IForkChoiceStore {
+  currentSlot: Slot;
+  get justified(): CheckpointHexWithTotalBalance;
+  set justified(justified: CheckpointHexWithBalance);
+  unrealizedJustified: CheckpointHexWithBalance;
+  finalizedCheckpoint: CheckpointWithHex;
+  unrealizedFinalizedCheckpoint: CheckpointWithHex;
+  justifiedBalancesGetter: JustifiedBalancesGetter;
+  equivocatingIndices: Set<ValidatorIndex>;
+}
+
+/**
+ * IForkChoiceStore implementer which emits forkChoice events on updated justified and finalized checkpoints.
+ */
+export class ForkChoiceStore implements IForkChoiceStore {
+  private _justified: CheckpointHexWithTotalBalance;
+  unrealizedJustified: CheckpointHexWithBalance;
+  private _finalizedCheckpoint: CheckpointWithHex;
+  unrealizedFinalizedCheckpoint: CheckpointWithHex;
+  equivocatingIndices = new Set<ValidatorIndex>();
+  justifiedBalancesGetter: JustifiedBalancesGetter;
+  currentSlot: Slot;
+
+  constructor(
+    currentSlot: Slot,
+    justifiedCheckpoint: phase0.Checkpoint,
+    finalizedCheckpoint: phase0.Checkpoint,
+    justifiedBalances: EffectiveBalanceIncrements,
+    justifiedBalancesGetter: JustifiedBalancesGetter,
+    private readonly events?: {
+      onJustified: (cp: CheckpointWithHex) => void;
+      onFinalized: (cp: CheckpointWithHex) => void;
+    }
+  ) {
+    this.justifiedBalancesGetter = justifiedBalancesGetter;
+    this.currentSlot = currentSlot;
+    const justified = {
+      checkpoint: toCheckpointWithHex(justifiedCheckpoint),
+      balances: justifiedBalances,
+      totalBalance: computeTotalBalance(justifiedBalances),
+    };
+    this._justified = justified;
+    this.unrealizedJustified = justified;
+    this._finalizedCheckpoint = toCheckpointWithHex(finalizedCheckpoint);
+    this.unrealizedFinalizedCheckpoint = this._finalizedCheckpoint;
+  }
+
+  get justified(): CheckpointHexWithTotalBalance {
+    return this._justified;
+  }
+  set justified(justified: CheckpointHexWithBalance) {
+    this._justified = {...justified, totalBalance: computeTotalBalance(justified.balances)};
+    this.events?.onJustified(justified.checkpoint);
+  }
+
+  get finalizedCheckpoint(): CheckpointWithHex {
+    return this._finalizedCheckpoint;
+  }
+  set finalizedCheckpoint(checkpoint: CheckpointWithHex) {
+    const cp = toCheckpointWithHex(checkpoint);
+    this._finalizedCheckpoint = cp;
+    this.events?.onFinalized(cp);
+  }
+}
+
+export function toCheckpointWithHex(checkpoint: phase0.Checkpoint): CheckpointWithHex {
+  // `valueOf` coerses the checkpoint, which may be tree-backed, into a javascript object
+  // See https://github.com/ChainSafe/lodestar/issues/2258
+  const root = checkpoint.root;
+  return {
+    epoch: checkpoint.epoch,
+    root,
+    rootHex: toRootHex(root),
+  };
+}
+
+export function equalCheckpointWithHex(a: CheckpointWithHex, b: CheckpointWithHex): boolean {
+  return a.epoch === b.epoch && a.rootHex === b.rootHex;
+}
+
+export function computeTotalBalance(balances: EffectiveBalanceIncrements): number {
+  let totalBalance = 0;
+  for (let i = 0; i < balances.length; i++) {
+    totalBalance += balances[i];
+  }
+  return totalBalance;
+}

package/src/index.ts

@@ -0,0 +1,34 @@
+export {
+  ForkChoiceError,
+  ForkChoiceErrorCode,
+  type InvalidAttestation,
+  InvalidAttestationCode,
+  type InvalidBlock,
+  InvalidBlockCode,
+} from "./forkChoice/errors.js";
+export {ForkChoice, type ForkChoiceOpts, UpdateHeadOpt, assertValidTerminalPowBlock} from "./forkChoice/forkChoice.js";
+export {
+  type AncestorResult,
+  AncestorStatus,
+  EpochDifference,
+  type IForkChoice,
+  NotReorgedReason,
+  type PowBlockHex,
+} from "./forkChoice/interface.js";
+export {
+  type CheckpointWithHex,
+  ForkChoiceStore,
+  type IForkChoiceStore,
+  type JustifiedBalancesGetter,
+} from "./forkChoice/store.js";
+export {type ForkChoiceMetrics, getForkChoiceMetrics} from "./metrics.js";
+export type {
+  BlockExtraMeta,
+  LVHInvalidResponse,
+  LVHValidResponse,
+  MaybeValidExecutionStatus,
+  ProtoBlock,
+  ProtoNode,
+} from "./protoArray/interface.js";
+export {ExecutionStatus} from "./protoArray/interface.js";
+export {ProtoArray} from "./protoArray/protoArray.js";

package/src/metrics.ts

@@ -0,0 +1,71 @@
+import {MetricsRegisterExtra} from "@lodestar/utils";
+import {UpdateHeadOpt} from "./forkChoice/forkChoice.js";
+import {NotReorgedReason} from "./forkChoice/interface.js";
+
+export type ForkChoiceMetrics = ReturnType<typeof getForkChoiceMetrics>;
+
+export function getForkChoiceMetrics(register: MetricsRegisterExtra) {
+  return {
+    forkChoice: {
+      findHead: register.histogram<{caller: string}>({
+        name: "beacon_fork_choice_find_head_seconds",
+        help: "Time taken to find head in seconds",
+        buckets: [0.1, 1, 10],
+        labelNames: ["caller"],
+      }),
+      requests: register.gauge({
+        name: "beacon_fork_choice_requests_total",
+        help: "Count of occasions where fork choice has tried to find a head",
+      }),
+      errors: register.gauge<{entrypoint: UpdateHeadOpt}>({
+        name: "beacon_fork_choice_errors_total",
+        help: "Count of occasions where fork choice has returned an error when trying to find a head",
+        labelNames: ["entrypoint"],
+      }),
+      changedHead: register.gauge({
+        name: "beacon_fork_choice_changed_head_total",
+        help: "Count of occasions fork choice has found a new head",
+      }),
+      reorg: register.gauge({
+        name: "beacon_fork_choice_reorg_total",
+        help: "Count of occasions fork choice has switched to a different chain",
+      }),
+      reorgDistance: register.histogram({
+        name: "beacon_fork_choice_reorg_distance",
+        help: "Histogram of re-org distance",
+        // We need high resolution in the low range, since re-orgs are a rare but critical event.
+        // Add buckets up to 100 to capture high depth re-orgs. Above 100 things are going really bad.
+        buckets: [1, 2, 3, 5, 7, 10, 20, 30, 50, 100],
+      }),
+      votes: register.gauge({
+        name: "beacon_fork_choice_votes_count",
+        help: "Current count of votes in fork choice data structures",
+      }),
+      queuedAttestations: register.gauge({
+        name: "beacon_fork_choice_queued_attestations_count",
+        help: "Count of queued_attestations in fork choice per slot",
+      }),
+      validatedAttestationDatas: register.gauge({
+        name: "beacon_fork_choice_validated_attestation_datas_count",
+        help: "Current count of validatedAttestationDatas in fork choice data structures",
+      }),
+      balancesLength: register.gauge({
+        name: "beacon_fork_choice_balances_length",
+        help: "Current length of balances in fork choice data structures",
+      }),
+      nodes: register.gauge({
+        name: "beacon_fork_choice_nodes_count",
+        help: "Current count of nodes in fork choice data structures",
+      }),
+      indices: register.gauge({
+        name: "beacon_fork_choice_indices_count",
+        help: "Current count of indices in fork choice data structures",
+      }),
+      notReorgedReason: register.counter<{reason: NotReorgedReason}>({
+        name: "beacon_fork_choice_not_reorged_reason_total",
+        help: "Reason why the current head is not re-orged out",
+        labelNames: ["reason"],
+      }),
+    },
+  };
+}

package/src/protoArray/computeDeltas.ts

@@ -0,0 +1,97 @@
+import {EffectiveBalanceIncrements} from "@lodestar/state-transition";
+import {ValidatorIndex} from "@lodestar/types";
+import {ProtoArrayError, ProtoArrayErrorCode} from "./errors.js";
+import {VoteTracker} from "./interface.js";
+
+// reuse arrays to avoid memory reallocation and gc
+const deltas = new Array<number>();
+
+/**
+ * Returns a list of `deltas`, where there is one delta for each of the indices in `indices`
+ *
+ * The deltas are formed by a change between `oldBalances` and `newBalances`, and/or a change of vote in `votes`.
+ *
+ * ## Errors
+ *
+ * - If a value in `indices` is greater to or equal to `indices.length`.
+ */
+export function computeDeltas(
+  numProtoNodes: number,
+  votes: VoteTracker[],
+  oldBalances: EffectiveBalanceIncrements,
+  newBalances: EffectiveBalanceIncrements,
+  equivocatingIndices: Set<ValidatorIndex>
+): number[] {
+  deltas.length = numProtoNodes;
+  deltas.fill(0);
+
+  // avoid creating new variables in the loop to potentially reduce GC pressure
+  let oldBalance: number, newBalance: number;
+  let currentIndex: number | null, nextIndex: number | null;
+
+  for (let vIndex = 0; vIndex < votes.length; vIndex++) {
+    const vote = votes[vIndex];
+    // There is no need to create a score change if the validator has never voted or both of their
+    // votes are for the zero hash (genesis block)
+    if (vote === undefined) {
+      continue;
+    }
+    currentIndex = vote.currentIndex;
+    nextIndex = vote.nextIndex;
+
+    // IF the validator was not included in the _old_ balances (i.e. it did not exist yet)
+    // then say its balance was 0
+    oldBalance = oldBalances[vIndex] ?? 0;
+
+    // If the validator's vote is not known in the _new_ balances, then use a balance of zero.
+    //
+    // It is possible that there was a vote for an unknown validator if we change our justified
+    // state to a new state with a higher epoch that is on a different fork because that fork may have
+    // on-boarded fewer validators than the prior fork.
+    newBalance = newBalances === oldBalances ? oldBalance : (newBalances[vIndex] ?? 0);
+
+    if (equivocatingIndices.size > 0 && equivocatingIndices.has(vIndex)) {
+      // this function could be called multiple times but we only want to process slashing validator for 1 time
+      if (currentIndex !== null) {
+        if (currentIndex >= numProtoNodes) {
+          throw new ProtoArrayError({
+            code: ProtoArrayErrorCode.INVALID_NODE_DELTA,
+            index: currentIndex,
+          });
+        }
+        deltas[currentIndex] -= oldBalance;
+      }
+      vote.currentIndex = null;
+      continue;
+    }
+
+    if (currentIndex !== nextIndex || oldBalance !== newBalance) {
+      // We ignore the vote if it is not known in `indices .
+      // We assume that it is outside of our tree (ie: pre-finalization) and therefore not interesting
+      if (currentIndex !== null) {
+        if (currentIndex >= numProtoNodes) {
+          throw new ProtoArrayError({
+            code: ProtoArrayErrorCode.INVALID_NODE_DELTA,
+            index: currentIndex,
+          });
+        }
+        deltas[currentIndex] -= oldBalance;
+      }
+
+      // We ignore the vote if it is not known in `indices .
+      // We assume that it is outside of our tree (ie: pre-finalization) and therefore not interesting
+      if (nextIndex !== null) {
+        if (nextIndex >= numProtoNodes) {
+          throw new ProtoArrayError({
+            code: ProtoArrayErrorCode.INVALID_NODE_DELTA,
+            index: nextIndex,
+          });
+        }
+        deltas[nextIndex] += newBalance;
+      }
+    }
+    vote.currentIndex = nextIndex;
+  }
+
+  return deltas;
+}

package/src/protoArray/errors.ts

@@ -0,0 +1,59 @@
+import {Epoch, RootHex} from "@lodestar/types";
+import {LodestarError} from "@lodestar/utils";
+
+export enum LVHExecErrorCode {
+  PreMergeToInvalid = "PreMergeToInvalid",
+  ValidToInvalid = "ValidToInvalid",
+  InvalidToValid = "InvalidToValid",
+}
+
+export type LVHExecError = {lvhCode: LVHExecErrorCode; blockRoot: RootHex; execHash: RootHex};
+
+export enum ProtoArrayErrorCode {
+  FINALIZED_NODE_UNKNOWN = "PROTO_ARRAY_ERROR_FINALIZED_NODE_UNKNOWN",
+  JUSTIFIED_NODE_UNKNOWN = "PROTO_ARRAY_ERROR_JUSTIFIED_NODE_UNKNOWN",
+  INVALID_FINALIZED_ROOT_CHANGE = "PROTO_ARRAY_ERROR_INVALID_FINALIZED_ROOT_CHANGE",
+  INVALID_NODE_INDEX = "PROTO_ARRAY_ERROR_INVALID_NODE_INDEX",
+  INVALID_PARENT_INDEX = "PROTO_ARRAY_ERROR_INVALID_PARENT_INDEX",
+  INVALID_BEST_CHILD_INDEX = "PROTO_ARRAY_ERROR_INVALID_BEST_CHILD_INDEX",
+  INVALID_JUSTIFIED_INDEX = "PROTO_ARRAY_ERROR_INVALID_JUSTIFIED_INDEX",
+  INVALID_BEST_DESCENDANT_INDEX = "PROTO_ARRAY_ERROR_INVALID_BEST_DESCENDANT_INDEX",
+  INVALID_PARENT_DELTA = "PROTO_ARRAY_ERROR_INVALID_PARENT_DELTA",
+  INVALID_NODE_DELTA = "PROTO_ARRAY_ERROR_INVALID_NODE_DELTA",
+  INDEX_OVERFLOW = "PROTO_ARRAY_ERROR_INDEX_OVERFLOW",
+  INVALID_DELTA_LEN = "PROTO_ARRAY_ERROR_INVALID_DELTA_LEN",
+  REVERTED_FINALIZED_EPOCH = "PROTO_ARRAY_ERROR_REVERTED_FINALIZED_EPOCH",
+  INVALID_BEST_NODE = "PROTO_ARRAY_ERROR_INVALID_BEST_NODE",
+  INVALID_BLOCK_EXECUTION_STATUS = "PROTO_ARRAY_INVALID_BLOCK_EXECUTION_STATUS",
+  INVALID_JUSTIFIED_EXECUTION_STATUS = "PROTO_ARRAY_INVALID_JUSTIFIED_EXECUTION_STATUS",
+  INVALID_LVH_EXECUTION_RESPONSE = "PROTO_ARRAY_INVALID_LVH_EXECUTION_RESPONSE",
+}
+
+export type ProtoArrayErrorType =
+  | {code: ProtoArrayErrorCode.FINALIZED_NODE_UNKNOWN; root: RootHex}
+  | {code: ProtoArrayErrorCode.JUSTIFIED_NODE_UNKNOWN; root: RootHex}
+  | {code: ProtoArrayErrorCode.INVALID_FINALIZED_ROOT_CHANGE}
+  | {code: ProtoArrayErrorCode.INVALID_NODE_INDEX; index: number}
+  | {code: ProtoArrayErrorCode.INVALID_PARENT_INDEX; index: number}
+  | {code: ProtoArrayErrorCode.INVALID_BEST_CHILD_INDEX; index: number}
+  | {code: ProtoArrayErrorCode.INVALID_JUSTIFIED_INDEX; index: number}
+  | {code: ProtoArrayErrorCode.INVALID_BEST_DESCENDANT_INDEX; index: number}
+  | {code: ProtoArrayErrorCode.INVALID_PARENT_DELTA; index: number}
+  | {code: ProtoArrayErrorCode.INVALID_NODE_DELTA; index: number}
+  | {code: ProtoArrayErrorCode.INDEX_OVERFLOW; value: string}
+  | {code: ProtoArrayErrorCode.INVALID_DELTA_LEN; deltas: number; indices: number}
+  | {code: ProtoArrayErrorCode.REVERTED_FINALIZED_EPOCH; currentFinalizedEpoch: Epoch; newFinalizedEpoch: Epoch}
+  | {
+      code: ProtoArrayErrorCode.INVALID_BEST_NODE;
+      startRoot: RootHex;
+      justifiedEpoch: Epoch;
+      finalizedEpoch: Epoch;
+      headRoot: RootHex;
+      headJustifiedEpoch: Epoch;
+      headFinalizedEpoch: Epoch;
+    }
+  | {code: ProtoArrayErrorCode.INVALID_BLOCK_EXECUTION_STATUS; root: RootHex}
+  | {code: ProtoArrayErrorCode.INVALID_JUSTIFIED_EXECUTION_STATUS; root: RootHex}
+  | ({code: ProtoArrayErrorCode.INVALID_LVH_EXECUTION_RESPONSE} & LVHExecError);
+
+export class ProtoArrayError extends LodestarError<ProtoArrayErrorType> {}