@lodestar/config 1.35.0-dev.b42a298a7c → 1.35.0-dev.ba92bd8a88

package/src/chainConfig/json.ts

@@ -0,0 +1,175 @@
+import {fromHex, toHex} from "@lodestar/utils";
+import {validateBlobSchedule} from "../utils/validateBlobSchedule.js";
+import {
+  BlobSchedule,
+  BlobScheduleEntry,
+  ChainConfig,
+  SpecJson,
+  SpecValue,
+  SpecValueTypeName,
+  chainConfigTypes,
+  isBlobSchedule,
+} from "./types.js";
+
+const MAX_UINT64_JSON = "18446744073709551615";
+
+export function chainConfigToJson(config: ChainConfig): SpecJson {
+  const json: SpecJson = {};
+
+  for (const key of Object.keys(chainConfigTypes) as (keyof ChainConfig)[]) {
+    const value = config[key];
+    if (value !== undefined) {
+      json[key] = serializeSpecValue(value, chainConfigTypes[key]);
+    }
+  }
+
+  return json;
+}
+
+export function chainConfigFromJson(json: Record<string, unknown>): ChainConfig {
+  const config = {} as ChainConfig;
+
+  for (const key of Object.keys(chainConfigTypes) as (keyof ChainConfig)[]) {
+    const value = json[key];
+    if (value !== undefined) {
+      config[key] = deserializeSpecValue(json[key], chainConfigTypes[key], key) as never;
+    }
+  }
+
+  return config;
+}
+
+export function specValuesToJson(spec: Record<string, SpecValue>): SpecJson {
+  const json: SpecJson = {};
+
+  for (const key of Object.keys(spec)) {
+    json[key] = serializeSpecValue(spec[key], toSpecValueTypeName(spec[key]));
+  }
+
+  return json;
+}
+
+/** Automatic inference of typeName. For critical variables define type names, else infer */
+export function toSpecValueTypeName(value: SpecValue): SpecValueTypeName {
+  if (value instanceof Uint8Array) return "bytes";
+  if (typeof value === "number") return "number";
+  if (typeof value === "bigint") return "bigint";
+  if (typeof value === "string") return "string";
+  if (isBlobSchedule(value)) return "blob_schedule";
+  throw Error(`Unknown value type ${value}`);
+}
+
+export function serializeSpecValue(
+  value: SpecValue,
+  typeName: SpecValueTypeName
+): string | Record<keyof BlobScheduleEntry, string>[] {
+  switch (typeName) {
+    case "number":
+      if (typeof value !== "number") {
+        throw Error(`Invalid value ${value.toString()} expected number`);
+      }
+      if (value === Infinity) {
+        return MAX_UINT64_JSON;
+      }
+      return value.toString(10);
+
+    case "bigint":
+      if (typeof value !== "bigint") {
+        throw Error(`Invalid value ${value.toString()} expected bigint`);
+      }
+      return value.toString(10);
+
+    case "bytes":
+      if (!(value instanceof Uint8Array)) {
+        throw Error(`Invalid value ${value.toString()} expected Uint8Array`);
+      }
+      return toHex(value);
+
+    case "string":
+      if (typeof value !== "string") {
+        throw Error(`Invalid value ${value.toString()} expected string`);
+      }
+      return value;
+
+    case "blob_schedule":
+      if (!isBlobSchedule(value)) {
+        throw Error(`Invalid value ${value.toString()} expected BlobSchedule`);
+      }
+
+      return value.map(({EPOCH, MAX_BLOBS_PER_BLOCK}) => ({
+        EPOCH: EPOCH === Infinity ? MAX_UINT64_JSON : EPOCH.toString(10),
+        MAX_BLOBS_PER_BLOCK: MAX_BLOBS_PER_BLOCK === Infinity ? MAX_UINT64_JSON : MAX_BLOBS_PER_BLOCK.toString(10),
+      }));
+  }
+}
+
+export function deserializeSpecValue(valueStr: unknown, typeName: SpecValueTypeName, keyName: string): SpecValue {
+  if (typeName === "blob_schedule") {
+    return deserializeBlobSchedule(valueStr);
+  }
+
+  if (typeof valueStr !== "string") {
+    throw Error(`Invalid ${keyName} value ${valueStr} expected string`);
+  }
+
+  switch (typeName) {
+    case "number":
+      if (valueStr === MAX_UINT64_JSON) {
+        return Infinity;
+      }
+      return parseInt(valueStr, 10);
+
+    case "bigint":
+      return BigInt(valueStr);
+
+    case "bytes":
+      return fromHex(valueStr);
+
+    case "string":
+      return valueStr;
+  }
+}
+
+export function deserializeBlobSchedule(input: unknown): BlobSchedule {
+  if (!Array.isArray(input)) {
+    throw Error(`Invalid BLOB_SCHEDULE value ${input} expected array`);
+  }
+
+  const blobSchedule = input.map((entry, i) => {
+    if (typeof entry !== "object" || entry === null) {
+      throw Error(`Invalid BLOB_SCHEDULE[${i}] entry ${entry} expected object`);
+    }
+
+    const out = {} as BlobScheduleEntry;
+
+    for (const key of ["EPOCH", "MAX_BLOBS_PER_BLOCK"] as Array<keyof BlobScheduleEntry>) {
+      const value = entry[key];
+
+      if (value === undefined) {
+        throw Error(`Invalid BLOB_SCHEDULE[${i}] entry ${JSON.stringify(entry)} missing ${key}`);
+      }
+
+      if (typeof value !== "string") {
+        throw Error(`Invalid BLOB_SCHEDULE[${i}].${key} value ${value} expected string`);
+      }
+
+      if (value === MAX_UINT64_JSON) {
+        out[key] = Infinity;
+      } else {
+        const parsed = parseInt(value, 10);
+
+        if (Number.isNaN(parsed)) {
+          throw Error(`Invalid BLOB_SCHEDULE[${i}].${key} value ${value} expected number`);
+        }
+
+        out[key] = parsed;
+      }
+    }
+
+    return out;
+  });
+
+  validateBlobSchedule(blobSchedule);
+
+  return blobSchedule;
+}

