@lodestar/beacon-node 1.35.0-dev.f80d2d52da → 1.35.0-dev.fd1dac853d

package/src/eth1/eth1MergeBlockTracker.ts

@@ -0,0 +1,328 @@
+import {ChainConfig} from "@lodestar/config";
+import {RootHex} from "@lodestar/types";
+import {Logger, pruneSetToMax, toRootHex} from "@lodestar/utils";
+import {ZERO_HASH_HEX} from "../constants/index.js";
+import {Metrics} from "../metrics/index.js";
+import {enumToIndexMap} from "../util/enum.js";
+import {EthJsonRpcBlockRaw, IEth1Provider, PowMergeBlock, PowMergeBlockTimestamp, TDProgress} from "./interface.js";
+import {dataToRootHex, quantityToBigint, quantityToNum} from "./provider/utils.js";
+
+export enum StatusCode {
+  STOPPED = "STOPPED",
+  SEARCHING = "SEARCHING",
+  FOUND = "FOUND",
+}
+
+type Status =
+  | {code: StatusCode.STOPPED}
+  | {code: StatusCode.SEARCHING}
+  | {code: StatusCode.FOUND; mergeBlock: PowMergeBlock};
+
+/** For metrics, index order = declaration order of StatusCode  */
+const statusCodeIdx = enumToIndexMap(StatusCode);
+
+/**
+ * Bounds `blocksByHashCache` cache, imposing a max distance between highest and lowest block numbers.
+ * In case of extreme forking the cache might grow unbounded.
+ */
+const MAX_CACHE_POW_BLOCKS = 1024;
+
+const MAX_TD_RENDER_VALUE = Number.MAX_SAFE_INTEGER;
+
+export type Eth1MergeBlockTrackerModules = {
+  config: ChainConfig;
+  logger: Logger;
+  signal: AbortSignal;
+  metrics: Metrics | null;
+};
+
+// get_pow_block_at_total_difficulty
+
+/**
+ * Follows the eth1 chain to find a (or multiple?) merge blocks that cross the threshold of total terminal difficulty
+ *
+ * Finding the mergeBlock could be done in demand when proposing pre-merge blocks. However, that would slow block
+ * production during the weeks between BELLATRIX_EPOCH and TTD.
+ */
+export class Eth1MergeBlockTracker {
+  private readonly config: ChainConfig;
+  private readonly logger: Logger;
+  private readonly metrics: Metrics | null;
+
+  private readonly blocksByHashCache = new Map<RootHex, PowMergeBlock>();
+  private readonly intervals: NodeJS.Timeout[] = [];
+
+  private status: Status;
+  private latestEth1Block: PowMergeBlockTimestamp | null = null;
+  private getTerminalPowBlockFromEth1Promise: Promise<PowMergeBlock | null> | null = null;
+  private readonly safeTDFactor: bigint;
+
+  constructor(
+    {config, logger, signal, metrics}: Eth1MergeBlockTrackerModules,
+    private readonly eth1Provider: IEth1Provider
+  ) {
+    this.config = config;
+    this.logger = logger;
+    this.metrics = metrics;
+
+    this.status = {code: StatusCode.STOPPED};
+
+    signal.addEventListener("abort", () => this.close(), {once: true});
+
+    this.safeTDFactor = getSafeTDFactor(this.config.TERMINAL_TOTAL_DIFFICULTY);
+    const scaledTTD = this.config.TERMINAL_TOTAL_DIFFICULTY / this.safeTDFactor;
+
+    // Only run metrics if necessary
+    if (metrics) {
+      // TTD can't be dynamically changed during execution, register metric once
+      metrics.eth1.eth1MergeTTD.set(Number(scaledTTD as bigint));
+      metrics.eth1.eth1MergeTDFactor.set(Number(this.safeTDFactor as bigint));
+
+      metrics.eth1.eth1MergeStatus.addCollect(() => {
+        // Set merge ttd, merge status and merge block status
+        metrics.eth1.eth1MergeStatus.set(statusCodeIdx[this.status.code]);
+
+        if (this.latestEth1Block !== null) {
+          // Set latestBlock stats
+          metrics.eth1.eth1LatestBlockNumber.set(this.latestEth1Block.number);
+          metrics.eth1.eth1LatestBlockTD.set(Number(this.latestEth1Block.totalDifficulty / this.safeTDFactor));
+          metrics.eth1.eth1LatestBlockTimestamp.set(this.latestEth1Block.timestamp);
+        }
+      });
+    }
+  }
+
+  /**
+   * Returns the most recent POW block that satisfies the merge block condition
+   */
+  async getTerminalPowBlock(): Promise<PowMergeBlock | null> {
+    switch (this.status.code) {
+      case StatusCode.STOPPED:
+        // If not module is not polling fetch the mergeBlock explicitly
+        return this.getTerminalPowBlockFromEth1();
+
+      case StatusCode.SEARCHING:
+        // Assume that polling would have found the block
+        return null;
+
+      case StatusCode.FOUND:
+        return this.status.mergeBlock;
+    }
+  }
+
+  getTDProgress(): TDProgress | null {
+    if (this.latestEth1Block === null) {
+      return this.latestEth1Block;
+    }
+
+    const tdDiff = this.config.TERMINAL_TOTAL_DIFFICULTY - this.latestEth1Block.totalDifficulty;
+
+    if (tdDiff > BigInt(0)) {
+      return {
+        ttdHit: false,
+        tdFactor: this.safeTDFactor,
+        tdDiffScaled: Number((tdDiff / this.safeTDFactor) as bigint),
+        ttd: this.config.TERMINAL_TOTAL_DIFFICULTY,
+        td: this.latestEth1Block.totalDifficulty,
+        timestamp: this.latestEth1Block.timestamp,
+      };
+    }
+    return {
+      ttdHit: true,
+    };
+  }
+
+  /**
+   * Get a POW block by hash checking the local cache first
+   */
+  async getPowBlock(powBlockHash: string): Promise<PowMergeBlock | null> {
+    // Check cache first
+    const cachedBlock = this.blocksByHashCache.get(powBlockHash);
+    if (cachedBlock) {
+      return cachedBlock;
+    }
+
+    // Fetch from node
+    const blockRaw = await this.eth1Provider.getBlockByHash(powBlockHash);
+    if (blockRaw) {
+      const block = toPowBlock(blockRaw);
+      this.cacheBlock(block);
+      return block;
+    }
+
+    return null;
+  }
+
+  /**
+   * Should only start polling for mergeBlock if:
+   * - after BELLATRIX_FORK_EPOCH
+   * - Beacon node synced
+   * - head state not isMergeTransitionComplete
+   */
+  startPollingMergeBlock(): void {
+    if (this.status.code !== StatusCode.STOPPED) {
+      return;
+    }
+
+    this.status = {code: StatusCode.SEARCHING};
+    this.logger.info("Starting search for terminal POW block", {
+      TERMINAL_TOTAL_DIFFICULTY: this.config.TERMINAL_TOTAL_DIFFICULTY,
+    });
+
+    const interval = setInterval(() => {
+      // Preemptively try to find merge block and cache it if found.
+      // Future callers of getTerminalPowBlock() will re-use the cached found mergeBlock.
+      this.getTerminalPowBlockFromEth1().catch((e) => {
+        this.logger.error("Error on findMergeBlock", {}, e as Error);
+        this.metrics?.eth1.eth1PollMergeBlockErrors.inc();
+      });
+    }, this.config.SECONDS_PER_ETH1_BLOCK * 1000);
+
+    this.intervals.push(interval);
+  }
+
+  private close(): void {
+    this.intervals.forEach(clearInterval);
+  }
+
+  private async getTerminalPowBlockFromEth1(): Promise<PowMergeBlock | null> {
+    if (!this.getTerminalPowBlockFromEth1Promise) {
+      this.getTerminalPowBlockFromEth1Promise = this.internalGetTerminalPowBlockFromEth1()
+        .then((mergeBlock) => {
+          // Persist found merge block here to affect both caller paths:
+          // - internal searcher
+          // - external caller if STOPPED
+          if (mergeBlock && this.status.code !== StatusCode.FOUND) {
+            if (this.status.code === StatusCode.SEARCHING) {
+              this.close();
+            }
+
+            this.logger.info("Terminal POW block found!", {
+              hash: mergeBlock.blockHash,
+              number: mergeBlock.number,
+              totalDifficulty: mergeBlock.totalDifficulty,
+            });
+
+            this.status = {code: StatusCode.FOUND, mergeBlock};
+            this.metrics?.eth1.eth1MergeBlockDetails.set(
+              {
+                terminalBlockHash: mergeBlock.blockHash,
+                // Convert all number/bigints to string labels
+                terminalBlockNumber: mergeBlock.number.toString(10),
+                terminalBlockTD: mergeBlock.totalDifficulty.toString(10),
+              },
+              1
+            );
+          }
+
+          return mergeBlock;
+        })
+        .finally(() => {
+          this.getTerminalPowBlockFromEth1Promise = null;
+        });
+    } else {
+      // This should no happen, since getTerminalPowBlockFromEth1() should resolve faster than SECONDS_PER_ETH1_BLOCK.
+      // else something is wrong: the el-cl comms are two slow, or the backsearch got stuck in a deep search.
+      this.metrics?.eth1.getTerminalPowBlockPromiseCacheHit.inc();
+    }
+
+    return this.getTerminalPowBlockFromEth1Promise;
+  }
+
+  /**
+   * **internal** + **unsafe** since it can create multiple backward searches that overload the eth1 client.
+   * Must be called in a wrapper to ensure that there's only once concurrent call to this fn.
+   */
+  private async internalGetTerminalPowBlockFromEth1(): Promise<PowMergeBlock | null> {
+    // Search merge block by hash
+    // Terminal block hash override takes precedence over terminal total difficulty
+    const terminalBlockHash = toRootHex(this.config.TERMINAL_BLOCK_HASH);
+    if (terminalBlockHash !== ZERO_HASH_HEX) {
+      const block = await this.getPowBlock(terminalBlockHash);
+      if (block) {
+        return block;
+      }
+      // if a TERMINAL_BLOCK_HASH other than ZERO_HASH is configured and we can't find it, return NONE
+      return null;
+    }
+
+    // Search merge block by TTD
+    const latestBlockRaw = await this.eth1Provider.getBlockByNumber("latest");
+    if (!latestBlockRaw) {
+      throw Error("getBlockByNumber('latest') returned null");
+    }
+
+    let block = toPowBlock(latestBlockRaw);
+    this.latestEth1Block = {...block, timestamp: quantityToNum(latestBlockRaw.timestamp)};
+    this.cacheBlock(block);
+
+    // This code path to look backwards for the merge block is only necessary if:
+    // - The network has not yet found the merge block
+    // - There are descendants of the merge block in the eth1 chain
+    // For the search below to require more than a few hops, multiple block proposers in a row must fail to detect
+    // an existing merge block. Such situation is extremely unlikely, so this search is left un-optimized. Since
+    // this class can start eagerly looking for the merge block when not necessary, startPollingMergeBlock() should
+    // only be called when there is certainty that a mergeBlock search is necessary.
+
+    while (true) {
+      if (block.totalDifficulty < this.config.TERMINAL_TOTAL_DIFFICULTY) {
+        // TTD not reached yet
+        return null;
+      }
+
+      // else block.totalDifficulty >= this.config.TERMINAL_TOTAL_DIFFICULTY
+      // Potential mergeBlock! Must find the first block that passes TTD
+
+      // Allow genesis block to reach TTD https://github.com/ethereum/consensus-specs/pull/2719
+      if (block.parentHash === ZERO_HASH_HEX) {
+        return block;
+      }
+
+      const parent = await this.getPowBlock(block.parentHash);
+      if (!parent) {
+        throw Error(`Unknown parent of block with TD>TTD ${block.parentHash}`);
+      }
+
+      this.metrics?.eth1.eth1ParentBlocksFetched.inc();
+
+      // block.td > TTD && parent.td < TTD => block is mergeBlock
+      if (parent.totalDifficulty < this.config.TERMINAL_TOTAL_DIFFICULTY) {
+        // Is terminal total difficulty block AND has verified block -> parent relationship
+        return block;
+      }
+      block = parent;
+    }
+  }
+
+  private cacheBlock(block: PowMergeBlock): void {
+    this.blocksByHashCache.set(block.blockHash, block);
+    pruneSetToMax(this.blocksByHashCache, MAX_CACHE_POW_BLOCKS);
+  }
+}
+
+export function toPowBlock(block: EthJsonRpcBlockRaw): PowMergeBlock {
+  // Validate untrusted data from API
+  return {
+    number: quantityToNum(block.number),
+    blockHash: dataToRootHex(block.hash),
+    parentHash: dataToRootHex(block.parentHash),
+    totalDifficulty: quantityToBigint(block.totalDifficulty),
+  };
+}
+
+/**
+ * TTD values can be very large, for xDAI > 1e45. So scale down.
+ * To be good, TTD should be rendered as a number < Number.MAX_TD_RENDER_VALUE ~= 9e15
+ */
+export function getSafeTDFactor(ttd: bigint): bigint {
+  const safeIntegerMult = ttd / BigInt(MAX_TD_RENDER_VALUE);
+
+  // TTD < MAX_TD_RENDER_VALUE, no need to scale down
+  if (safeIntegerMult === BigInt(0)) {
+    return BigInt(1);
+  }
+
+  // Return closest power of 10 to ensure TD < max
+  const safeIntegerMultDigits = safeIntegerMult.toString(10).length;
+  return BigInt(10) ** BigInt(safeIntegerMultDigits);
+}

