@lodestar/validator 1.35.0-dev.83de5b8dea → 1.35.0-dev.8689cc3545

package/src/types.ts

@@ -0,0 +1,31 @@
+import {SecretKey} from "@chainsafe/blst";
+import {DatabaseController} from "@lodestar/db";
+import {BLSPubkey} from "@lodestar/types";
+
+export type GenesisInfo = {
+  startTime: number;
+};
+
+export type BLSKeypair = {
+  publicKey: BLSPubkey;
+  secretKey: SecretKey;
+};
+
+/**
+ * The validator's BLS public key, uniquely identifying them. _48-bytes, hex encoded with 0x prefix, case insensitive._
+ * ```
+ * "0x93247f2209abcacf57b75a51dafae777f9dd38bc7053d1af526f220a7489a6d3a2753e5f3e8b1cfe39b56f43611df74a"
+ * ```
+ */
+export type PubkeyHex = string;
+
+export type LodestarValidatorDatabaseController = Pick<
+  DatabaseController<Uint8Array, Uint8Array>,
+  "close" | "setMetrics" | "values" | "batchPut" | "keys" | "get" | "put"
+>;
+
+/**
+ * Callback to request a parent process to shudown.
+ * This could be an AbortController, but sending a message upwards is very useful to log a reason for shudown
+ */
+export type ProcessShutdownCallback = (err: Error) => void;

package/src/util/batch.ts

@@ -0,0 +1,15 @@
+/**
+ * Convert array of items into array of batched item arrays
+ */
+export function batchItems<T>(items: T[], opts: {batchSize: number; maxBatches?: number}): T[][] {
+  const batches: T[][] = [];
+  const maxBatches = opts.maxBatches ?? Math.ceil(items.length / opts.batchSize);
+
+  for (let i = 0; i < maxBatches; i++) {
+    const batch = items.slice(opts.batchSize * i, opts.batchSize * (i + 1));
+    if (batch.length === 0) break;
+    batches.push(batch);
+  }
+
+  return batches;
+}

package/src/util/clock.ts