package/src/chainConfig/networks/chiado.ts

@@ -0,0 +1,49 @@
+import {fromHex as b} from "@lodestar/utils";
+import {ChainConfig} from "../types.js";
+import {gnosisChainConfig as gnosis} from "./gnosis.js";
+
+// Chiado beacon chain config:
+// https://github.com/gnosischain/configs/blob/main/chiado/config.yaml
+
+export const chiadoChainConfig: ChainConfig = {
+  ...gnosis,
+
+  // NOTE: Only add diff values
+  CONFIG_NAME: "chiado",
+
+  // Transition
+  TERMINAL_TOTAL_DIFFICULTY: BigInt("231707791542740786049188744689299064356246512"),
+
+  // Deposit contract
+  DEPOSIT_CHAIN_ID: 10200,
+  DEPOSIT_NETWORK_ID: 10200,
+  DEPOSIT_CONTRACT_ADDRESS: b("0xb97036A26259B7147018913bD58a774cf91acf25"),
+
+  // 10 October 2022 10:00:00 GMT+0000
+  MIN_GENESIS_TIME: 1665396000,
+  MIN_GENESIS_ACTIVE_VALIDATOR_COUNT: 6000,
+  GENESIS_FORK_VERSION: b("0x0000006f"),
+  GENESIS_DELAY: 300,
+
+  // Forking
+  ALTAIR_FORK_VERSION: b("0x0100006f"),
+  ALTAIR_FORK_EPOCH: 90,
+  // Bellatrix
+  BELLATRIX_FORK_VERSION: b("0x0200006f"),
+  BELLATRIX_FORK_EPOCH: 180,
+  // Capella
+  CAPELLA_FORK_VERSION: b("0x0300006f"),
+  CAPELLA_FORK_EPOCH: 244224, // Wed May 24 2023 13:12:00 GMT+0000
+  // Deneb
+  DENEB_FORK_VERSION: b("0x0400006f"),
+  DENEB_FORK_EPOCH: 516608, // Wed Jan 31 2024 18:15:40 GMT+0000
+  // Electra
+  ELECTRA_FORK_VERSION: b("0x0500006f"),
+  ELECTRA_FORK_EPOCH: 948224, // Thu Mar 06 2025 09:43:40 GMT+0000
+  // Fulu
+  FULU_FORK_VERSION: b("0x0600006f"),
+  FULU_FORK_EPOCH: Infinity,
+
+  // Blob Scheduling
+  BLOB_SCHEDULE: [],
+};