package/src/eth1/index.ts

@@ -0,0 +1,157 @@
+import {CachedBeaconStateAllForks} from "@lodestar/state-transition";
+import {Root} from "@lodestar/types";
+import {fromHex} from "@lodestar/utils";
+import {Eth1DepositDataTracker, Eth1DepositDataTrackerModules} from "./eth1DepositDataTracker.js";
+import {Eth1MergeBlockTracker, Eth1MergeBlockTrackerModules} from "./eth1MergeBlockTracker.js";
+import {Eth1DataAndDeposits, IEth1ForBlockProduction, IEth1Provider, PowMergeBlock, TDProgress} from "./interface.js";
+import {Eth1Options} from "./options.js";
+import {Eth1Provider} from "./provider/eth1Provider.js";
+export {Eth1Provider};
+export type {IEth1ForBlockProduction, IEth1Provider};
+
+// This module encapsulates all consumer functionality to the execution node (formerly eth1). The execution client
+// has to:
+//
+// - For genesis, the beacon node must follow the eth1 chain: get all deposit events + blocks within that range.
+//   Once the genesis conditions are met, start the POS chain with the resulting state. The logic is similar to the
+//   two points below, but the implementation is specialized for each scenario.
+//
+// - Follow the eth1 block chain to validate eth1Data votes. It needs all consecutive blocks within a specific range
+//   and at a distance from the head.
+//   ETH1_FOLLOW_DISTANCE 	        uint64(2**11) (= 2,048) 	Eth1 blocks 	~8 hours
+//   EPOCHS_PER_ETH1_VOTING_PERIOD 	uint64(2**6) (= 64)     	epochs 	      ~6.8 hours
+//
+// - Fetch ALL deposit events from the deposit contract to build the deposit tree and validate future merkle proofs.
+//   Then it must follow deposit events at a distance roughly similar to the `ETH1_FOLLOW_DISTANCE` parameter above.
+//
+// - [New bellatrix]: After BELLATRIX_FORK_EPOCH, it must fetch the block with hash
+//   `state.eth1_data.block_hash` to compute `terminal_total_difficulty`. Note this may change with
+//   https://github.com/ethereum/consensus-specs/issues/2603.
+//
+// - [New bellatrix]: On block production post BELLATRIX_FORK_EPOCH, pre merge, the beacon node must find the merge block
+//   crossing the `terminal_total_difficulty` boundary and include it in the block. After the merge block production
+//   will just use `execution_engine.assemble_block` without fetching individual blocks.
+//
+// - [New bellatrix]: Fork-choice must validate the merge block ensuring it crossed the `terminal_total_difficulty`
+//   boundary, so it must fetch the POW block referenced in the merge block + its POW parent block.
+//
+// With the merge the beacon node has to follow the eth1 chain at two distances:
+// 1. At `ETH1_FOLLOW_DISTANCE` for eth1Data to be re-org safe
+// 2. At the head to get the first merge block, tolerating possible re-orgs
+//
+// Then both streams of blocks should not be merged since it's harder to guard against re-orgs from (2) to (1).
+
+export function initializeEth1ForBlockProduction(
+  opts: Eth1Options,
+  modules: Pick<Eth1DepositDataTrackerModules, "db" | "config" | "metrics" | "logger" | "signal">
+): IEth1ForBlockProduction {
+  if (opts.enabled) {
+    return new Eth1ForBlockProduction(opts, {
+      config: modules.config,
+      db: modules.db,
+      metrics: modules.metrics,
+      logger: modules.logger,
+      signal: modules.signal,
+    });
+  }
+  return new Eth1ForBlockProductionDisabled();
+}
+
+export class Eth1ForBlockProduction implements IEth1ForBlockProduction {
+  private readonly eth1DepositDataTracker: Eth1DepositDataTracker | null;
+  private readonly eth1MergeBlockTracker: Eth1MergeBlockTracker;
+
+  constructor(
+    opts: Eth1Options,
+    modules: Eth1DepositDataTrackerModules & Eth1MergeBlockTrackerModules & {eth1Provider?: IEth1Provider}
+  ) {
+    const eth1Provider =
+      modules.eth1Provider ||
+      new Eth1Provider(
+        modules.config,
+        {...opts, logger: modules.logger},
+        modules.signal,
+        modules.metrics?.eth1HttpClient
+      );
+
+    this.eth1DepositDataTracker = opts.disableEth1DepositDataTracker
+      ? null
+      : new Eth1DepositDataTracker(opts, modules, eth1Provider);
+
+    this.eth1MergeBlockTracker = new Eth1MergeBlockTracker(modules, eth1Provider);
+  }
+
+  async getEth1DataAndDeposits(state: CachedBeaconStateAllForks): Promise<Eth1DataAndDeposits> {
+    if (this.eth1DepositDataTracker === null) {
+      return {eth1Data: state.eth1Data, deposits: []};
+    }
+    return this.eth1DepositDataTracker.getEth1DataAndDeposits(state);
+  }
+
+  async getTerminalPowBlock(): Promise<Root | null> {
+    const block = await this.eth1MergeBlockTracker.getTerminalPowBlock();
+    return block && fromHex(block.blockHash);
+  }
+
+  getPowBlock(powBlockHash: string): Promise<PowMergeBlock | null> {
+    return this.eth1MergeBlockTracker.getPowBlock(powBlockHash);
+  }
+
+  getTDProgress(): TDProgress | null {
+    return this.eth1MergeBlockTracker.getTDProgress();
+  }
+
+  startPollingMergeBlock(): void {
+    this.eth1MergeBlockTracker.startPollingMergeBlock();
+  }
+
+  isPollingEth1Data(): boolean {
+    return this.eth1DepositDataTracker?.isPollingEth1Data() ?? false;
+  }
+
+  stopPollingEth1Data(): void {
+    this.eth1DepositDataTracker?.stopPollingEth1Data();
+  }
+}
+
+/**
+ * Disabled version of Eth1ForBlockProduction
+ * May produce invalid blocks by not adding new deposits and voting for the same eth1Data
+ */
+export class Eth1ForBlockProductionDisabled implements IEth1ForBlockProduction {
+  /**
+   * Returns same eth1Data as in state and no deposits
+   * May produce invalid blocks if deposits have to be added
+   */
+  async getEth1DataAndDeposits(state: CachedBeaconStateAllForks): Promise<Eth1DataAndDeposits> {
+    return {eth1Data: state.eth1Data, deposits: []};
+  }
+
+  /**
+   * Will miss the oportunity to propose the merge block but will still produce valid blocks
+   */
+  async getTerminalPowBlock(): Promise<Root | null> {
+    return null;
+  }
+
+  /** Will not be able to validate the merge block */
+  async getPowBlock(_powBlockHash: string): Promise<PowMergeBlock | null> {
+    throw Error("eth1 must be enabled to verify merge block");
+  }
+
+  getTDProgress(): TDProgress | null {
+    return null;
+  }
+
+  isPollingEth1Data(): boolean {
+    return false;
+  }
+
+  startPollingMergeBlock(): void {
+    // Ignore
+  }
+
+  stopPollingEth1Data(): void {
+    // Ignore
+  }
+}