@@ -0,0 +1,164 @@
+import {ChainForkConfig} from "@lodestar/config";
+import {GENESIS_SLOT, SLOTS_PER_EPOCH} from "@lodestar/params";
+import {computeEpochAtSlot, getCurrentSlot} from "@lodestar/state-transition";
+import {Epoch, Slot, TimeSeconds} from "@lodestar/types";
+import {ErrorAborted, Logger, isErrorAborted, sleep} from "@lodestar/utils";
+
+type RunEveryFn = (slot: Slot, signal: AbortSignal) => Promise<void>;
+
+export interface IClock {
+  readonly genesisTime: number;
+  readonly secondsPerSlot: number;
+
+  readonly currentEpoch: number;
+
+  start(signal: AbortSignal): void;
+  runEverySlot(fn: (slot: Slot, signal: AbortSignal) => Promise<void>): void;
+  runEveryEpoch(fn: (epoch: Epoch, signal: AbortSignal) => Promise<void>): void;
+  msToSlot(slot: Slot): number;
+  secFromSlot(slot: Slot): number;
+  getCurrentSlot(): Slot;
+  getCurrentEpoch(): Epoch;
+}
+
+export enum TimeItem {
+  Slot,
+  Epoch,
+}
+
+export class Clock implements IClock {
+  readonly genesisTime: number;
+  readonly secondsPerSlot: number;
+  private readonly config: ChainForkConfig;
+  private readonly logger: Logger;
+  private readonly fns: {timeItem: TimeItem; fn: RunEveryFn}[] = [];
+
+  constructor(config: ChainForkConfig, logger: Logger, opts: {genesisTime: number}) {
+    this.genesisTime = opts.genesisTime;
+    this.secondsPerSlot = config.SECONDS_PER_SLOT;
+    this.config = config;
+    this.logger = logger;
+  }
+
+  get currentEpoch(): Epoch {
+    return computeEpochAtSlot(getCurrentSlot(this.config, this.genesisTime));
+  }
+
+  start(signal: AbortSignal): void {
+    for (const {timeItem, fn} of this.fns) {
+      this.runAtMostEvery(timeItem, signal, fn).catch((e: Error) => {
+        if (!isErrorAborted(e)) {
+          this.logger.error("runAtMostEvery", {}, e);
+        }
+      });
+    }
+  }
+
+  getCurrentSlot(): Slot {
+    return getCurrentSlot(this.config, this.genesisTime);
+  }
+
+  getCurrentEpoch(): Epoch {
+    return computeEpochAtSlot(getCurrentSlot(this.config, this.genesisTime));
+  }
+
+  runEverySlot(fn: RunEveryFn): void {
+    this.fns.push({timeItem: TimeItem.Slot, fn});
+  }
+
+  runEveryEpoch(fn: RunEveryFn): void {
+    this.fns.push({timeItem: TimeItem.Epoch, fn});
+  }
+
+  /** Milliseconds from now to a specific slot */
+  msToSlot(slot: Slot): number {
+    const timeAt = this.genesisTime + this.config.SECONDS_PER_SLOT * slot;
+    return timeAt * 1000 - Date.now();
+  }
+
+  /** Seconds elapsed from a specific slot to now */
+  secFromSlot(slot: Slot): number {
+    return Date.now() / 1000 - (this.genesisTime + this.config.SECONDS_PER_SLOT * slot);
+  }
+
+  /**
+   * If a task happens to take more than one slot to run, we might skip a slot. This is unfortunate,
+   * however the alternative is to *always* process every slot, which has the chance of creating a
+   * theoretically unlimited backlog of tasks. It was a conscious decision to choose to drop tasks
+   * on an overloaded/latent system rather than overload it even more.
+   */
+  private async runAtMostEvery(timeItem: TimeItem, signal: AbortSignal, fn: RunEveryFn): Promise<void> {
+    // Run immediately first
+    let slot = getCurrentSlot(this.config, this.genesisTime);
+    let slotOrEpoch = timeItem === TimeItem.Slot ? slot : computeEpochAtSlot(slot);
+    while (!signal.aborted) {
+      // Must catch fn() to ensure `sleep()` is awaited both for resolve and reject
+      await fn(slotOrEpoch, signal).catch((e: Error) => {
+        if (!isErrorAborted(e)) this.logger.error("Error on runEvery fn", {}, e);
+      });
+
+      try {
+        await sleep(this.timeUntilNext(timeItem), signal);
+        // calling getCurrentSlot here may not be correct when we're close to the next slot
+        // it's safe to call getCurrentSlotAround after we sleep
+        const nextSlot = getCurrentSlotAround(this.config, this.genesisTime);
+
+        if (timeItem === TimeItem.Slot) {
+          if (nextSlot > slot + 1) {
+            // It's not very likely that we skip more than one slot as HTTP timeout is set
+            // to SECONDS_PER_SLOT so we will fail task before skipping another slot.
+            this.logger.warn("Skipped slot due to task taking more than one slot to run", {
+              skippedSlot: slot + 1,
+            });
+          }
+          slotOrEpoch = nextSlot;
+        } else {
+          slotOrEpoch = computeEpochAtSlot(nextSlot);
+        }
+        slot = nextSlot;
+      } catch (e) {
+        if (e instanceof ErrorAborted) {
+          return;
+        }
+        throw e;
+      }
+    }
+  }
+
+  private timeUntilNext(timeItem: TimeItem): number {
+    const milliSecondsPerSlot = this.config.SECONDS_PER_SLOT * 1000;
+    const msFromGenesis = Date.now() - this.genesisTime * 1000;
+
+    if (timeItem === TimeItem.Slot) {
+      if (msFromGenesis >= 0) {
+        return milliSecondsPerSlot - (msFromGenesis % milliSecondsPerSlot);
+      }
+      return Math.abs(msFromGenesis) % milliSecondsPerSlot;
+    }
+    const milliSecondsPerEpoch = SLOTS_PER_EPOCH * milliSecondsPerSlot;
+    if (msFromGenesis >= 0) {
+      return milliSecondsPerEpoch - (msFromGenesis % milliSecondsPerEpoch);
+    }
+    return Math.abs(msFromGenesis) % milliSecondsPerEpoch;
+  }
+}
+
+/**
+ * Same to the spec but we use Math.round instead of Math.floor.
+ */
+export function getCurrentSlotAround(config: ChainForkConfig, genesisTime: TimeSeconds): Slot {
+  const diffInSeconds = Date.now() / 1000 - genesisTime;
+  const slotsSinceGenesis = Math.round(diffInSeconds / config.SECONDS_PER_SLOT);
+  return GENESIS_SLOT + slotsSinceGenesis;
+}
+
+// function useEventStream() {
+//   this.stream = this.events.getEventStream([BeaconEventType.BLOCK, BeaconEventType.HEAD, BeaconEventType.CHAIN_REORG]);
+//   pipeToEmitter(this.stream, this).catch((e: Error) => {
+//     this.logger.error("Error on stream pipe", {}, e);
+//   });
+
+//   // On stop
+//   this.stream.stop();
+//   this.stream = null;
+// }

