feat: add fulu definition (#7479)

**Motivation**

Both `peerDAS` and `FOCIL` both rely on these changes and its little
harm to merge them into unstable so that both branches can build on this
without diverging.

Author: matthewkeil

packages/beacon-node/test/spec/presets/fork.test.ts

@@ -7,6 +7,7 @@ import {
   CachedBeaconStateBellatrix,
   CachedBeaconStateCapella,
   CachedBeaconStateDeneb,
+  CachedBeaconStateElectra,
   CachedBeaconStatePhase0,
 } from "@lodestar/state-transition";
 import * as slotFns from "@lodestar/state-transition/slot";
@@ -38,6 +39,8 @@ const fork: TestRunnerFn<ForkStateCase, BeaconStateAllForks> = (forkNext) => {
           return slotFns.upgradeStateToDeneb(preState as CachedBeaconStateCapella);
         case ForkName.electra:
           return slotFns.upgradeStateToElectra(preState as CachedBeaconStateDeneb);
+        case ForkName.fulu:
+          return slotFns.upgradeStateToFulu(preState as CachedBeaconStateElectra);
       }
     },
     options: {

packages/beacon-node/test/spec/presets/transition.test.ts

@@ -108,6 +108,15 @@ function getTransitionConfig(fork: ForkName, forkEpoch: number): Partial<ChainCo
         DENEB_FORK_EPOCH: 0,
         ELECTRA_FORK_EPOCH: forkEpoch,
       };
+    case ForkName.fulu:
+      return {
+        ALTAIR_FORK_EPOCH: 0,
+        BELLATRIX_FORK_EPOCH: 0,
+        CAPELLA_FORK_EPOCH: 0,
+        DENEB_FORK_EPOCH: 0,
+        ELECTRA_FORK_EPOCH: 0,
+        FULU_FORK_EPOCH: forkEpoch,
+      };
   }
 }
 

packages/beacon-node/test/unit/chain/lightclient/upgradeLightClientHeader.test.ts

@@ -15,6 +15,7 @@ describe("UpgradeLightClientHeader", () => {
     CAPELLA_FORK_EPOCH: 3,
     DENEB_FORK_EPOCH: 4,
     ELECTRA_FORK_EPOCH: 5,
+    FULU_FORK_EPOCH: 6,
   });
 
   const genesisValidatorsRoot = Buffer.alloc(32, 0xaa);