package/src/chainConfig/networks/ephemery.ts

@@ -0,0 +1,71 @@
+import {fromHex as b} from "@lodestar/utils";
+import {chainConfig as mainnet} from "../configs/mainnet.js";
+import {ChainConfig} from "../types.js";
+
+// Ephemery dynamic beacon chain config:
+// https://github.com/ephemery-testnet/ephemery-genesis/blob/master/cl-config.yaml
+
+// Ephemery specification:
+// https://eips.ethereum.org/EIPS/eip-6916
+
+// iteration 0, "base"-genesis
+const baseChainConfig: ChainConfig = {
+  ...mainnet,
+
+  CONFIG_NAME: "ephemery",
+
+  // Genesis
+  // ---------------------------------------------------------------
+  MIN_GENESIS_ACTIVE_VALIDATOR_COUNT: 64,
+  // Thu Dec 02 2021 19:00:00 GMT+0000
+  MIN_GENESIS_TIME: 1638471600,
+  GENESIS_FORK_VERSION: b("0x1000101b"),
+  GENESIS_DELAY: 300,
+
+  // Forking
+  // ---------------------------------------------------------------
+  // Altair
+  ALTAIR_FORK_VERSION: b("0x2000101b"),
+  ALTAIR_FORK_EPOCH: 0,
+  // Merge
+  BELLATRIX_FORK_VERSION: b("0x3000101b"),
+  BELLATRIX_FORK_EPOCH: 0,
+  TERMINAL_TOTAL_DIFFICULTY: BigInt("0"),
+  // Capella
+  CAPELLA_FORK_VERSION: b("0x4000101b"),
+  CAPELLA_FORK_EPOCH: 0,
+  // Deneb
+  DENEB_FORK_VERSION: b("0x5000101b"),
+  DENEB_FORK_EPOCH: 0,
+  // Electra
+  ELECTRA_FORK_VERSION: b("0x6000101b"),
+  ELECTRA_FORK_EPOCH: 10,
+  // Fulu
+  FULU_FORK_VERSION: b("0x7000101b"),
+  FULU_FORK_EPOCH: Infinity,
+
+  // Deposit contract
+  // ---------------------------------------------------------------
+  DEPOSIT_CHAIN_ID: 39438000,
+  DEPOSIT_NETWORK_ID: 39438000,
+  DEPOSIT_CONTRACT_ADDRESS: b("0x4242424242424242424242424242424242424242"),
+
+  ETH1_FOLLOW_DISTANCE: 12,
+
+  // Blob Scheduling
+  // ---------------------------------------------------------------
+  BLOB_SCHEDULE: [],
+};
+
+// Reset interval (7 days) in milliseconds, based on ephemery-genesis values.env:
+// https://github.com/ephemery-testnet/ephemery-genesis/blob/9a28fbef950c8547d78785f8a0ea49a95ce19a48/values.env#L5
+const RESET_INTERVAL_MS = 604800000;
+const iteration = Math.floor(Date.now() - baseChainConfig.MIN_GENESIS_TIME) / RESET_INTERVAL_MS;
+
+export const ephemeryChainConfig: ChainConfig = {
+  ...baseChainConfig,
+
+  MIN_GENESIS_TIME: RESET_INTERVAL_MS * iteration + baseChainConfig.MIN_GENESIS_TIME,
+  DEPOSIT_CHAIN_ID: baseChainConfig.DEPOSIT_CHAIN_ID + iteration,
+  DEPOSIT_NETWORK_ID: baseChainConfig.DEPOSIT_NETWORK_ID + iteration,
+};

package/src/chainConfig/networks/gnosis.ts

