@chainsafe/lodestar 1.35.0-dev.8644a83c62 → 1.35.0-dev.8961b06c11

package/src/applyPreset.ts

@@ -0,0 +1,92 @@
+// MUST import this file first before anything and not import any Lodestar code.
+
+import {hasher as hashtreeHasher} from "#hashtree-hasher";
+import {setHasher} from "@chainsafe/persistent-merkle-tree";
+
+// Without setting this first, persistent-merkle-tree will use noble instead
+setHasher(hashtreeHasher);
+
+//
+// ## Rationale
+//
+// Lodestar implemented PRESET / CONFIG separation to allow importing types and preset constants directly
+// see https://github.com/ChainSafe/lodestar/pull/2585
+//
+// However this prevents dynamic configuration changes which is exactly what the CLI required before.
+// - The dev command can't apply the minimal preset dynamically
+// - `--network gnosis` can't apply a different preset dynamically
+// - `--network chiado` can't apply a different preset dynamically
+//
+// Running this file allows us to keep a static export strategy while NOT requiring users to
+// set LODESTAR_PRESET manually every time.
+
+// IMPORTANT: only import Lodestar code here which does not import any other Lodestar libraries
+import {PresetName, presetFromJson, setActivePreset} from "@lodestar/params/setPreset";
+import {readFile} from "./util/file.js";
+
+const network = valueOfArg("network");
+const preset = valueOfArg("preset");
+const presetFile = valueOfArg("presetFile");
+
+// Apply preset flag if present
+if (preset) {
+  process.env.LODESTAR_PRESET = preset;
+}
+
+// If ENV is set overrides, network (otherwise can not override network --dev in mainnet mode)
+else if (process.env.LODESTAR_PRESET) {
+  // break
+}
+
+// Translate network to preset
+else if (network) {
+  if (network === "dev") {
+    process.env.LODESTAR_PRESET = "minimal";
+    // the kzg library has hardcoded the mainnet value, do not use presets
+    setActivePreset(PresetName.minimal, {FIELD_ELEMENTS_PER_BLOB: 4096});
+  } else if (network === "gnosis" || network === "chiado") {
+    process.env.LODESTAR_PRESET = "gnosis";
+  }
+}
+
+// If running dev top level command `$ lodestar dev`, apply minimal
+else if (process.argv[2] === "dev") {
+  process.env.LODESTAR_PRESET = "minimal";
+  process.env.LODESTAR_NETWORK = "dev";
+  // the kzg library has hardcoded the mainnet value, do not use presets
+  setActivePreset(PresetName.minimal, {FIELD_ELEMENTS_PER_BLOB: 4096});
+}
+
+if (presetFile) {
+  // Override the active preset with custom values from file
+  // Do not modify the preset to use as a base by passing null
+  setActivePreset(null, presetFromJson(readFile(presetFile) ?? {}));
+}
+
+/**
+ * Valid syntax
+ * - `--preset minimal`
+ * - `--preset=minimal`
+ */
+function valueOfArg(argName: string): string | null {
+  // Syntax `--preset minimal`
+  // process.argv = ["--preset", "minimal"];
+
+  {
+    const index = process.argv.indexOf(`--${argName}`);
+    if (index > -1) {
+      return process.argv[index + 1] ?? "";
+    }
+  }
+
+  // Syntax `--preset=minimal`
+  {
+    const prefix = `--${argName}=`;
+    const item = process.argv.find((arg) => arg.startsWith(prefix));
+    if (item) {
+      return item.slice(prefix.length);
+    }
+  }
+
+  return null;
+}

package/src/cli.ts