package/src/util/difference.ts

@@ -0,0 +1,10 @@
+import {Root} from "@lodestar/types";
+import {toHex} from "@lodestar/utils";
+
+/**
+ * Return items included in `next` but not in `prev`
+ */
+export function differenceHex<T extends Uint8Array | Root>(prev: T[], next: T[]): T[] {
+  const existing = new Set(prev.map((item) => toHex(item)));
+  return next.filter((item) => !existing.has(toHex(item)));
+}

package/src/util/externalSignerClient.ts

@@ -0,0 +1,277 @@
+import {ContainerType, ValueOf} from "@chainsafe/ssz";
+import {BeaconConfig} from "@lodestar/config";
+import {ForkPreBellatrix, ForkSeq} from "@lodestar/params";
+import {blindedOrFullBlockToHeader, computeEpochAtSlot} from "@lodestar/state-transition";
+import {
+  AggregateAndProof,
+  BeaconBlock,
+  BlindedBeaconBlock,
+  Epoch,
+  Root,
+  RootHex,
+  Slot,
+  altair,
+  capella,
+  phase0,
+  ssz,
+  sszTypesFor,
+} from "@lodestar/types";
+import {ValidatorRegistrationV1} from "@lodestar/types/bellatrix";
+import {fetch, toHex, toRootHex} from "@lodestar/utils";
+import {PubkeyHex} from "../types.js";
+
+export enum SignableMessageType {
+  AGGREGATION_SLOT = "AGGREGATION_SLOT",
+  AGGREGATE_AND_PROOF = "AGGREGATE_AND_PROOF",
+  AGGREGATE_AND_PROOF_V2 = "AGGREGATE_AND_PROOF_V2",
+  ATTESTATION = "ATTESTATION",
+  BLOCK_V2 = "BLOCK_V2",
+  DEPOSIT = "DEPOSIT",
+  RANDAO_REVEAL = "RANDAO_REVEAL",
+  VOLUNTARY_EXIT = "VOLUNTARY_EXIT",
+  SYNC_COMMITTEE_MESSAGE = "SYNC_COMMITTEE_MESSAGE",
+  SYNC_COMMITTEE_SELECTION_PROOF = "SYNC_COMMITTEE_SELECTION_PROOF",
+  SYNC_COMMITTEE_CONTRIBUTION_AND_PROOF = "SYNC_COMMITTEE_CONTRIBUTION_AND_PROOF",
+  VALIDATOR_REGISTRATION = "VALIDATOR_REGISTRATION",
+  BLS_TO_EXECUTION_CHANGE = "BLS_TO_EXECUTION_CHANGE",
+}
+
+const AggregationSlotType = new ContainerType({
+  slot: ssz.Slot,
+});
+
+const DepositType = new ContainerType(
+  {
+    pubkey: ssz.BLSPubkey,
+    withdrawalCredentials: ssz.Bytes32,
+    amount: ssz.UintNum64,
+    genesisForkVersion: ssz.Bytes4,
+  },
+  {jsonCase: "eth2"}
+);
+
+const RandaoRevealType = new ContainerType({
+  epoch: ssz.Epoch,
+});
+
+const SyncCommitteeMessageType = new ContainerType(
+  {
+    beaconBlockRoot: ssz.Root,
+    slot: ssz.Slot,
+  },
+  {jsonCase: "eth2"}
+);
+
+const SyncAggregatorSelectionDataType = new ContainerType(
+  {
+    slot: ssz.Slot,
+    subcommitteeIndex: ssz.SubcommitteeIndex,
+  },
+  {jsonCase: "eth2"}
+);
+
+export type SignableMessage =
+  | {type: SignableMessageType.AGGREGATION_SLOT; data: {slot: Slot}}
+  | {type: SignableMessageType.AGGREGATE_AND_PROOF; data: phase0.AggregateAndProof}
+  | {type: SignableMessageType.AGGREGATE_AND_PROOF_V2; data: AggregateAndProof}
+  | {type: SignableMessageType.ATTESTATION; data: phase0.AttestationData}
+  | {type: SignableMessageType.BLOCK_V2; data: BeaconBlock<ForkPreBellatrix> | BlindedBeaconBlock}
+  | {type: SignableMessageType.DEPOSIT; data: ValueOf<typeof DepositType>}
+  | {type: SignableMessageType.RANDAO_REVEAL; data: {epoch: Epoch}}
+  | {type: SignableMessageType.VOLUNTARY_EXIT; data: phase0.VoluntaryExit}
+  | {type: SignableMessageType.SYNC_COMMITTEE_MESSAGE; data: ValueOf<typeof SyncCommitteeMessageType>}
+  | {type: SignableMessageType.SYNC_COMMITTEE_SELECTION_PROOF; data: ValueOf<typeof SyncAggregatorSelectionDataType>}
+  | {type: SignableMessageType.SYNC_COMMITTEE_CONTRIBUTION_AND_PROOF; data: altair.ContributionAndProof}
+  | {type: SignableMessageType.VALIDATOR_REGISTRATION; data: ValidatorRegistrationV1}
+  | {type: SignableMessageType.BLS_TO_EXECUTION_CHANGE; data: capella.BLSToExecutionChange};
+
+const requiresForkInfo: Record<SignableMessageType, boolean> = {
+  [SignableMessageType.AGGREGATION_SLOT]: true,
+  [SignableMessageType.AGGREGATE_AND_PROOF]: true,
+  [SignableMessageType.AGGREGATE_AND_PROOF_V2]: true,
+  [SignableMessageType.ATTESTATION]: true,
+  [SignableMessageType.BLOCK_V2]: true,
+  [SignableMessageType.DEPOSIT]: false,
+  [SignableMessageType.RANDAO_REVEAL]: true,
+  [SignableMessageType.VOLUNTARY_EXIT]: true,
+  [SignableMessageType.SYNC_COMMITTEE_MESSAGE]: true,
+  [SignableMessageType.SYNC_COMMITTEE_SELECTION_PROOF]: true,
+  [SignableMessageType.SYNC_COMMITTEE_CONTRIBUTION_AND_PROOF]: true,
+  [SignableMessageType.VALIDATOR_REGISTRATION]: false,
+  [SignableMessageType.BLS_TO_EXECUTION_CHANGE]: true,
+};
+
+type Web3SignerSerializedRequest = {
+  type: SignableMessageType;
+  fork_info?: {
+    fork: {
+      previous_version: RootHex;
+      current_version: RootHex;
+      epoch: string;
+    };
+    genesis_validators_root: RootHex;
+  };
+  signingRoot: RootHex;
+};
+
+enum MediaType {
+  json = "application/json",
+}
+
+/**
+ * Return public keys from the server.
+ */
+export async function externalSignerGetKeys(externalSignerUrl: string): Promise<string[]> {
+  const res = await fetch(`${externalSignerUrl}/api/v1/eth2/publicKeys`, {
+    method: "GET",
+    headers: {Accept: MediaType.json},
+  });
+
+  return handleExternalSignerResponse<string[]>(res);
+}
+
+/**
+ * Return signature in bytes. Assumption that the pubkey has it's corresponding secret key in the keystore of an external signer.
+ */
+export async function externalSignerPostSignature(
+  config: BeaconConfig,
+  externalSignerUrl: string,
+  pubkeyHex: PubkeyHex,
+  signingRoot: Root,
+  signingSlot: Slot,
+  signableMessage: SignableMessage
+): Promise<string> {
+  const requestObj = serializerSignableMessagePayload(config, signableMessage) as Web3SignerSerializedRequest;
+
+  requestObj.type = signableMessage.type;
+  requestObj.signingRoot = toRootHex(signingRoot);
+
+  if (requiresForkInfo[signableMessage.type]) {
+    const forkInfo = config.getForkInfo(signingSlot);
+    requestObj.fork_info = {
+      fork: {
+        previous_version: toHex(forkInfo.prevVersion),
+        current_version: toHex(forkInfo.version),
+        epoch: String(computeEpochAtSlot(signingSlot)),
+      },
+      genesis_validators_root: toRootHex(config.genesisValidatorsRoot),
+    };
+  }
+
+  const res = await fetch(`${externalSignerUrl}/api/v1/eth2/sign/${pubkeyHex}`, {
+    method: "POST",
+    headers: {
+      Accept: MediaType.json,
+      "Content-Type": MediaType.json,
+    },
+    body: JSON.stringify(requestObj),
+  });
+
+  const data = await handleExternalSignerResponse<{signature: string}>(res);
+  return data.signature;
+}
+
+/**
+ * Return upcheck status from server.
+ */
+export async function externalSignerUpCheck(remoteUrl: string): Promise<boolean> {
+  const res = await fetch(`${remoteUrl}/upcheck`, {
+    method: "GET",
+    headers: {Accept: MediaType.json},
+  });
+
+  const data = await handleExternalSignerResponse<{status: string}>(res);
+  return data.status === "OK";
+}
+
+async function handleExternalSignerResponse<T>(res: Response): Promise<T> {
+  if (!res.ok) {
+    const errBody = await res.text();
+    throw Error(errBody || res.statusText);
+  }
+
+  const contentType = res.headers.get("content-type");
+  if (contentType === null) {
+    throw Error("No Content-Type header found in response");
+  }
+
+  const mediaType = contentType.split(";", 1)[0].trim().toLowerCase();
+  if (mediaType !== MediaType.json) {
+    throw Error(`Unsupported response media type: ${mediaType}`);
+  }
+
+  try {
+    return (await res.json()) as T;
+  } catch (e) {
+    throw Error(`Invalid json response: ${(e as Error).message}`);
+  }
+}
+
+function serializerSignableMessagePayload(config: BeaconConfig, payload: SignableMessage): Record<string, unknown> {
+  switch (payload.type) {
+    case SignableMessageType.AGGREGATION_SLOT:
+      return {aggregation_slot: AggregationSlotType.toJson(payload.data)};
+
+    case SignableMessageType.AGGREGATE_AND_PROOF:
+      return {aggregate_and_proof: ssz.phase0.AggregateAndProof.toJson(payload.data)};
+
+    case SignableMessageType.AGGREGATE_AND_PROOF_V2: {
+      const fork = config.getForkName(payload.data.aggregate.data.slot);
+      return {
+        aggregate_and_proof: {
+          version: fork.toUpperCase(),
+          data: sszTypesFor(fork).AggregateAndProof.toJson(payload.data),
+        },
+      };
+    }
+
+    case SignableMessageType.ATTESTATION:
+      return {attestation: ssz.phase0.AttestationData.toJson(payload.data)};
+
+    // Note: `type: BLOCK` not implemented
+    case SignableMessageType.BLOCK_V2: {
+      const fork = config.getForkInfo(payload.data.slot);
+      // web3signer requires capitalized names: PHASE0, ALTAIR, etc
+      const version = fork.name.toUpperCase();
+      if (fork.seq >= ForkSeq.bellatrix) {
+        return {
+          beacon_block: {
+            version,
+            block_header: ssz.phase0.BeaconBlockHeader.toJson(blindedOrFullBlockToHeader(config, payload.data)),
+          },
+        };
+      }
+
+      return {
+        beacon_block: {
+          version,
+          block: config.getForkTypes(payload.data.slot).BeaconBlock.toJson(payload.data),
+        },
+      };
+    }
+
+    case SignableMessageType.DEPOSIT:
+      return {deposit: DepositType.toJson(payload.data)};
+
+    case SignableMessageType.RANDAO_REVEAL:
+      return {randao_reveal: RandaoRevealType.toJson(payload.data)};
+
+    case SignableMessageType.VOLUNTARY_EXIT:
+      return {voluntary_exit: ssz.phase0.VoluntaryExit.toJson(payload.data)};
+
+    case SignableMessageType.SYNC_COMMITTEE_MESSAGE:
+      return {sync_committee_message: SyncCommitteeMessageType.toJson(payload.data)};
+
+    case SignableMessageType.SYNC_COMMITTEE_SELECTION_PROOF:
+      return {sync_aggregator_selection_data: SyncAggregatorSelectionDataType.toJson(payload.data)};
+
+    case SignableMessageType.SYNC_COMMITTEE_CONTRIBUTION_AND_PROOF:
+      return {contribution_and_proof: ssz.altair.ContributionAndProof.toJson(payload.data)};
+
+    case SignableMessageType.VALIDATOR_REGISTRATION:
+      return {validator_registration: ssz.bellatrix.ValidatorRegistrationV1.toJson(payload.data)};
+
+    case SignableMessageType.BLS_TO_EXECUTION_CHANGE:
+      return {BLS_TO_EXECUTION_CHANGE: ssz.capella.BLSToExecutionChange.toJson(payload.data)};
+  }
+}