@@ -0,0 +1,74 @@
+import {PresetName} from "@lodestar/params";
+import {fromHex as b} from "@lodestar/utils";
+import {chainConfig as mainnet} from "../configs/mainnet.js";
+import {ChainConfig} from "../types.js";
+
+// Gnosis beacon chain config:
+// https://github.com/gnosischain/configs/blob/main/mainnet/config.yaml
+
+export const gnosisChainConfig: ChainConfig = {
+  ...mainnet,
+
+  // NOTE: Only add diff values
+  PRESET_BASE: PresetName.gnosis,
+  CONFIG_NAME: "gnosis",
+
+  // Transition
+  TERMINAL_TOTAL_DIFFICULTY: BigInt("8626000000000000000000058750000000000000000000"),
+
+  // Time parameters
+  SECONDS_PER_SLOT: 5,
+  SECONDS_PER_ETH1_BLOCK: 6,
+  ETH1_FOLLOW_DISTANCE: 1024,
+  CHURN_LIMIT_QUOTIENT: 4096,
+
+  // Validator cycle
+  MAX_PER_EPOCH_ACTIVATION_CHURN_LIMIT: 2,
+
+  // Deposit contract
+  DEPOSIT_CHAIN_ID: 100,
+  DEPOSIT_NETWORK_ID: 100,
+  DEPOSIT_CONTRACT_ADDRESS: b("0x0b98057ea310f4d31f2a452b414647007d1645d9"),
+
+  // Networking
+  MIN_EPOCHS_FOR_BLOB_SIDECARS_REQUESTS: 16384,
+
+  // Dec 8, 2021, 13:00 UTC
+  MIN_GENESIS_TIME: 1638968400,
+  MIN_GENESIS_ACTIVE_VALIDATOR_COUNT: 4096,
+  GENESIS_FORK_VERSION: b("0x00000064"),
+  GENESIS_DELAY: 6000,
+
+  // Forking
+  ALTAIR_FORK_VERSION: b("0x01000064"),
+  ALTAIR_FORK_EPOCH: 512,
+  // Bellatrix
+  BELLATRIX_FORK_VERSION: b("0x02000064"),
+  BELLATRIX_FORK_EPOCH: 385536,
+  // Capella
+  CAPELLA_FORK_VERSION: b("0x03000064"),
+  CAPELLA_FORK_EPOCH: 648704, // 2023-08-01T11:34:20.000Z
+  // Deneb
+  DENEB_FORK_VERSION: b("0x04000064"),
+  DENEB_FORK_EPOCH: 889856, // 2024-03-11T18:30:20.000Z
+  // Electra
+  ELECTRA_FORK_VERSION: b("0x05000064"),
+  ELECTRA_FORK_EPOCH: 1337856, // 2025-04-30T14:03:40.000Z
+  // Fulu
+  FULU_FORK_VERSION: b("0x06000064"),
+  FULU_FORK_EPOCH: Infinity,
+
+  // Deneb
+  MAX_BLOBS_PER_BLOCK: 2,
+
+  // Electra
+  // 2**6 * 10**9 (= 64,000,000,000)
+  MAX_PER_EPOCH_ACTIVATION_EXIT_CHURN_LIMIT: 64000000000,
+  BLOB_SIDECAR_SUBNET_COUNT_ELECTRA: 2,
+  MAX_BLOBS_PER_BLOCK_ELECTRA: 2,
+  // MAX_REQUEST_BLOCKS_DENEB * MAX_BLOBS_PER_BLOCK_ELECTRA
+  MAX_REQUEST_BLOB_SIDECARS_ELECTRA: 256,
+
+  // Blob Scheduling
+  BLOB_SCHEDULE: [],
+};

package/src/chainConfig/networks/holesky.ts