@@ -0,0 +1,56 @@
+// Must not use `* as yargs`, see https://github.com/yargs/yargs/issues/1131
+import yargs, {Argv} from "yargs";
+import {hideBin} from "yargs/helpers";
+import {registerCommandToYargs} from "@lodestar/utils";
+import {cmds} from "./cmds/index.js";
+import {globalOptions, rcConfigOption} from "./options/index.js";
+import {getVersionData} from "./util/version.js";
+
+const {version} = getVersionData();
+const topBanner = `🌟 Lodestar: TypeScript Implementation of the Ethereum Consensus Beacon Chain.
+  * Version: ${version}
+  * by ChainSafe Systems, 2018-${new Date().getFullYear()}`;
+const bottomBanner = `📖 For more information, check the CLI reference:
+  * https://chainsafe.github.io/lodestar/reference/cli
+
+✍️ Give feedback and report issues on GitHub:
+  * https://github.com/ChainSafe/lodestar`;
+
+export const yarg = yargs((hideBin as (args: string[]) => string[])(process.argv));
+
+/**
+ * Common factory for running the CLI and running integration tests
+ * The CLI must actually be executed in a different script
+ */
+export function getLodestarCli(): Argv {
+  const lodestar = yarg
+    .env("LODESTAR")
+    .parserConfiguration({
+      // As of yargs v16.1.0 dot-notation breaks strictOptions()
+      // Manually processing options is typesafe tho more verbose
+      "dot-notation": false,
+    })
+    .options(globalOptions)
+    // blank scriptName so that help text doesn't display the cli name before each command
+    .scriptName("")
+    .demandCommand(1)
+    // Control show help behaviour below on .fail()
+    .showHelpOnFail(false)
+    .usage(topBanner)
+    .epilogue(bottomBanner)
+    .version(topBanner)
+    .alias("h", "help")
+    .alias("v", "version")
+    .recommendCommands();
+
+  // yargs.command and all ./cmds
+  for (const cmd of cmds) {
+    registerCommandToYargs(lodestar, cmd);
+  }
+
+  // throw an error if we see an unrecognized cmd
+  lodestar.recommendCommands().strict();
+  lodestar.config(...rcConfigOption);
+
+  return lodestar;
+}

package/src/cmds/beacon/handler.ts

