@lodestar/config 1.35.0-dev.955e9f89ed → 1.35.0-dev.98d359db41

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,
+    },
+  ],
+};

package/src/chainConfig/types.ts

@@ -0,0 +1,252 @@
+import {PresetName} from "@lodestar/params";
+
+/**
+ * Run-time chain configuration
+ */
+export type ChainConfig = {
+  PRESET_BASE: PresetName;
+  /**
+   * Free-form short name of the network that this configuration applies to - known
+   * canonical network names include:
+   * * 'mainnet' - there can be only one
+   * * 'holesky' - testnet
+   * Must match the regex: [a-z0-9\-]
+   */
+  CONFIG_NAME: string;
+
+  // Transition
+  TERMINAL_TOTAL_DIFFICULTY: bigint;
+  TERMINAL_BLOCK_HASH: Uint8Array;
+  TERMINAL_BLOCK_HASH_ACTIVATION_EPOCH: number;
+
+  // Genesis
+  MIN_GENESIS_ACTIVE_VALIDATOR_COUNT: number;
+  MIN_GENESIS_TIME: number;
+  GENESIS_FORK_VERSION: Uint8Array;
+  GENESIS_DELAY: number;
+
+  // Forking
+  // Altair
+  ALTAIR_FORK_VERSION: Uint8Array;
+  ALTAIR_FORK_EPOCH: number;
+  // Bellatrix
+  BELLATRIX_FORK_VERSION: Uint8Array;
+  BELLATRIX_FORK_EPOCH: number;
+  // Capella
+  CAPELLA_FORK_VERSION: Uint8Array;
+  CAPELLA_FORK_EPOCH: number;
+  // DENEB
+  DENEB_FORK_VERSION: Uint8Array;
+  DENEB_FORK_EPOCH: number;
+  // ELECTRA
+  ELECTRA_FORK_VERSION: Uint8Array;
+  ELECTRA_FORK_EPOCH: number;
+  // FULU
+  FULU_FORK_VERSION: Uint8Array;
+  FULU_FORK_EPOCH: number;
+  // GLOAS
+  GLOAS_FORK_VERSION: Uint8Array;
+  GLOAS_FORK_EPOCH: number;
+
+  // Time parameters
+  SECONDS_PER_SLOT: number;
+  SECONDS_PER_ETH1_BLOCK: number;
+  MIN_VALIDATOR_WITHDRAWABILITY_DELAY: number;
+  SHARD_COMMITTEE_PERIOD: number;
+  ETH1_FOLLOW_DISTANCE: number;
+
+  ATTESTATION_DUE_BPS_GLOAS: number;
+  AGGREGATE_DUE_BPS_GLOAS: number;
+  SYNC_MESSAGE_DUE_BPS_GLOAS: number;
+  CONTRIBUTION_DUE_BPS_GLOAS: number;
+  PAYLOAD_ATTESTATION_DUE_BPS: number;
+
+  // Validator cycle
+  INACTIVITY_SCORE_BIAS: number;
+  INACTIVITY_SCORE_RECOVERY_RATE: number;
+  EJECTION_BALANCE: number;
+  MIN_PER_EPOCH_CHURN_LIMIT: number;
+  MAX_PER_EPOCH_ACTIVATION_CHURN_LIMIT: number;
+  CHURN_LIMIT_QUOTIENT: number;
+  MAX_PER_EPOCH_ACTIVATION_EXIT_CHURN_LIMIT: number;
+  MIN_PER_EPOCH_CHURN_LIMIT_ELECTRA: number;
+
+  // Fork choice
+  PROPOSER_SCORE_BOOST: number;
+  REORG_HEAD_WEIGHT_THRESHOLD: number;
+  REORG_PARENT_WEIGHT_THRESHOLD: number;
+  REORG_MAX_EPOCHS_SINCE_FINALIZATION: number;
+
+  // Deposit contract
+  DEPOSIT_CHAIN_ID: number;
+  DEPOSIT_NETWORK_ID: number;
+  DEPOSIT_CONTRACT_ADDRESS: Uint8Array;
+
+  // Networking
+  MAX_REQUEST_BLOCKS: number;
+  MAX_REQUEST_BLOCKS_DENEB: number;
+  MIN_EPOCHS_FOR_BLOCK_REQUESTS: number;
+  MIN_EPOCHS_FOR_BLOB_SIDECARS_REQUESTS: number;
+  MIN_EPOCHS_FOR_DATA_COLUMN_SIDECARS_REQUESTS: number;
+  BLOB_SIDECAR_SUBNET_COUNT: number;
+  MAX_BLOBS_PER_BLOCK: number;
+  MAX_REQUEST_BLOB_SIDECARS: number;
+  BLOB_SIDECAR_SUBNET_COUNT_ELECTRA: number;
+  DATA_COLUMN_SIDECAR_SUBNET_COUNT: number;
+  MAX_BLOBS_PER_BLOCK_ELECTRA: number;
+  MAX_REQUEST_BLOB_SIDECARS_ELECTRA: number;
+  MAX_REQUEST_DATA_COLUMN_SIDECARS: number;
+
+  // Fulu
+  NUMBER_OF_CUSTODY_GROUPS: number;
+  SAMPLES_PER_SLOT: number;
+  CUSTODY_REQUIREMENT: number;
+  VALIDATOR_CUSTODY_REQUIREMENT: number;
+  BALANCE_PER_ADDITIONAL_CUSTODY_GROUP: number;
+
+  // Blob Scheduling
+  BLOB_SCHEDULE: BlobSchedule;
+};
+
+export const chainConfigTypes: SpecTypes<ChainConfig> = {
+  PRESET_BASE: "string",
+  CONFIG_NAME: "string",
+
+  // Transition
+  TERMINAL_TOTAL_DIFFICULTY: "bigint",
+  TERMINAL_BLOCK_HASH: "bytes",
+  TERMINAL_BLOCK_HASH_ACTIVATION_EPOCH: "number",
+
+  // Genesis
+  MIN_GENESIS_ACTIVE_VALIDATOR_COUNT: "number",
+  MIN_GENESIS_TIME: "number",
+  GENESIS_FORK_VERSION: "bytes",
+  GENESIS_DELAY: "number",
+
+  // Forking
+  // Altair
+  ALTAIR_FORK_VERSION: "bytes",
+  ALTAIR_FORK_EPOCH: "number",
+  // Bellatrix
+  BELLATRIX_FORK_VERSION: "bytes",
+  BELLATRIX_FORK_EPOCH: "number",
+  // Capella
+  CAPELLA_FORK_VERSION: "bytes",
+  CAPELLA_FORK_EPOCH: "number",
+  // DENEB
+  DENEB_FORK_VERSION: "bytes",
+  DENEB_FORK_EPOCH: "number",
+  // ELECTRA
+  ELECTRA_FORK_VERSION: "bytes",
+  ELECTRA_FORK_EPOCH: "number",
+  // FULU
+  FULU_FORK_VERSION: "bytes",
+  FULU_FORK_EPOCH: "number",
+  // GLOAS
+  GLOAS_FORK_VERSION: "bytes",
+  GLOAS_FORK_EPOCH: "number",
+
+  // Time parameters
+  SECONDS_PER_SLOT: "number",
+  SECONDS_PER_ETH1_BLOCK: "number",
+  MIN_VALIDATOR_WITHDRAWABILITY_DELAY: "number",
+  SHARD_COMMITTEE_PERIOD: "number",
+  ETH1_FOLLOW_DISTANCE: "number",
+
+  ATTESTATION_DUE_BPS_GLOAS: "number",
+  AGGREGATE_DUE_BPS_GLOAS: "number",
+  SYNC_MESSAGE_DUE_BPS_GLOAS: "number",
+  CONTRIBUTION_DUE_BPS_GLOAS: "number",
+  PAYLOAD_ATTESTATION_DUE_BPS: "number",
+
+  // Validator cycle
+  INACTIVITY_SCORE_BIAS: "number",
+  INACTIVITY_SCORE_RECOVERY_RATE: "number",
+  EJECTION_BALANCE: "number",
+  MIN_PER_EPOCH_CHURN_LIMIT: "number",
+  MAX_PER_EPOCH_ACTIVATION_CHURN_LIMIT: "number",
+  CHURN_LIMIT_QUOTIENT: "number",
+  MAX_PER_EPOCH_ACTIVATION_EXIT_CHURN_LIMIT: "number",
+  MIN_PER_EPOCH_CHURN_LIMIT_ELECTRA: "number",
+
+  // Fork choice
+  PROPOSER_SCORE_BOOST: "number",
+  REORG_HEAD_WEIGHT_THRESHOLD: "number",
+  REORG_PARENT_WEIGHT_THRESHOLD: "number",
+  REORG_MAX_EPOCHS_SINCE_FINALIZATION: "number",
+
+  // Deposit contract
+  DEPOSIT_CHAIN_ID: "number",
+  DEPOSIT_NETWORK_ID: "number",
+  DEPOSIT_CONTRACT_ADDRESS: "bytes",
+
+  // Networking
+  MAX_REQUEST_BLOCKS: "number",
+  MAX_REQUEST_BLOCKS_DENEB: "number",
+  MIN_EPOCHS_FOR_BLOCK_REQUESTS: "number",
+  MIN_EPOCHS_FOR_BLOB_SIDECARS_REQUESTS: "number",
+  MIN_EPOCHS_FOR_DATA_COLUMN_SIDECARS_REQUESTS: "number",
+  BLOB_SIDECAR_SUBNET_COUNT: "number",
+  DATA_COLUMN_SIDECAR_SUBNET_COUNT: "number",
+  MAX_BLOBS_PER_BLOCK: "number",
+  MAX_REQUEST_BLOB_SIDECARS: "number",
+  BLOB_SIDECAR_SUBNET_COUNT_ELECTRA: "number",
+  MAX_BLOBS_PER_BLOCK_ELECTRA: "number",
+  MAX_REQUEST_BLOB_SIDECARS_ELECTRA: "number",
+  MAX_REQUEST_DATA_COLUMN_SIDECARS: "number",
+
+  // Fulu
+  NUMBER_OF_CUSTODY_GROUPS: "number",
+  SAMPLES_PER_SLOT: "number",
+  CUSTODY_REQUIREMENT: "number",
+  VALIDATOR_CUSTODY_REQUIREMENT: "number",
+  BALANCE_PER_ADDITIONAL_CUSTODY_GROUP: "number",
+
+  // Blob Scheduling
+  BLOB_SCHEDULE: "blob_schedule",
+};
+
+export type BlobScheduleEntry = {
+  EPOCH: number;
+  MAX_BLOBS_PER_BLOCK: number;
+};
+
+export type BlobSchedule = BlobScheduleEntry[];
+
+export function isBlobSchedule(value: unknown): value is BlobSchedule {
+  return (
+    Array.isArray(value) &&
+    value.every(
+      (entry) =>
+        typeof entry === "object" &&
+        entry !== null &&
+        typeof entry.EPOCH === "number" &&
+        typeof entry.MAX_BLOBS_PER_BLOCK === "number"
+    )
+  );
+}
+
+/** Allows values in a Spec file */
+export type SpecValue = number | bigint | Uint8Array | string | BlobSchedule;
+
+/** Type value name of each spec field. Numbers are ignored since they are the most common */
+export type SpecValueType<V extends SpecValue> = V extends number
+  ? "number"
+  : V extends bigint
+    ? "bigint"
+    : V extends Uint8Array
+      ? "bytes"
+      : V extends string
+        ? "string"
+        : V extends BlobSchedule
+          ? "blob_schedule"
+          : never;
+
+/** All possible type names for a SpecValue */
+export type SpecValueTypeName = SpecValueType<SpecValue>;
+
+export type SpecTypes<Spec extends Record<string, SpecValue>> = {
+  [K in keyof Spec]: SpecValueType<Spec[K]>;
+};
+
+export type SpecJson = Record<string, string | Record<string, string>[]>;

package/src/configs.ts

@@ -0,0 +1,4 @@
+import {chainConfig as mainnetChainConfig} from "./chainConfig/configs/mainnet.js";
+import {chainConfig as minimalChainConfig} from "./chainConfig/configs/minimal.js";
+
+export {mainnetChainConfig, minimalChainConfig};

package/src/default.ts

@@ -0,0 +1,6 @@
+import {createChainForkConfig} from "./beaconConfig.js";
+import {defaultChainConfig} from "./chainConfig/index.js";
+
+export const chainConfig = defaultChainConfig;
+// for testing purpose only
+export const config = createChainForkConfig(defaultChainConfig);