@@ -28,6 +29,7 @@ describe("UpgradeLightClientHeader", () => {
       bellatrix: ssz.altair.LightClientHeader.defaultValue(),
       deneb: ssz.deneb.LightClientHeader.defaultValue(),
       electra: ssz.deneb.LightClientHeader.defaultValue(),
+      fulu: ssz.deneb.LightClientHeader.defaultValue(),
     };
 
     testSlots = {
@@ -37,6 +39,7 @@ describe("UpgradeLightClientHeader", () => {
       capella: 25,
       deneb: 33,
       electra: 41,
+      fulu: 54,
     };
   });
 

packages/beacon-node/test/unit/network/fork.test.ts

@@ -10,13 +10,15 @@ function getForkConfig({
   capella,
   deneb,
   electra,
+  fulu,
 }: {
   phase0: number;
   altair: number;
   bellatrix: number;
   capella: number;
   deneb: number;
   electra: number;
+  fulu: number;
 }): BeaconConfig {
   const forks: Record<ForkName, ForkInfo> = {
     phase0: {
@@ -67,6 +69,14 @@ function getForkConfig({
       prevVersion: Buffer.from([0, 0, 0, 4]),
       prevForkName: ForkName.deneb,
     },
+    fulu: {
+      name: ForkName.fulu,
+      seq: ForkSeq.fulu,
+      epoch: fulu,
+      version: Buffer.from([0, 0, 0, 6]),
+      prevVersion: Buffer.from([0, 0, 0, 5]),
+      prevForkName: ForkName.electra,
+    },
   };
   const forksAscendingEpochOrder = Object.values(forks);
   const forksDescendingEpochOrder = Object.values(forks).reverse();
@@ -144,9 +154,10 @@ for (const testScenario of testScenarios) {
   const {phase0, altair, bellatrix, capella, testCases} = testScenario;
   const deneb = Infinity;
   const electra = Infinity;
+  const fulu = Infinity;
 
   describe(`network / fork: phase0: ${phase0}, altair: ${altair}, bellatrix: ${bellatrix} capella: ${capella}`, () => {
-    const forkConfig = getForkConfig({phase0, altair, bellatrix, capella, deneb, electra});
+    const forkConfig = getForkConfig({phase0, altair, bellatrix, capella, deneb, electra, fulu});
     const forks = forkConfig.forks;
     for (const testCase of testCases) {
       const {epoch, currentFork, nextFork, activeForks} = testCase;

packages/beacon-node/test/utils/config.ts

@@ -38,5 +38,14 @@ export function getConfig(fork: ForkName, forkEpoch = 0): ChainForkConfig {
         DENEB_FORK_EPOCH: 0,
         ELECTRA_FORK_EPOCH: forkEpoch,
       });
+    case ForkName.fulu:
+      return createChainForkConfig({
+        ALTAIR_FORK_EPOCH: 0,
+        BELLATRIX_FORK_EPOCH: 0,
+        CAPELLA_FORK_EPOCH: 0,
+        DENEB_FORK_EPOCH: 0,
+        ELECTRA_FORK_EPOCH: 0,
+        FULU_FORK_EPOCH: forkEpoch,
+      });
   }
 }

packages/config/src/chainConfig/configs/mainnet.ts

@@ -52,6 +52,10 @@ export const chainConfig: ChainConfig = {
   ELECTRA_FORK_VERSION: b("0x05000000"),
   ELECTRA_FORK_EPOCH: Infinity,
 
+  // FULU
+  FULU_FORK_VERSION: b("0x06000000"),
+  FULU_FORK_EPOCH: Infinity,
+
   // Time parameters
   // ---------------------------------------------------------------
   // 12 seconds

packages/config/src/chainConfig/configs/minimal.ts

@@ -47,6 +47,9 @@ export const chainConfig: ChainConfig = {
   // ELECTRA
   ELECTRA_FORK_VERSION: b("0x05000001"),
   ELECTRA_FORK_EPOCH: Infinity,
+  // FULU
+  FULU_FORK_VERSION: b("0x06000001"),
+  FULU_FORK_EPOCH: Infinity,
 
   // Time parameters
   // ---------------------------------------------------------------

packages/config/src/chainConfig/networks/chiado.ts

@@ -40,4 +40,7 @@ export const chiadoChainConfig: ChainConfig = {
   // Electra
   ELECTRA_FORK_VERSION: b("0x0500006f"),
   ELECTRA_FORK_EPOCH: Infinity,
+  // Fulu
+  FULU_FORK_VERSION: b("0x0600006f"),
+  FULU_FORK_EPOCH: Infinity,
 };

packages/config/src/chainConfig/networks/ephemery.ts

@@ -40,6 +40,9 @@ const baseChainConfig: ChainConfig = {
   // Electra
   ELECTRA_FORK_VERSION: b("0x6000101b"),
   ELECTRA_FORK_EPOCH: 10,
+  // Fulu
+  FULU_FORK_VERSION: b("0x7000101b"),
+  FULU_FORK_EPOCH: Infinity,
 
   // Deposit contract
   // ---------------------------------------------------------------

packages/config/src/chainConfig/networks/gnosis.ts

@@ -54,4 +54,7 @@ export const gnosisChainConfig: ChainConfig = {
   // Electra
   ELECTRA_FORK_VERSION: b("0x05000064"),
   ELECTRA_FORK_EPOCH: Infinity,
+  // Fulu
+  FULU_FORK_VERSION: b("0x06000064"),
+  FULU_FORK_EPOCH: Infinity,
 };

packages/config/src/chainConfig/networks/holesky.ts

@@ -36,6 +36,9 @@ export const holeskyChainConfig: ChainConfig = {
   // Electra
   ELECTRA_FORK_VERSION: b("0x06017000"),
   ELECTRA_FORK_EPOCH: 115968,
+  // Fulu
+  FULU_FORK_VERSION: b("0x07017000"),
+  FULU_FORK_EPOCH: Infinity,
 
   // # 28,000,000,000 Gwei to ensure quicker ejection
   EJECTION_BALANCE: 28000000000,

packages/config/src/chainConfig/networks/sepolia.ts

@@ -36,6 +36,9 @@ export const sepoliaChainConfig: ChainConfig = {
   // Electra
   ELECTRA_FORK_VERSION: b("0x90000074"),
   ELECTRA_FORK_EPOCH: 222464,
+  // Fulu
+  FULU_FORK_VERSION: b("0x90000075"),
+  FULU_FORK_EPOCH: 222464,
 
   // Deposit contract
   // ---------------------------------------------------------------

packages/config/src/chainConfig/types.ts

@@ -41,6 +41,9 @@ export type ChainConfig = {
   // ELECTRA
   ELECTRA_FORK_VERSION: Uint8Array;
   ELECTRA_FORK_EPOCH: number;
+  // FULU
+  FULU_FORK_VERSION: Uint8Array;
+  FULU_FORK_EPOCH: number;
 
   // Time parameters
   SECONDS_PER_SLOT: number;
@@ -112,6 +115,9 @@ export const chainConfigTypes: SpecTypes<ChainConfig> = {
   // ELECTRA
   ELECTRA_FORK_VERSION: "bytes",
   ELECTRA_FORK_EPOCH: "number",
+  // FULU
+  FULU_FORK_VERSION: "bytes",
+  FULU_FORK_EPOCH: "number",
 
   // Time parameters
   SECONDS_PER_SLOT: "number",

packages/config/src/forkConfig/index.ts

@@ -68,10 +68,18 @@ export function createForkConfig(config: ChainConfig): ForkConfig {
     prevVersion: config.DENEB_FORK_VERSION,
     prevForkName: ForkName.deneb,
   };
+  const fulu: ForkInfo = {
+    name: ForkName.fulu,
+    seq: ForkSeq.fulu,
+    epoch: config.FULU_FORK_EPOCH,
+    version: config.FULU_FORK_VERSION,
+    prevVersion: config.ELECTRA_FORK_VERSION,
+    prevForkName: ForkName.electra,
+  };
 
   /** Forks in order order of occurence, `phase0` first */
   // Note: Downstream code relies on proper ordering.
-  const forks = {phase0, altair, bellatrix, capella, deneb, electra};
+  const forks = {phase0, altair, bellatrix, capella, deneb, electra, fulu};
 
   // Prevents allocating an array on every getForkInfo() call
   const forksAscendingEpochOrder = Object.values(forks);

packages/light-client/src/spec/utils.ts

@@ -134,11 +134,18 @@ export function upgradeLightClientHeader(
       // Break if no further upgradation is required else fall through
       if (ForkSeq[targetFork] <= ForkSeq.deneb) break;
 
+    // biome-ignore lint/suspicious/noFallthroughSwitchClause: We need fall-through behavior here
     case ForkName.electra:
       // No changes to LightClientHeader in Electra
 
       // Break if no further upgrades is required else fall through
       if (ForkSeq[targetFork] <= ForkSeq.electra) break;
+
+    case ForkName.fulu:
+      // No changes to LightClientHeader in Electra
+
+      // Break if no further upgrades is required else fall through
+      if (ForkSeq[targetFork] <= ForkSeq.fulu) break;
   }
   return upgradedHeader;
 }

packages/params/src/forkName.ts

@@ -8,6 +8,7 @@ export enum ForkName {
   capella = "capella",
   deneb = "deneb",
   electra = "electra",
+  fulu = "fulu",
 }
 
 /**
@@ -20,6 +21,7 @@ export enum ForkSeq {
   capella = 3,
   deneb = 4,
   electra = 5,
+  fulu = 6,
 }
 
 function exclude<T extends ForkName, U extends T>(coll: T[], val: U[]): Exclude<T, U>[] {

packages/params/test/unit/__snapshots__/forkName.test.ts.snap

@@ -8,6 +8,7 @@ exports[`forkName > should have valid allForks 1`] = `
   "capella",
   "deneb",
   "electra",
+  "fulu",
 ]
 `;
 
@@ -18,6 +19,7 @@ exports[`forkName > should have valid post-altair forks 1`] = `
   "capella",
   "deneb",
   "electra",
+  "fulu",
 ]
 `;
 
@@ -27,6 +29,7 @@ exports[`forkName > should have valid post-bellatrix forks 1`] = `
   "capella",
   "deneb",
   "electra",
+  "fulu",
 ]
 `;
 
@@ -35,12 +38,14 @@ exports[`forkName > should have valid post-capella forks 1`] = `
   "capella",
   "deneb",
   "electra",
+  "fulu",
 ]
 `;
 
 exports[`forkName > should have valid post-deneb forks 1`] = `
 [
   "deneb",
   "electra",
+  "fulu",
 ]
 `;

packages/state-transition/src/cache/stateCache.ts

@@ -11,6 +11,7 @@ import {
   BeaconStateDeneb,
   BeaconStateElectra,
   BeaconStateExecutions,
+  BeaconStateFulu,
   BeaconStatePhase0,
 } from "./types.js";
 
@@ -132,6 +133,7 @@ export type CachedBeaconStateBellatrix = CachedBeaconState<BeaconStateBellatrix>
 export type CachedBeaconStateCapella = CachedBeaconState<BeaconStateCapella>;
 export type CachedBeaconStateDeneb = CachedBeaconState<BeaconStateDeneb>;
 export type CachedBeaconStateElectra = CachedBeaconState<BeaconStateElectra>;
+export type CachedBeaconStateFulu = CachedBeaconState<BeaconStateFulu>;
 
 export type CachedBeaconStateAllForks = CachedBeaconState<BeaconStateAllForks>;
 export type CachedBeaconStateExecutions = CachedBeaconState<BeaconStateExecutions>;

packages/state-transition/src/cache/types.ts

@@ -9,6 +9,7 @@ export type BeaconStateBellatrix = CompositeViewDU<SSZTypesFor<ForkName.bellatri
 export type BeaconStateCapella = CompositeViewDU<SSZTypesFor<ForkName.capella, "BeaconState">>;
 export type BeaconStateDeneb = CompositeViewDU<SSZTypesFor<ForkName.deneb, "BeaconState">>;
 export type BeaconStateElectra = CompositeViewDU<SSZTypesFor<ForkName.electra, "BeaconState">>;
+export type BeaconStateFulu = CompositeViewDU<SSZTypesFor<ForkName.fulu, "BeaconState">>;
 
 export type BeaconStateAllForks = CompositeViewDU<SSZTypesFor<ForkAll, "BeaconState">>;
 export type BeaconStateExecutions = CompositeViewDU<SSZTypesFor<ForkPostBellatrix, "BeaconState">>;

packages/state-transition/src/slot/index.ts

@@ -8,6 +8,7 @@ export {upgradeStateToBellatrix} from "./upgradeStateToBellatrix.js";
 export {upgradeStateToCapella} from "./upgradeStateToCapella.js";
 export {upgradeStateToDeneb} from "./upgradeStateToDeneb.js";
 export {upgradeStateToElectra} from "./upgradeStateToElectra.js";
+export {upgradeStateToFulu} from "./upgradeStateToFulu.js";
 
 /**
  * Dial state to next slot. Common for all forks

packages/state-transition/src/slot/upgradeStateToFulu.ts

@@ -0,0 +1,26 @@
+import {ssz} from "@lodestar/types";
+import {getCachedBeaconState} from "../cache/stateCache.js";
+import {CachedBeaconStateElectra, CachedBeaconStateFulu} from "../types.js";
+
+/**
+ * Upgrade a state from Electra to Fulu.
+ */
+export function upgradeStateToFulu(stateElectra: CachedBeaconStateElectra): CachedBeaconStateFulu {
+  const {config} = stateElectra;
+
+  const stateElectraNode = ssz.electra.BeaconState.commitViewDU(stateElectra);
+  const stateFuluView = ssz.fulu.BeaconState.getViewDU(stateElectraNode);
+
+  const stateFulu = getCachedBeaconState(stateFuluView, stateElectra);
+
+  stateFulu.fork = ssz.phase0.Fork.toViewDU({
+    previousVersion: stateElectra.fork.currentVersion,
+    currentVersion: config.FULU_FORK_VERSION,
+    epoch: stateElectra.epochCtx.epoch,
+  });
+
+  stateFulu.commit();
+  // Clear cache to ensure the cache of capella fields is not used by new deneb fields
+
+  return stateFulu;
+}

packages/state-transition/src/stateTransition.ts

@@ -16,12 +16,14 @@ import {
   upgradeStateToDeneb,
   upgradeStateToElectra,
 } from "./slot/index.js";
+import {upgradeStateToFulu} from "./slot/upgradeStateToFulu.js";
 import {
   CachedBeaconStateAllForks,
   CachedBeaconStateAltair,
   CachedBeaconStateBellatrix,
   CachedBeaconStateCapella,
   CachedBeaconStateDeneb,
+  CachedBeaconStateElectra,
   CachedBeaconStatePhase0,
 } from "./types.js";
 import {computeEpochAtSlot} from "./util/index.js";
@@ -264,6 +266,9 @@ function processSlotsWithTransientCache(
       if (stateEpoch === config.ELECTRA_FORK_EPOCH) {
         postState = upgradeStateToElectra(postState as CachedBeaconStateDeneb) as CachedBeaconStateAllForks;
       }
+      if (stateEpoch === config.FULU_FORK_EPOCH) {
+        postState = upgradeStateToFulu(postState as CachedBeaconStateElectra) as CachedBeaconStateAllForks;
+      }
     } else {
       postState.slot++;
     }

packages/state-transition/src/types.ts

@@ -10,6 +10,7 @@ export type {
   CachedBeaconStateCapella,
   CachedBeaconStateDeneb,
   CachedBeaconStateElectra,
+  CachedBeaconStateFulu,
 } from "./cache/stateCache.js";
 
 export type {
@@ -21,4 +22,5 @@ export type {
   BeaconStateCapella,
   BeaconStateDeneb,
   BeaconStateElectra,
+  BeaconStateFulu,
 } from "./cache/types.js";