package/src/eth1/interface.ts

@@ -0,0 +1,131 @@
+import {BeaconConfig} from "@lodestar/config";
+import {CachedBeaconStateAllForks} from "@lodestar/state-transition";
+import {Root, RootHex, phase0} from "@lodestar/types";
+
+export type EthJsonRpcBlockRaw = {
+  /** the block number. null when its pending block. `"0x1b4"` */
+  number: string;
+  /** 32 Bytes - hash of the block. null when its pending block. `"0xdc0818cf78f21a8e70579cb46a43643f78291264dda342ae31049421c82d21ae"` */
+  hash: string;
+  /** 32 Bytes - hash of the parent block. `"0xe99e022112df268087ea7eafaf4790497fd21dbeeb6bd7a1721df161a6657a54"` */
+  parentHash: string;
+  /**
+   * integer of the total difficulty of the chain until this block. `"0x78ed983323d"`.
+   * Current mainnet value is 0x684de10dc5c03f006b6, 75 bits so requires a bigint.
+   */
+  totalDifficulty: string;
+  /** the unix timestamp for when the block was collated. `"0x55ba467c"` */
+  timestamp: string;
+};
+
+export interface IEth1Provider {
+  deployBlock: number;
+  getBlockNumber(): Promise<number>;
+  /** Returns HTTP code 200 + value=null if block is not found */
+  getBlockByNumber(blockNumber: number | "latest"): Promise<EthJsonRpcBlockRaw | null>;
+  /** Returns HTTP code 200 + value=null if block is not found */
+  getBlockByHash(blockHashHex: string): Promise<EthJsonRpcBlockRaw | null>;
+  /** null returns are ignored, may return a different number of blocks than expected */
+  getBlocksByNumber(fromBlock: number, toBlock: number): Promise<EthJsonRpcBlockRaw[]>;
+  getDepositEvents(fromBlock: number, toBlock: number): Promise<phase0.DepositEvent[]>;
+  validateContract(): Promise<void>;
+  getState(): Eth1ProviderState;
+}
+
+export enum Eth1ProviderState {
+  ONLINE = "ONLINE",
+  OFFLINE = "OFFLINE",
+  ERROR = "ERROR",
+  AUTH_FAILED = "AUTH_FAILED",
+}
+
+export type Eth1DataAndDeposits = {
+  eth1Data: phase0.Eth1Data;
+  deposits: phase0.Deposit[];
+};
+
+export interface IEth1ForBlockProduction {
+  getEth1DataAndDeposits(state: CachedBeaconStateAllForks): Promise<Eth1DataAndDeposits>;
+
+  /** Returns the most recent POW block that satisfies the merge block condition */
+  getTerminalPowBlock(): Promise<Root | null>;
+  /** Get a POW block by hash checking the local cache first */
+  getPowBlock(powBlockHash: string): Promise<PowMergeBlock | null>;
+
+  /** Get current TD progress for log notifier */
+  getTDProgress(): TDProgress | null;
+
+  /**
+   * Should only start polling for mergeBlock if:
+   * - after BELLATRIX_FORK_EPOCH
+   * - Beacon node synced
+   * - head state not isMergeTransitionComplete
+   */
+  startPollingMergeBlock(): void;
+
+  isPollingEth1Data(): boolean;
+
+  /**
+   * Should stop polling eth1Data after a Electra block is finalized AND deposit_requests_start_index is reached
+   */
+  stopPollingEth1Data(): void;
+}
+
+/** Different Eth1Block from phase0.Eth1Block with blockHash */
+export type Eth1Block = {
+  blockHash: Uint8Array;
+  blockNumber: number;
+  timestamp: number;
+};
+
+export type PowMergeBlock = {
+  number: number;
+  blockHash: RootHex;
+  parentHash: RootHex;
+  totalDifficulty: bigint;
+};
+
+export type PowMergeBlockTimestamp = PowMergeBlock & {
+  /** in seconds */
+  timestamp: number;
+};
+
+export type TDProgress =
+  | {
+      ttdHit: false;
+      /** Power of ten by which tdDiffScaled is scaled down */
+      tdFactor: bigint;
+      /** (TERMINAL_TOTAL_DIFFICULTY - block.totalDifficulty) / tdFactor */
+      tdDiffScaled: number;
+      /** TERMINAL_TOTAL_DIFFICULTY */
+      ttd: bigint;
+      /** totalDifficulty of latest fetched eth1 block */
+      td: bigint;
+      /** timestamp in sec of latest fetched eth1 block */
+      timestamp: number;
+    }
+  | {ttdHit: true};
+
+export type BatchDepositEvents = {
+  depositEvents: phase0.DepositEvent[];
+  blockNumber: number;
+};
+
+export type Eth1Streamer = {
+  getDepositsStream(fromBlock: number): AsyncGenerator<BatchDepositEvents>;
+  getDepositsAndBlockStreamForGenesis(fromBlock: number): AsyncGenerator<[phase0.DepositEvent[], phase0.Eth1Block]>;
+};
+
+export type IEth1StreamParams = Pick<
+  BeaconConfig,
+  "ETH1_FOLLOW_DISTANCE" | "MIN_GENESIS_TIME" | "GENESIS_DELAY" | "SECONDS_PER_ETH1_BLOCK"
+> & {
+  maxBlocksPerPoll: number;
+};
+
+export type IJson = string | number | boolean | undefined | IJson[] | {[key: string]: IJson};
+
+export interface RpcPayload<P = IJson[]> {
+  method: string;
+  params: P;
+}

package/src/eth1/options.ts

@@ -0,0 +1,28 @@
+export type Eth1Options = {
+  enabled?: boolean;
+  disableEth1DepositDataTracker?: boolean;
+  providerUrls?: string[];
+  /**
+   * jwtSecretHex is the jwt secret if the eth1 modules should ping the jwt auth
+   * protected engine endpoints.
+   */
+  jwtSecretHex?: string;
+  jwtId?: string;
+  jwtVersion?: string;
+  depositContractDeployBlock?: number;
+  unsafeAllowDepositDataOverwrite?: boolean;
+  /**
+   * Vote for a specific eth1_data regardless of validity and existing votes.
+   * hex encoded ssz serialized Eth1Data type.
+   */
+  forcedEth1DataVote?: string;
+};
+
+export const DEFAULT_PROVIDER_URLS = ["http://localhost:8545"];
+
+export const defaultEth1Options: Eth1Options = {
+  enabled: true,
+  providerUrls: DEFAULT_PROVIDER_URLS,
+  depositContractDeployBlock: 0,
+  unsafeAllowDepositDataOverwrite: false,
+};