@@ -0,0 +1,64 @@
+import {fromHex as b} from "@lodestar/utils";
+import {chainConfig as mainnet} from "../configs/mainnet.js";
+import {ChainConfig} from "../types.js";
+
+// Holesky beacon chain config:
+// https://github.com/eth-clients/holesky/blob/main/metadata/config.yaml
+
+export const holeskyChainConfig: ChainConfig = {
+  ...mainnet,
+
+  CONFIG_NAME: "holesky",
+
+  // Genesis
+  // ---------------------------------------------------------------
+  MIN_GENESIS_ACTIVE_VALIDATOR_COUNT: 16384,
+  // Sep-28-2023 11:55:00 +UTC
+  MIN_GENESIS_TIME: 1695902100,
+  GENESIS_DELAY: 300,
+  GENESIS_FORK_VERSION: b("0x01017000"),
+
+  // Forking
+  // ---------------------------------------------------------------
+  // # Altair
+  ALTAIR_FORK_VERSION: b("0x02017000"),
+  ALTAIR_FORK_EPOCH: 0,
+  // # Merge
+  BELLATRIX_FORK_VERSION: b("0x03017000"),
+  BELLATRIX_FORK_EPOCH: 0,
+  TERMINAL_TOTAL_DIFFICULTY: BigInt("0"),
+  // Capella
+  CAPELLA_FORK_VERSION: b("0x04017000"),
+  CAPELLA_FORK_EPOCH: 256,
+  // Deneb
+  DENEB_FORK_VERSION: b("0x05017000"),
+  DENEB_FORK_EPOCH: 29696,
+  // Electra
+  ELECTRA_FORK_VERSION: b("0x06017000"),
+  ELECTRA_FORK_EPOCH: 115968,
+  // Fulu
+  FULU_FORK_VERSION: b("0x07017000"),
+  FULU_FORK_EPOCH: 165120,
+
+  // # 28,000,000,000 Gwei to ensure quicker ejection
+  EJECTION_BALANCE: 28000000000,
+
+  // Deposit contract
+  // ---------------------------------------------------------------
+  DEPOSIT_CHAIN_ID: 17000,
+  DEPOSIT_NETWORK_ID: 17000,
+  DEPOSIT_CONTRACT_ADDRESS: b("0x4242424242424242424242424242424242424242"),
+
+  // Blob Scheduling
+  // ---------------------------------------------------------------
+  BLOB_SCHEDULE: [
+    {
+      EPOCH: 166400,
+      MAX_BLOBS_PER_BLOCK: 15,
+    },
+    {
+      EPOCH: 167936,
+      MAX_BLOBS_PER_BLOCK: 21,
+    },
+  ],
+};

package/src/chainConfig/networks/hoodi.ts

@@ -0,0 +1,64 @@
+import {fromHex as b} from "@lodestar/utils";
+import {chainConfig as mainnet} from "../configs/mainnet.js";
+import {ChainConfig} from "../types.js";
+
+// Hoodi beacon chain config:
+// https://github.com/eth-clients/hoodi/blob/main/metadata/config.yaml
+
+export const hoodiChainConfig: ChainConfig = {
+  ...mainnet,
+
+  CONFIG_NAME: "hoodi",
+
+  // Genesis
+  // ---------------------------------------------------------------
+  // 2025-Mar-17 12:00:00 PM UTC
+  MIN_GENESIS_TIME: 1742212800,
+  GENESIS_DELAY: 600,
+  GENESIS_FORK_VERSION: b("0x10000910"),
+
+  // Forking
+  // ---------------------------------------------------------------
+  // # Altair
+  ALTAIR_FORK_VERSION: b("0x20000910"),
+  ALTAIR_FORK_EPOCH: 0,
+  // # Merge
+  BELLATRIX_FORK_VERSION: b("0x30000910"),
+  BELLATRIX_FORK_EPOCH: 0,
+  TERMINAL_TOTAL_DIFFICULTY: BigInt("0"),
+  // Capella
+  CAPELLA_FORK_VERSION: b("0x40000910"),
+  CAPELLA_FORK_EPOCH: 0,
+  // Deneb
+  DENEB_FORK_VERSION: b("0x50000910"),
+  DENEB_FORK_EPOCH: 0,
+  // Electra
+  ELECTRA_FORK_VERSION: b("0x60000910"),
+  ELECTRA_FORK_EPOCH: 2048,
+  // Fulu
+  FULU_FORK_VERSION: b("0x70000910"),
+  FULU_FORK_EPOCH: 50688,
+
+  // Time parameters
+  // ---------------------------------------------------------------
+  // 12 (update from older mainnet default of 14)
+  SECONDS_PER_ETH1_BLOCK: 12,
+
+  // Deposit contract
+  // ---------------------------------------------------------------
+  DEPOSIT_CHAIN_ID: 560048,
+  DEPOSIT_NETWORK_ID: 560048,
+
+  // Blob Scheduling
+  // ---------------------------------------------------------------
+  BLOB_SCHEDULE: [
+    {
+      EPOCH: 52480,
+      MAX_BLOBS_PER_BLOCK: 15,
+    },
+    {
+      EPOCH: 54016,
+      MAX_BLOBS_PER_BLOCK: 21,
+    },
+  ],
+};