@@ -0,0 +1,267 @@
+import path from "node:path";
+import {getHeapStatistics} from "node:v8";
+import {SignableENR} from "@chainsafe/enr";
+import {hasher} from "@chainsafe/persistent-merkle-tree";
+import {BeaconDb, BeaconNode} from "@lodestar/beacon-node";
+import {ChainForkConfig, createBeaconConfig} from "@lodestar/config";
+import {LevelDbController} from "@lodestar/db/controller/level";
+import {LoggerNode, getNodeLogger} from "@lodestar/logger/node";
+import {ACTIVE_PRESET, PresetName} from "@lodestar/params";
+import {ErrorAborted, bytesToInt} from "@lodestar/utils";
+import {ProcessShutdownCallback} from "@lodestar/validator";
+import {BeaconNodeOptions, getBeaconConfigFromArgs} from "../../config/index.js";
+import {getNetworkBootnodes, getNetworkData, isKnownNetworkName, readBootnodes} from "../../networks/index.js";
+import {GlobalArgs, parseBeaconNodeArgs} from "../../options/index.js";
+import {LogArgs} from "../../options/logOptions.js";
+import {
+  cleanOldLogFiles,
+  mkdir,
+  onGracefulShutdown,
+  parseLoggerArgs,
+  pruneOldFilesInDir,
+  writeFile600Perm,
+} from "../../util/index.js";
+import {getVersionData} from "../../util/version.js";
+import {initBeaconState} from "./initBeaconState.js";
+import {initPrivateKeyAndEnr} from "./initPeerIdAndEnr.js";
+import {BeaconArgs} from "./options.js";
+import {getBeaconPaths} from "./paths.js";
+
+const DEFAULT_RETENTION_SSZ_OBJECTS_HOURS = 15 * 24;
+const HOURS_TO_MS = 3600 * 1000;
+const EIGHT_GB = 8 * 1024 * 1024 * 1024;
+
+/**
+ * Runs a beacon node.
+ */
+export async function beaconHandler(args: BeaconArgs & GlobalArgs): Promise<void> {
+  const {config, options, beaconPaths, network, version, commit, privateKey, logger} = await beaconHandlerInit(args);
+
+  if (hasher.name !== "hashtree") {
+    logger.warn(`hashtree is not supported, using hasher ${hasher.name}`);
+  }
+
+  const heapSizeLimit = getHeapStatistics().heap_size_limit;
+  if (heapSizeLimit < EIGHT_GB) {
+    logger.warn(
+      `Node.js heap size limit is too low, consider increasing it to at least ${EIGHT_GB}. See https://chainsafe.github.io/lodestar/faqs/#running-a-beacon-node for more details.`
+    );
+  }
+
+  // initialize directories
+  mkdir(beaconPaths.dataDir);
+  mkdir(beaconPaths.beaconDir);
+  mkdir(beaconPaths.dbDir);
+
+  const abortController = new AbortController();
+
+  logger.info("Lodestar", {network, version, commit});
+  // Callback for beacon to request forced exit, for e.g. in case of irrecoverable
+  // forkchoice errors
+  const processShutdownCallback: ProcessShutdownCallback = (err) => {
+    logger.error("Process shutdown requested", {}, err);
+    process.kill(process.pid, "SIGINT");
+  };
+
+  if (ACTIVE_PRESET === PresetName.minimal) logger.info("ACTIVE_PRESET == minimal preset");
+
+  const db = new BeaconDb(config, await LevelDbController.create(options.db, {metrics: null, logger}));
+  logger.info("Connected to LevelDB database", {path: options.db.name});
+
+  // BeaconNode setup
+  try {
+    const {anchorState, wsCheckpoint} = await initBeaconState(
+      options,
+      args,
+      config,
+      db,
+      logger,
+      abortController.signal
+    );
+    const beaconConfig = createBeaconConfig(config, anchorState.genesisValidatorsRoot);
+    const node = await BeaconNode.init({
+      opts: options,
+      config: beaconConfig,
+      db,
+      logger,
+      processShutdownCallback,
+      privateKey,
+      dataDir: beaconPaths.dataDir,
+      peerStoreDir: beaconPaths.peerStoreDir,
+      anchorState,
+      wsCheckpoint,
+    });
+
+    // dev debug option to have access to the BN instance
+    if (args.attachToGlobalThis) {
+      (globalThis as unknown as {bn: BeaconNode}).bn = node;
+    }
+
+    // Prune invalid SSZ objects every interval
+    const {persistInvalidSszObjectsDir, persistInvalidSszObjects} = options.chain;
+    const pruneInvalidSSZObjectsInterval =
+      persistInvalidSszObjectsDir && persistInvalidSszObjects
+        ? setInterval(() => {
+            try {
+              const deletedFileCount = pruneOldFilesInDir(
+                persistInvalidSszObjectsDir,
+                (args.persistInvalidSszObjectsRetentionHours ?? DEFAULT_RETENTION_SSZ_OBJECTS_HOURS) * HOURS_TO_MS
+              );
+              logger.info("Pruned invalid SSZ objects", {deletedFileCount});
+            } catch (e) {
+              logger.warn("Error pruning invalid SSZ objects", {persistInvalidSszObjectsDir}, e as Error);
+            }
+            // Run every ~1 hour
+          }, HOURS_TO_MS)
+        : null;
+
+    // Intercept SIGINT signal, to perform final ops before exiting
+    onGracefulShutdown(async () => {
+      if (args.persistNetworkIdentity) {
+        try {
+          const networkIdentity = await node.network.getNetworkIdentity();
+          const enrPath = path.join(beaconPaths.beaconDir, "enr");
+          writeFile600Perm(enrPath, networkIdentity.enr);
+        } catch (e) {
+          logger.warn("Unable to persist enr", {}, e as Error);
+        }
+      }
+      abortController.abort();
+
+      if (pruneInvalidSSZObjectsInterval !== null) {
+        clearInterval(pruneInvalidSSZObjectsInterval);
+      }
+    }, logger.info.bind(logger));
+
+    abortController.signal.addEventListener(
+      "abort",
+      async () => {
+        try {
+          await node.close();
+          logger.debug("Beacon node closed");
+          // Explicitly exit until active handles issue is resolved
+          // See https://github.com/ChainSafe/lodestar/issues/5642
+          process.exit(0);
+        } catch (e) {
+          logger.error("Error closing beacon node", {}, e as Error);
+          // Make sure db is always closed gracefully
+          await db.close();
+          // Must explicitly exit process due to potential active handles
+          process.exit(1);
+        }
+      },
+      {once: true}
+    );
+  } catch (e) {
+    await db.close();
+
+    if (e instanceof ErrorAborted) {
+      logger.info(e.message); // Let the user know the abort was received but don't print as error
+    } else {
+      throw e;
+    }
+  }
+}
+
+/** Separate function to simplify unit testing of options merging */
+export async function beaconHandlerInit(args: BeaconArgs & GlobalArgs) {
+  const {config, network} = getBeaconConfigFromArgs(args);
+
+  const beaconNodeOptions = new BeaconNodeOptions(parseBeaconNodeArgs(args));
+
+  const {version, commit} = getVersionData();
+  const beaconPaths = getBeaconPaths(args, network);
+  // TODO: Rename db.name to db.path or db.location
+  beaconNodeOptions.set({db: {name: beaconPaths.dbDir}});
+  beaconNodeOptions.set({
+    chain: {
+      validatorMonitorLogs: args.validatorMonitorLogs,
+      persistInvalidSszObjectsDir: beaconPaths.persistInvalidSszObjectsDir,
+      persistOrphanedBlocksDir: beaconPaths.persistOrphanedBlocksDir,
+    },
+  });
+  // Add metrics metadata to show versioning + network info in Prometheus + Grafana
+  beaconNodeOptions.set({metrics: {metadata: {version, commit, network}}});
+  // Add detailed version string for API node/version endpoint
+  beaconNodeOptions.set({api: {commit, version}});
+
+  if (args.supernode) {
+    beaconNodeOptions.set({chain: {supernode: true}, network: {supernode: true}});
+  }
+
+  // Set known depositContractDeployBlock
+  if (isKnownNetworkName(network)) {
+    const {depositContractDeployBlock} = getNetworkData(network);
+    beaconNodeOptions.set({eth1: {depositContractDeployBlock}});
+  }
+
+  const logger = initLogger(args, beaconPaths.dataDir, config);
+  const {privateKey, enr} = await initPrivateKeyAndEnr(args, beaconPaths.beaconDir, logger);
+
+  if (args.discv5 !== false) {
+    // Inject ENR to beacon options
+    beaconNodeOptions.set({network: {discv5: {enr: enr.encodeTxt(), config: {enrUpdate: !enr.ip && !enr.ip6}}}});
+
+    // Combine bootnodes from different sources
+    const bootnodes = (beaconNodeOptions.get().network?.discv5?.bootEnrs ?? []).concat(
+      args.bootnodesFile ? readBootnodes(args.bootnodesFile) : [],
+      isKnownNetworkName(network) ? await getNetworkBootnodes(network) : []
+    );
+    // Deduplicate and set combined bootnodes
+    beaconNodeOptions.set({network: {discv5: {bootEnrs: [...new Set(bootnodes)]}}});
+  }
+
+  beaconNodeOptions.set({chain: {initialCustodyGroupCount: getInitialCustodyGroupCount(args, config, enr)}});
+
+  if (args.disableLightClientServer) {
+    beaconNodeOptions.set({chain: {disableLightClientServer: true}});
+  }
+
+  if (args.private) {
+    beaconNodeOptions.set({network: {private: true}, api: {private: true}});
+  } else {
+    const versionStr = `Lodestar/${version}`;
+    const simpleVersionStr = version.split("/")[0];
+    // Add simple version string for libp2p agent version
+    beaconNodeOptions.set({network: {version: simpleVersionStr}});
+    // Add User-Agent header to all builder requests
+    beaconNodeOptions.set({executionBuilder: {userAgent: versionStr}});
+    // Set jwt version with version string
+    beaconNodeOptions.set({executionEngine: {jwtVersion: versionStr}, eth1: {jwtVersion: versionStr}});
+    // Set commit and version for ClientVersion
+    beaconNodeOptions.set({executionEngine: {commit, version}});
+  }
+
+  // Render final options
+  const options = beaconNodeOptions.getWithDefaults();
+
+  return {config, options, beaconPaths, network, version, commit, privateKey, logger};
+}
+
+export function initLogger(
+  args: LogArgs & Pick<GlobalArgs, "dataDir">,
+  dataDir: string,
+  config: ChainForkConfig,
+  fileName = "beacon.log"
+): LoggerNode {
+  const defaultLogFilepath = path.join(dataDir, fileName);
+  const logger = getNodeLogger(parseLoggerArgs(args, {defaultLogFilepath}, config));
+  try {
+    cleanOldLogFiles(args, {defaultLogFilepath});
+  } catch (e) {
+    logger.debug("Not able to delete log files", {}, e as Error);
+  }
+
+  return logger;
+}
+
+function getInitialCustodyGroupCount(args: BeaconArgs & GlobalArgs, config: ChainForkConfig, enr: SignableENR): number {
+  if (args.supernode) {
+    return config.NUMBER_OF_CUSTODY_GROUPS;
+  }
+
+  const enrCgcBytes = enr.kvs.get("cgc");
+  const enrCgc = enrCgcBytes != null ? bytesToInt(enrCgcBytes, "be") : 0;
+
+  return Math.max(enrCgc, config.CUSTODY_REQUIREMENT);
+}

package/src/cmds/beacon/index.ts

@@ -0,0 +1,18 @@
+import {CliCommand, CliCommandOptions} from "@lodestar/utils";
+import {GlobalArgs} from "../../options/index.js";
+import {beaconHandler} from "./handler.js";
+import {BeaconArgs, beaconOptions} from "./options.js";
+
+export const beacon: CliCommand<BeaconArgs, GlobalArgs> = {
+  command: "beacon",
+  describe: "Run a beacon chain node",
+  docsFolder: "run/beacon-management",
+  examples: [
+    {
+      command: "beacon --network hoodi",
+      description: "Run a beacon chain node and connect to the hoodi testnet",
+    },
+  ],
+  options: beaconOptions as CliCommandOptions<BeaconArgs>,
+  handler: beaconHandler,
+};