package/src/util/format.ts

@@ -0,0 +1,3 @@
+export function isValidatePubkeyHex(pubkeyHex: string): boolean {
+  return /^0x[0-9a-fA-F]{96}$/.test(pubkeyHex);
+}

package/src/util/index.ts

@@ -0,0 +1,6 @@
+export * from "./batch.js";
+export * from "./clock.js";
+export * from "./difference.js";
+export * from "./logger.js";
+export * from "./params.js";
+export * from "./url.js";

package/src/util/logger.ts

@@ -0,0 +1,51 @@
+import {ApiError} from "@lodestar/api";
+import {LogData, Logger, isErrorAborted} from "@lodestar/utils";
+import {IClock} from "./clock.js";
+
+export type LoggerVc = Logger & {
+  isSyncing(e: Error): void;
+};
+
+export function getLoggerVc(logger: Logger, clock: IClock): LoggerVc {
+  let hasLogged = false;
+
+  clock.runEverySlot(async () => {
+    if (hasLogged) hasLogged = false;
+  });
+
+  return {
+    error(message: string, context?: LogData, e?: Error) {
+      if (e) {
+        // Returns true if it's an network error with code 503 = Node is syncing
+        // https://github.com/ethereum/beacon-APIs/blob/e68a954e1b6f6eb5421abf4532c171ce301c6b2e/types/http.yaml#L62
+        if (e instanceof ApiError && e.status === 503) {
+          this.isSyncing(e);
+        }
+        // Only log if arg `e` is not an instance of `ErrorAborted`
+        else if (!isErrorAborted(e)) {
+          logger.error(message, context, e);
+        }
+      } else {
+        logger.error(message, context, e);
+      }
+    },
+
+    // error: logger.error.bind(logger),
+    warn: logger.warn.bind(logger),
+    info: logger.info.bind(logger),
+    verbose: logger.verbose.bind(logger),
+    debug: logger.debug.bind(logger),
+
+    /**
+     * Throttle "node is syncing" errors to not pollute the console too much.
+     * Logs once per slot at most.
+     */
+    isSyncing(e: Error) {
+      if (!hasLogged) {
+        hasLogged = true;
+        // Log the full error message, in case the server returns 503 for some unknown reason
+        logger.warn(`Node is syncing - ${e.message}`);
+      }
+    },
+  };
+}