package/src/chainConfig/networks/mainnet.ts

@@ -0,0 +1,19 @@
+import {fromHex as b} from "@lodestar/utils";
+import {chainConfig as mainnet} from "../configs/mainnet.js";
+import {ChainConfig} from "../types.js";
+
+export const mainnetChainConfig: ChainConfig = {
+  ...mainnet,
+
+  CONFIG_NAME: "mainnet",
+
+  DEPOSIT_CONTRACT_ADDRESS: b("0x00000000219ab540356cBB839Cbe05303d7705Fa"),
+
+  DEPOSIT_CHAIN_ID: 1,
+  DEPOSIT_NETWORK_ID: 1,
+
+  MIN_GENESIS_TIME: 1606824000, // Tuesday, December 1, 2020 12:00:00 PM UTC
+  GENESIS_DELAY: 604800,
+  // MUST NOT use `GENESIS_FORK_VERSION` here so for `minimal` networks the preset value of 0x00000001 take prevalence
+  // GENESIS_FORK_VERSION: "0x00000000",
+};

package/src/chainConfig/networks/sepolia.ts

@@ -0,0 +1,61 @@
+import {fromHex as b} from "@lodestar/utils";
+import {chainConfig as mainnet} from "../configs/mainnet.js";
+import {ChainConfig} from "../types.js";
+
+// Sepolia beacon chain config:
+// https://github.com/eth-clients/sepolia/blob/main/metadata/config.yaml
+
+export const sepoliaChainConfig: ChainConfig = {
+  ...mainnet,
+
+  CONFIG_NAME: "sepolia",
+
+  // Genesis
+  // ---------------------------------------------------------------
+  MIN_GENESIS_ACTIVE_VALIDATOR_COUNT: 1300,
+  // # Sunday, June 19, 2022 2:00:00 PM +UTC
+  MIN_GENESIS_TIME: 1655647200,
+  GENESIS_FORK_VERSION: b("0x90000069"),
+  GENESIS_DELAY: 86400,
+
+  // Forking
+  // ---------------------------------------------------------------
+  // # Altair
+  ALTAIR_FORK_VERSION: b("0x90000070"),
+  ALTAIR_FORK_EPOCH: 50,
+  // # Merge
+  BELLATRIX_FORK_VERSION: b("0x90000071"),
+  BELLATRIX_FORK_EPOCH: 100,
+  TERMINAL_TOTAL_DIFFICULTY: BigInt("17000000000000000"),
+  // Capella
+  CAPELLA_FORK_VERSION: b("0x90000072"),
+  CAPELLA_FORK_EPOCH: 56832,
+  // Deneb
+  DENEB_FORK_VERSION: b("0x90000073"),
+  DENEB_FORK_EPOCH: 132608,
+  // Electra
+  ELECTRA_FORK_VERSION: b("0x90000074"),
+  ELECTRA_FORK_EPOCH: 222464,
+  // Fulu
+  FULU_FORK_VERSION: b("0x90000075"),
+  FULU_FORK_EPOCH: 272640,
+
+  // Deposit contract
+  // ---------------------------------------------------------------
+  DEPOSIT_CHAIN_ID: 11155111,
+  DEPOSIT_NETWORK_ID: 11155111,
+  DEPOSIT_CONTRACT_ADDRESS: b("0x7f02C3E3c98b133055B8B348B2Ac625669Ed295D"),
+
+  // Blob Scheduling
+  // ---------------------------------------------------------------
+  BLOB_SCHEDULE: [
+    {
+      EPOCH: 274176,
+      MAX_BLOBS_PER_BLOCK: 15,
+    },
+    {
+      EPOCH: 275712,
+      MAX_BLOBS_PER_BLOCK: 21,
+    },
+  ],
+};