@lodestar/state-transition 1.43.0-dev.8ad5d8be4c → 1.43.0-dev.8e18007572

package/lib/lightClient/spec/utils.js

@@ -0,0 +1,197 @@
+import { PublicKey } from "@chainsafe/blst";
+import { BLOCK_BODY_EXECUTION_PAYLOAD_DEPTH as EXECUTION_PAYLOAD_DEPTH, BLOCK_BODY_EXECUTION_PAYLOAD_INDEX as EXECUTION_PAYLOAD_INDEX, FINALIZED_ROOT_DEPTH, FINALIZED_ROOT_DEPTH_ELECTRA, ForkName, ForkSeq, NEXT_SYNC_COMMITTEE_DEPTH, NEXT_SYNC_COMMITTEE_DEPTH_ELECTRA, isForkPostElectra, } from "@lodestar/params";
+import { isElectraLightClientUpdate, ssz, } from "@lodestar/types";
+import { byteArrayEquals, verifyMerkleBranch } from "@lodestar/utils";
+import { computeEpochAtSlot, computeSyncPeriodAtSlot } from "../../util/epoch.js";
+export const GENESIS_SLOT = 0;
+export const ZERO_HASH = new Uint8Array(32);
+export const ZERO_PUBKEY = new Uint8Array(48);
+export const ZERO_SYNC_COMMITTEE = ssz.altair.SyncCommittee.defaultValue();
+export const ZERO_HEADER = ssz.phase0.BeaconBlockHeader.defaultValue();
+/** From https://notes.ethereum.org/@vbuterin/extended_light_client_protocol#Optimistic-head-determining-function */
+const SAFETY_THRESHOLD_FACTOR = 2;
+export function sumBits(bits) {
+    return bits.getTrueBitIndexes().length;
+}
+/**
+ * Util to guarantee that all bits have a corresponding pubkey.
+ */
+export function getParticipantPubkeys(pubkeys, bits) {
+    // BitArray.intersectValues() checks the length is correct.
+    return bits.intersectValues(pubkeys);
+}
+function deserializePubkeys(pubkeys) {
+    return pubkeys.map((pk) => PublicKey.fromBytes(pk, true));
+}
+function serializePubkeys(pubkeys) {
+    return pubkeys.map((pk) => pk.toBytes());
+}
+export function deserializeSyncCommittee(syncCommittee) {
+    return {
+        pubkeys: deserializePubkeys(syncCommittee.pubkeys),
+        aggregatePubkey: PublicKey.fromBytes(syncCommittee.aggregatePubkey, true),
+    };
+}
+export function serializeSyncCommittee(syncCommittee) {
+    return {
+        pubkeys: serializePubkeys(syncCommittee.pubkeys),
+        aggregatePubkey: syncCommittee.aggregatePubkey.toBytes(),
+    };
+}
+export function getSafetyThreshold(maxActiveParticipants) {
+    return Math.floor(maxActiveParticipants / SAFETY_THRESHOLD_FACTOR);
+}
+export function getZeroSyncCommitteeBranch(fork) {
+    const nextSyncCommitteeDepth = isForkPostElectra(fork)
+        ? NEXT_SYNC_COMMITTEE_DEPTH_ELECTRA
+        : NEXT_SYNC_COMMITTEE_DEPTH;
+    return Array.from({ length: nextSyncCommitteeDepth }, () => ZERO_HASH);
+}
+export function getZeroFinalityBranch(fork) {
+    const finalizedRootDepth = isForkPostElectra(fork) ? FINALIZED_ROOT_DEPTH_ELECTRA : FINALIZED_ROOT_DEPTH;
+    return Array.from({ length: finalizedRootDepth }, () => ZERO_HASH);
+}
+export function isSyncCommitteeUpdate(update) {
+    return (
+    // Fast return for when constructing full LightClientUpdate from partial updates
+    update.nextSyncCommitteeBranch !==
+        getZeroSyncCommitteeBranch(isElectraLightClientUpdate(update) ? ForkName.electra : ForkName.altair) &&
+        update.nextSyncCommitteeBranch.some((branch) => !byteArrayEquals(branch, ZERO_HASH)));
+}
+export function isFinalityUpdate(update) {
+    return (
+    // Fast return for when constructing full LightClientUpdate from partial updates
+    update.finalityBranch !==
+        getZeroFinalityBranch(isElectraLightClientUpdate(update) ? ForkName.electra : ForkName.altair) &&
+        update.finalityBranch.some((branch) => !byteArrayEquals(branch, ZERO_HASH)));
+}
+export function isZeroedHeader(header) {
+    // Fast return for when constructing full LightClientUpdate from partial updates
+    return header === ZERO_HEADER || byteArrayEquals(header.bodyRoot, ZERO_HASH);
+}
+export function isZeroedSyncCommittee(syncCommittee) {
+    // Fast return for when constructing full LightClientUpdate from partial updates
+    return syncCommittee === ZERO_SYNC_COMMITTEE || byteArrayEquals(syncCommittee.pubkeys[0], ZERO_PUBKEY);
+}
+export function isValidMerkleBranch(leaf, branch, depth, index, root) {
+    if (branch.length !== depth) {
+        return false;
+    }
+    return verifyMerkleBranch(leaf, branch, depth, index, root);
+}
+export function normalizeMerkleBranch(branch, depth) {
+    const numExtraDepth = depth - branch.length;
+    return [...Array.from({ length: numExtraDepth }, () => ZERO_HASH), ...branch];
+}
+export function upgradeLightClientHeader(config, targetFork, header) {
+    const headerFork = config.getForkName(header.beacon.slot);
+    if (ForkSeq[headerFork] >= ForkSeq[targetFork]) {
+        throw Error(`Invalid upgrade request from headerFork=${headerFork} to targetFork=${targetFork}`);
+    }
+    // We are modifying the same header object, may be we could create a copy, but its
+    // not required as of now
+    const upgradedHeader = header;
+    const startUpgradeFromFork = Object.values(ForkName)[ForkSeq[headerFork] + 1];
+    switch (startUpgradeFromFork) {
+        // biome-ignore lint/suspicious/useDefaultSwitchClauseLast: We want default to evaluate at first to throw error early
+        default:
+            throw Error(`Invalid startUpgradeFromFork=${startUpgradeFromFork} for headerFork=${headerFork} in upgradeLightClientHeader to targetFork=${targetFork}`);
+        case ForkName.altair:
+        // biome-ignore lint/suspicious/noFallthroughSwitchClause: We need fall-through behavior here
+        case ForkName.bellatrix:
+            // Break if no further upgradation is required else fall through
+            if (ForkSeq[targetFork] <= ForkSeq.bellatrix)
+                break;
+        // biome-ignore lint/suspicious/noFallthroughSwitchClause: We need fall-through behavior here
+        case ForkName.capella:
+            upgradedHeader.execution =
+                ssz.capella.LightClientHeader.fields.execution.defaultValue();
+            upgradedHeader.executionBranch =
+                ssz.capella.LightClientHeader.fields.executionBranch.defaultValue();
+            // Break if no further upgradation is required else fall through
+            if (ForkSeq[targetFork] <= ForkSeq.capella)
+                break;
+        // biome-ignore lint/suspicious/noFallthroughSwitchClause: We need fall-through behavior here
+        case ForkName.deneb:
+            upgradedHeader.execution.blobGasUsed =
+                ssz.deneb.LightClientHeader.fields.execution.fields.blobGasUsed.defaultValue();
+            upgradedHeader.execution.excessBlobGas =
+                ssz.deneb.LightClientHeader.fields.execution.fields.excessBlobGas.defaultValue();
+            // 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;
+        // biome-ignore lint/suspicious/noFallthroughSwitchClause: We need fall-through behavior here
+        case ForkName.fulu:
+            // No changes to LightClientHeader in Fulu
+            // Break if no further upgrades is required else fall through
+            if (ForkSeq[targetFork] <= ForkSeq.fulu)
+                break;
+        case ForkName.gloas:
+            // No changes to LightClientHeader in Gloas
+            // Break if no further upgrades is required else fall through
+            if (ForkSeq[targetFork] <= ForkSeq.gloas)
+                break;
+    }
+    return upgradedHeader;
+}
+export function isValidLightClientHeader(config, header) {
+    const epoch = computeEpochAtSlot(header.beacon.slot);
+    if (epoch < config.CAPELLA_FORK_EPOCH) {
+        return ((header.execution === undefined ||
+            ssz.capella.ExecutionPayloadHeader.equals(header.execution, ssz.capella.LightClientHeader.fields.execution.defaultValue())) &&
+            (header.executionBranch === undefined ||
+                ssz.capella.LightClientHeader.fields.executionBranch.equals(ssz.capella.LightClientHeader.fields.executionBranch.defaultValue(), header.executionBranch)));
+    }
+    if (epoch < config.DENEB_FORK_EPOCH &&
+        ((header.execution.blobGasUsed &&
+            header.execution.blobGasUsed !== BigInt(0)) ||
+            (header.execution.excessBlobGas &&
+                header.execution.excessBlobGas !== BigInt(0)))) {
+        return false;
+    }
+    return isValidMerkleBranch(config
+        .getPostBellatrixForkTypes(header.beacon.slot)
+        .ExecutionPayloadHeader.hashTreeRoot(header.execution), header.executionBranch, EXECUTION_PAYLOAD_DEPTH, EXECUTION_PAYLOAD_INDEX, header.beacon.bodyRoot);
+}
+export function upgradeLightClientUpdate(config, targetFork, update) {
+    update.attestedHeader = upgradeLightClientHeader(config, targetFork, update.attestedHeader);
+    update.finalizedHeader = upgradeLightClientHeader(config, targetFork, update.finalizedHeader);
+    update.nextSyncCommitteeBranch = normalizeMerkleBranch(update.nextSyncCommitteeBranch, isForkPostElectra(targetFork) ? NEXT_SYNC_COMMITTEE_DEPTH_ELECTRA : NEXT_SYNC_COMMITTEE_DEPTH);
+    update.finalityBranch = normalizeMerkleBranch(update.finalityBranch, isForkPostElectra(targetFork) ? FINALIZED_ROOT_DEPTH_ELECTRA : FINALIZED_ROOT_DEPTH);
+    return update;
+}
+export function upgradeLightClientFinalityUpdate(config, targetFork, finalityUpdate) {
+    finalityUpdate.attestedHeader = upgradeLightClientHeader(config, targetFork, finalityUpdate.attestedHeader);
+    finalityUpdate.finalizedHeader = upgradeLightClientHeader(config, targetFork, finalityUpdate.finalizedHeader);
+    finalityUpdate.finalityBranch = normalizeMerkleBranch(finalityUpdate.finalityBranch, isForkPostElectra(targetFork) ? FINALIZED_ROOT_DEPTH_ELECTRA : FINALIZED_ROOT_DEPTH);
+    return finalityUpdate;
+}
+export function upgradeLightClientOptimisticUpdate(config, targetFork, optimisticUpdate) {
+    optimisticUpdate.attestedHeader = upgradeLightClientHeader(config, targetFork, optimisticUpdate.attestedHeader);
+    return optimisticUpdate;
+}
+/**
+ * Currently this upgradation is not required because all processing is done based on the
+ * summary that the store generates and maintains. In case store needs to be saved to disk,
+ * this could be required depending on the format the store is saved to the disk
+ */
+export function upgradeLightClientStore(config, targetFork, store, signatureSlot) {
+    const updateSignaturePeriod = computeSyncPeriodAtSlot(signatureSlot);
+    const bestValidUpdate = store.bestValidUpdates.get(updateSignaturePeriod);
+    if (bestValidUpdate) {
+        store.bestValidUpdates.set(updateSignaturePeriod, {
+            update: upgradeLightClientUpdate(config, targetFork, bestValidUpdate.update),
+            summary: bestValidUpdate.summary,
+        });
+    }
+    store.finalizedHeader = upgradeLightClientHeader(config, targetFork, store.finalizedHeader);
+    store.optimisticHeader = upgradeLightClientHeader(config, targetFork, store.optimisticHeader);
+    return store;
+}
+//# sourceMappingURL=utils.js.map

package/lib/lightClient/spec/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../../src/lightClient/spec/utils.ts"],"names":[],"mappings":"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"}

package/lib/lightClient/spec/validateLightClientBootstrap.d.ts

@@ -0,0 +1,4 @@
+import { ChainForkConfig } from "@lodestar/config";
+import { LightClientBootstrap, Root } from "@lodestar/types";
+export declare function validateLightClientBootstrap(config: ChainForkConfig, trustedBlockRoot: Root, bootstrap: LightClientBootstrap): void;
+//# sourceMappingURL=validateLightClientBootstrap.d.ts.map

package/lib/lightClient/spec/validateLightClientBootstrap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validateLightClientBootstrap.d.ts","sourceRoot":"","sources":["../../../src/lightClient/spec/validateLightClientBootstrap.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,eAAe,EAAC,MAAM,kBAAkB,CAAC;AAEjD,OAAO,EAAC,oBAAoB,EAAE,IAAI,EAAM,MAAM,iBAAiB,CAAC;AAShE,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,eAAe,EACvB,gBAAgB,EAAE,IAAI,EACtB,SAAS,EAAE,oBAAoB,GAC9B,IAAI,CAuBN"}

package/lib/lightClient/spec/validateLightClientBootstrap.js

@@ -0,0 +1,22 @@
+import { isForkPostElectra } from "@lodestar/params";
+import { ssz } from "@lodestar/types";
+import { byteArrayEquals, toHex } from "@lodestar/utils";
+import { isValidLightClientHeader, isValidMerkleBranch } from "./utils.js";
+const CURRENT_SYNC_COMMITTEE_INDEX = 22;
+const CURRENT_SYNC_COMMITTEE_DEPTH = 5;
+const CURRENT_SYNC_COMMITTEE_INDEX_ELECTRA = 22;
+const CURRENT_SYNC_COMMITTEE_DEPTH_ELECTRA = 6;
+export function validateLightClientBootstrap(config, trustedBlockRoot, bootstrap) {
+    const headerRoot = ssz.phase0.BeaconBlockHeader.hashTreeRoot(bootstrap.header.beacon);
+    const fork = config.getForkName(bootstrap.header.beacon.slot);
+    if (!isValidLightClientHeader(config, bootstrap.header)) {
+        throw Error("Bootstrap Header is not Valid Light Client Header");
+    }
+    if (!byteArrayEquals(headerRoot, trustedBlockRoot)) {
+        throw Error(`bootstrap header root ${toHex(headerRoot)} != trusted root ${toHex(trustedBlockRoot)}`);
+    }
+    if (!isValidMerkleBranch(ssz.altair.SyncCommittee.hashTreeRoot(bootstrap.currentSyncCommittee), bootstrap.currentSyncCommitteeBranch, isForkPostElectra(fork) ? CURRENT_SYNC_COMMITTEE_DEPTH_ELECTRA : CURRENT_SYNC_COMMITTEE_DEPTH, isForkPostElectra(fork) ? CURRENT_SYNC_COMMITTEE_INDEX_ELECTRA : CURRENT_SYNC_COMMITTEE_INDEX, bootstrap.header.beacon.stateRoot)) {
+        throw Error("Invalid currentSyncCommittee merkle branch");
+    }
+}
+//# sourceMappingURL=validateLightClientBootstrap.js.map

package/lib/lightClient/spec/validateLightClientBootstrap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validateLightClientBootstrap.js","sourceRoot":"","sources":["../../../src/lightClient/spec/validateLightClientBootstrap.ts"],"names":[],"mappings":"AACA,OAAO,EAAC,iBAAiB,EAAC,MAAM,kBAAkB,CAAC;AACnD,OAAO,EAA6B,GAAG,EAAC,MAAM,iBAAiB,CAAC;AAChE,OAAO,EAAC,eAAe,EAAE,KAAK,EAAC,MAAM,iBAAiB,CAAC;AACvD,OAAO,EAAC,wBAAwB,EAAE,mBAAmB,EAAC,MAAM,YAAY,CAAC;AAEzE,MAAM,4BAA4B,GAAG,EAAE,CAAC;AACxC,MAAM,4BAA4B,GAAG,CAAC,CAAC;AACvC,MAAM,oCAAoC,GAAG,EAAE,CAAC;AAChD,MAAM,oCAAoC,GAAG,CAAC,CAAC;AAE/C,MAAM,UAAU,4BAA4B,CAC1C,MAAuB,EACvB,gBAAsB,EACtB,SAA+B,EACzB;IACN,MAAM,UAAU,GAAG,GAAG,CAAC,MAAM,CAAC,iBAAiB,CAAC,YAAY,CAAC,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IACtF,MAAM,IAAI,GAAG,MAAM,CAAC,WAAW,CAAC,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAE9D,IAAI,CAAC,wBAAwB,CAAC,MAAM,EAAE,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC;QACxD,MAAM,KAAK,CAAC,mDAAmD,CAAC,CAAC;IACnE,CAAC;IAED,IAAI,CAAC,eAAe,CAAC,UAAU,EAAE,gBAAgB,CAAC,EAAE,CAAC;QACnD,MAAM,KAAK,CAAC,yBAAyB,KAAK,CAAC,UAAU,CAAC,oBAAoB,KAAK,CAAC,gBAAgB,CAAC,EAAE,CAAC,CAAC;IACvG,CAAC;IAED,IACE,CAAC,mBAAmB,CAClB,GAAG,CAAC,MAAM,CAAC,aAAa,CAAC,YAAY,CAAC,SAAS,CAAC,oBAAoB,CAAC,EACrE,SAAS,CAAC,0BAA0B,EACpC,iBAAiB,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,oCAAoC,CAAC,CAAC,CAAC,4BAA4B,EAC7F,iBAAiB,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,oCAAoC,CAAC,CAAC,CAAC,4BAA4B,EAC7F,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,CAClC,EACD,CAAC;QACD,MAAM,KAAK,CAAC,4CAA4C,CAAC,CAAC;IAC5D,CAAC;AAAA,CACF"}

package/lib/lightClient/spec/validateLightClientUpdate.d.ts

@@ -0,0 +1,5 @@
+import { ChainForkConfig } from "@lodestar/config";
+import { LightClientUpdate } from "@lodestar/types";
+import type { ILightClientStore, SyncCommitteeFast } from "./store.js";
+export declare function validateLightClientUpdate(config: ChainForkConfig, store: ILightClientStore, update: LightClientUpdate, syncCommittee: SyncCommitteeFast): void;
+//# sourceMappingURL=validateLightClientUpdate.d.ts.map

package/lib/lightClient/spec/validateLightClientUpdate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validateLightClientUpdate.d.ts","sourceRoot":"","sources":["../../../src/lightClient/spec/validateLightClientUpdate.ts"],"names":[],"mappings":"AACA,OAAO,EAAC,eAAe,EAAC,MAAM,kBAAkB,CAAC;AAcjD,OAAO,EAAC,iBAAiB,EAAwC,MAAM,iBAAiB,CAAC;AACzF,OAAO,KAAK,EAAC,iBAAiB,EAAE,iBAAiB,EAAC,MAAM,YAAY,CAAC;AAarE,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,eAAe,EACvB,KAAK,EAAE,iBAAiB,EACxB,MAAM,EAAE,iBAAiB,EACzB,aAAa,EAAE,iBAAiB,GAC/B,IAAI,CA0FN"}

package/lib/lightClient/spec/validateLightClientUpdate.js

@@ -0,0 +1,88 @@
+import { Signature, fastAggregateVerify } from "@chainsafe/blst";
+import { DOMAIN_SYNC_COMMITTEE, FINALIZED_ROOT_DEPTH, FINALIZED_ROOT_DEPTH_ELECTRA, FINALIZED_ROOT_INDEX, FINALIZED_ROOT_INDEX_ELECTRA, GENESIS_SLOT, MIN_SYNC_COMMITTEE_PARTICIPANTS, NEXT_SYNC_COMMITTEE_DEPTH, NEXT_SYNC_COMMITTEE_DEPTH_ELECTRA, NEXT_SYNC_COMMITTEE_INDEX, NEXT_SYNC_COMMITTEE_INDEX_ELECTRA, } from "@lodestar/params";
+import { isElectraLightClientUpdate, ssz } from "@lodestar/types";
+import { ZERO_HASH, getParticipantPubkeys, isFinalityUpdate, isSyncCommitteeUpdate, isValidLightClientHeader, isValidMerkleBranch, isZeroedHeader, isZeroedSyncCommittee, sumBits, } from "./utils.js";
+export function validateLightClientUpdate(config, store, update, syncCommittee) {
+    // Verify sync committee has sufficient participants
+    if (sumBits(update.syncAggregate.syncCommitteeBits) < MIN_SYNC_COMMITTEE_PARTICIPANTS) {
+        throw Error("Sync committee has not sufficient participants");
+    }
+    if (!isValidLightClientHeader(config, update.attestedHeader)) {
+        throw Error("Attested Header is not Valid Light Client Header");
+    }
+    // Sanity check that slots are in correct order
+    if (update.signatureSlot <= update.attestedHeader.beacon.slot) {
+        throw Error(`signature slot ${update.signatureSlot} must be after attested header slot ${update.attestedHeader.beacon.slot}`);
+    }
+    if (update.attestedHeader.beacon.slot < update.finalizedHeader.beacon.slot) {
+        throw Error(`attested header slot ${update.signatureSlot} must be after finalized header slot ${update.finalizedHeader.beacon.slot}`);
+    }
+    // Verify that the `finality_branch`, if present, confirms `finalized_header`
+    // to match the finalized checkpoint root saved in the state of `attested_header`.
+    // Note that the genesis finalized checkpoint root is represented as a zero hash.
+    if (!isFinalityUpdate(update)) {
+        if (!isZeroedHeader(update.finalizedHeader.beacon)) {
+            throw Error("finalizedHeader must be zero for non-finality update");
+        }
+    }
+    else {
+        let finalizedRoot;
+        if (update.finalizedHeader.beacon.slot === GENESIS_SLOT) {
+            if (!isZeroedHeader(update.finalizedHeader.beacon)) {
+                throw Error("finalizedHeader must be zero for not finality update");
+            }
+            finalizedRoot = ZERO_HASH;
+        }
+        else {
+            if (!isValidLightClientHeader(config, update.finalizedHeader)) {
+                throw Error("Finalized Header is not valid Light Client Header");
+            }
+            finalizedRoot = ssz.phase0.BeaconBlockHeader.hashTreeRoot(update.finalizedHeader.beacon);
+        }
+        if (!isValidMerkleBranch(finalizedRoot, update.finalityBranch, isElectraLightClientUpdate(update) ? FINALIZED_ROOT_DEPTH_ELECTRA : FINALIZED_ROOT_DEPTH, isElectraLightClientUpdate(update) ? FINALIZED_ROOT_INDEX_ELECTRA : FINALIZED_ROOT_INDEX, update.attestedHeader.beacon.stateRoot)) {
+            throw Error("Invalid finality header merkle branch");
+        }
+    }
+    // Verify that the `next_sync_committee`, if present, actually is the next sync committee saved in the
+    // state of the `attested_header`
+    if (!isSyncCommitteeUpdate(update)) {
+        if (!isZeroedSyncCommittee(update.nextSyncCommittee)) {
+            throw Error("nextSyncCommittee must be zero for non sync committee update");
+        }
+    }
+    else {
+        if (!isValidMerkleBranch(ssz.altair.SyncCommittee.hashTreeRoot(update.nextSyncCommittee), update.nextSyncCommitteeBranch, isElectraLightClientUpdate(update) ? NEXT_SYNC_COMMITTEE_DEPTH_ELECTRA : NEXT_SYNC_COMMITTEE_DEPTH, isElectraLightClientUpdate(update) ? NEXT_SYNC_COMMITTEE_INDEX_ELECTRA : NEXT_SYNC_COMMITTEE_INDEX, update.attestedHeader.beacon.stateRoot)) {
+            throw Error("Invalid next sync committee merkle branch");
+        }
+    }
+    // Verify sync committee aggregate signature
+    const participantPubkeys = getParticipantPubkeys(syncCommittee.pubkeys, update.syncAggregate.syncCommitteeBits);
+    const signingRoot = ssz.phase0.SigningData.hashTreeRoot({
+        objectRoot: ssz.phase0.BeaconBlockHeader.hashTreeRoot(update.attestedHeader.beacon),
+        domain: store.config.getDomain(update.signatureSlot - 1, DOMAIN_SYNC_COMMITTEE),
+    });
+    if (!isValidBlsAggregate(participantPubkeys, signingRoot, update.syncAggregate.syncCommitteeSignature)) {
+        throw Error("Invalid aggregate signature");
+    }
+}
+/**
+ * Same as BLS.verifyAggregate but with detailed error messages
+ */
+function isValidBlsAggregate(publicKeys, message, signature) {
+    let sig;
+    try {
+        sig = Signature.fromBytes(signature, true);
+    }
+    catch (e) {
+        e.message = `Error deserializing signature: ${e.message}`;
+        throw e;
+    }
+    try {
+        return fastAggregateVerify(message, publicKeys, sig);
+    }
+    catch (e) {
+        e.message = `Error verifying signature: ${e.message}`;
+        throw e;
+    }
+}
+//# sourceMappingURL=validateLightClientUpdate.js.map

package/lib/lightClient/spec/validateLightClientUpdate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validateLightClientUpdate.js","sourceRoot":"","sources":["../../../src/lightClient/spec/validateLightClientUpdate.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -11,7 +11,7 @@
   "bugs": {
     "url": "https://github.com/ChainSafe/lodestar/issues"
   },
-  "version": "1.43.0-dev.8ad5d8be4c",
+  "version": "1.43.0-dev.8e18007572",
   "type": "module",
   "exports": {
     ".": {
@@ -34,6 +34,11 @@
       "types": "./lib/slot/index.d.ts",
       "import": "./lib/slot/index.js"
     },
+    "./light-client": {
+      "bun": "./src/lightClient/spec/index.ts",
+      "types": "./lib/lightClient/spec/index.d.ts",
+      "import": "./lib/lightClient/spec/index.js"
+    },
     "./test-utils": {
       "bun": "./src/testUtils/index.ts",
       "types": "./lib/testUtils/index.d.ts",
@@ -67,14 +72,14 @@
     "@chainsafe/pubkey-index-map": "^3.0.0",
     "@chainsafe/ssz": "^1.4.0",
     "@chainsafe/swap-or-not-shuffle": "^1.2.1",
-    "@lodestar/config": "^1.43.0-dev.8ad5d8be4c",
-    "@lodestar/params": "^1.43.0-dev.8ad5d8be4c",
-    "@lodestar/types": "^1.43.0-dev.8ad5d8be4c",
-    "@lodestar/utils": "^1.43.0-dev.8ad5d8be4c",
+    "@lodestar/config": "^1.43.0-dev.8e18007572",
+    "@lodestar/params": "^1.43.0-dev.8e18007572",
+    "@lodestar/types": "^1.43.0-dev.8e18007572",
+    "@lodestar/utils": "^1.43.0-dev.8e18007572",
     "@vekexasia/bigint-buffer2": "^1.1.1"
   },
   "devDependencies": {
-    "@lodestar/api": "^1.43.0-dev.8ad5d8be4c"
+    "@lodestar/api": "^1.43.0-dev.8e18007572"
   },
   "keywords": [
     "ethereum",
@@ -82,5 +87,5 @@
     "beacon",
     "blockchain"
   ],
-  "gitHead": "52ad662fd29f20cdbd65d6083bc0a3008541b047"
+  "gitHead": "800bdf2d7346096735d753d5e74087966e96af00"
 }

package/src/lightClient/spec/index.ts

@@ -0,0 +1,101 @@
+import {BeaconConfig} from "@lodestar/config";
+import {UPDATE_TIMEOUT} from "@lodestar/params";
+import {
+  LightClientBootstrap,
+  LightClientFinalityUpdate,
+  LightClientOptimisticUpdate,
+  LightClientUpdate,
+  Slot,
+} from "@lodestar/types";
+import {computeSyncPeriodAtSlot} from "../../util/epoch.js";
+import {
+  type ProcessUpdateOpts,
+  getSyncCommitteeAtPeriod,
+  processLightClientUpdate,
+} from "./processLightClientUpdate.js";
+import {type ILightClientStore, LightClientStore, type LightClientStoreEvents} from "./store.js";
+import {ZERO_HEADER, ZERO_SYNC_COMMITTEE, getZeroFinalityBranch, getZeroSyncCommitteeBranch} from "./utils.js";
+
+export type {LightClientUpdateSummary} from "./isBetterUpdate.js";
+export {isBetterUpdate, toLightClientUpdateSummary} from "./isBetterUpdate.js";
+export {
+  type ProcessUpdateOpts,
+  getSyncCommitteeAtPeriod,
+  isSafeLightClientUpdate,
+  processLightClientUpdate,
+} from "./processLightClientUpdate.js";
+export {
+  type ILightClientStore,
+  LightClientStore,
+  type LightClientStoreEvents,
+  type LightClientUpdateWithSummary,
+  type SyncCommitteeFast,
+} from "./store.js";
+export {
+  getSafetyThreshold,
+  isFinalityUpdate,
+  isSyncCommitteeUpdate,
+  isValidLightClientHeader,
+  normalizeMerkleBranch,
+  upgradeLightClientFinalityUpdate,
+  upgradeLightClientHeader,
+  upgradeLightClientOptimisticUpdate,
+  upgradeLightClientStore,
+  upgradeLightClientUpdate,
+} from "./utils.js";
+export {validateLightClientBootstrap} from "./validateLightClientBootstrap.js";
+export {validateLightClientUpdate} from "./validateLightClientUpdate.js";
+
+export class LightclientSpec {
+  readonly store: ILightClientStore;
+  readonly config: BeaconConfig;
+
+  constructor(
+    config: BeaconConfig,
+    private readonly opts: ProcessUpdateOpts & LightClientStoreEvents,
+    bootstrap: LightClientBootstrap
+  ) {
+    this.store = new LightClientStore(config, bootstrap, opts);
+    this.config = config;
+  }
+
+  onUpdate(currentSlot: Slot, update: LightClientUpdate): void {
+    processLightClientUpdate(this.config, this.store, currentSlot, this.opts, update);
+  }
+
+  onFinalityUpdate(currentSlot: Slot, finalityUpdate: LightClientFinalityUpdate): void {
+    this.onUpdate(currentSlot, {
+      attestedHeader: finalityUpdate.attestedHeader,
+      nextSyncCommittee: ZERO_SYNC_COMMITTEE,
+      nextSyncCommitteeBranch: getZeroSyncCommitteeBranch(this.config.getForkName(finalityUpdate.signatureSlot)),
+      finalizedHeader: finalityUpdate.finalizedHeader,
+      finalityBranch: finalityUpdate.finalityBranch,
+      syncAggregate: finalityUpdate.syncAggregate,
+      signatureSlot: finalityUpdate.signatureSlot,
+    });
+  }
+
+  onOptimisticUpdate(currentSlot: Slot, optimisticUpdate: LightClientOptimisticUpdate): void {
+    this.onUpdate(currentSlot, {
+      attestedHeader: optimisticUpdate.attestedHeader,
+      nextSyncCommittee: ZERO_SYNC_COMMITTEE,
+      nextSyncCommitteeBranch: getZeroSyncCommitteeBranch(this.config.getForkName(optimisticUpdate.signatureSlot)),
+      finalizedHeader: {beacon: ZERO_HEADER},
+      finalityBranch: getZeroFinalityBranch(this.config.getForkName(optimisticUpdate.signatureSlot)),
+      syncAggregate: optimisticUpdate.syncAggregate,
+      signatureSlot: optimisticUpdate.signatureSlot,
+    });
+  }
+
+  forceUpdate(currentSlot: Slot): void {
+    for (const bestValidUpdate of this.store.bestValidUpdates.values()) {
+      if (currentSlot > bestValidUpdate.update.finalizedHeader.beacon.slot + UPDATE_TIMEOUT) {
+        const updatePeriod = computeSyncPeriodAtSlot(bestValidUpdate.update.signatureSlot);
+        // Simulate process_light_client_store_force_update() by forcing to apply a bestValidUpdate
+        // https://github.com/ethereum/consensus-specs/blob/a57e15636013eeba3610ff3ade41781dba1bb0cd/specs/altair/light-client/sync-protocol.md?plain=1#L394
+        // Call for `updatePeriod + 1` to force the update at `update.signatureSlot` to be applied
+        getSyncCommitteeAtPeriod(this.store, updatePeriod + 1, this.opts);
+      }
+    }
+  }
+}

package/src/lightClient/spec/isBetterUpdate.ts

@@ -0,0 +1,94 @@
+import {SYNC_COMMITTEE_SIZE} from "@lodestar/params";
+import {LightClientUpdate, Slot} from "@lodestar/types";
+import {computeSyncPeriodAtSlot} from "../../util/epoch.js";
+import {isFinalityUpdate, isSyncCommitteeUpdate, sumBits} from "./utils.js";
+
+/**
+ * Wrapper type for `isBetterUpdate()` so we can apply its logic without requiring the full LightClientUpdate type.
+ */
+export type LightClientUpdateSummary = {
+  activeParticipants: number;
+  attestedHeaderSlot: Slot;
+  signatureSlot: Slot;
+  finalizedHeaderSlot: Slot;
+  /** `if update.next_sync_committee_branch != [Bytes32() for _ in range(floorlog2(NEXT_SYNC_COMMITTEE_INDEX))]` */
+  isSyncCommitteeUpdate: boolean;
+  /** `if update.finality_branch != [Bytes32() for _ in range(floorlog2(FINALIZED_ROOT_INDEX))]` */
+  isFinalityUpdate: boolean;
+};
+
+/**
+ * Returns the update with more bits. On ties, prevUpdate is the better
+ *
+ * https://github.com/ethereum/consensus-specs/blob/be3c774069e16e89145660be511c1b183056017e/specs/altair/light-client/sync-protocol.md#is_better_update
+ */
+export function isBetterUpdate(newUpdate: LightClientUpdateSummary, oldUpdate: LightClientUpdateSummary): boolean {
+  // Compare supermajority (> 2/3) sync committee participation
+  const newNumActiveParticipants = newUpdate.activeParticipants;
+  const oldNumActiveParticipants = oldUpdate.activeParticipants;
+  const newHasSupermajority = newNumActiveParticipants * 3 >= SYNC_COMMITTEE_SIZE * 2;
+  const oldHasSupermajority = oldNumActiveParticipants * 3 >= SYNC_COMMITTEE_SIZE * 2;
+  if (newHasSupermajority !== oldHasSupermajority) {
+    return newHasSupermajority;
+  }
+  if (!newHasSupermajority && newNumActiveParticipants !== oldNumActiveParticipants) {
+    return newNumActiveParticipants > oldNumActiveParticipants;
+  }
+
+  // Compare presence of relevant sync committee
+  const newHasRelevantSyncCommittee =
+    newUpdate.isSyncCommitteeUpdate &&
+    computeSyncPeriodAtSlot(newUpdate.attestedHeaderSlot) === computeSyncPeriodAtSlot(newUpdate.signatureSlot);
+  const oldHasRelevantSyncCommittee =
+    oldUpdate.isSyncCommitteeUpdate &&
+    computeSyncPeriodAtSlot(oldUpdate.attestedHeaderSlot) === computeSyncPeriodAtSlot(oldUpdate.signatureSlot);
+  if (newHasRelevantSyncCommittee !== oldHasRelevantSyncCommittee) {
+    return newHasRelevantSyncCommittee;
+  }
+
+  // Compare indication of any finality
+  const newHasFinality = newUpdate.isFinalityUpdate;
+  const oldHasFinality = oldUpdate.isFinalityUpdate;
+  if (newHasFinality !== oldHasFinality) {
+    return newHasFinality;
+  }
+
+  // Compare sync committee finality
+  if (newHasFinality) {
+    const newHasSyncCommitteeFinality =
+      computeSyncPeriodAtSlot(newUpdate.finalizedHeaderSlot) === computeSyncPeriodAtSlot(newUpdate.attestedHeaderSlot);
+    const oldHasSyncCommitteeFinality =
+      computeSyncPeriodAtSlot(oldUpdate.finalizedHeaderSlot) === computeSyncPeriodAtSlot(oldUpdate.attestedHeaderSlot);
+    if (newHasSyncCommitteeFinality !== oldHasSyncCommitteeFinality) {
+      return newHasSyncCommitteeFinality;
+    }
+  }
+
+  // Tiebreaker 1: Sync committee participation beyond supermajority
+  if (newNumActiveParticipants !== oldNumActiveParticipants) {
+    return newNumActiveParticipants > oldNumActiveParticipants;
+  }
+
+  // Tiebreaker 2: Prefer older data (fewer changes to best)
+  if (newUpdate.attestedHeaderSlot !== oldUpdate.attestedHeaderSlot) {
+    return newUpdate.attestedHeaderSlot < oldUpdate.attestedHeaderSlot;
+  }
+  return newUpdate.signatureSlot < oldUpdate.signatureSlot;
+}
+
+export function isSafeLightClientUpdate(update: LightClientUpdateSummary): boolean {
+  return (
+    update.activeParticipants * 3 >= SYNC_COMMITTEE_SIZE * 2 && update.isFinalityUpdate && update.isSyncCommitteeUpdate
+  );
+}
+
+export function toLightClientUpdateSummary(update: LightClientUpdate): LightClientUpdateSummary {
+  return {
+    activeParticipants: sumBits(update.syncAggregate.syncCommitteeBits),
+    attestedHeaderSlot: update.attestedHeader.beacon.slot,
+    signatureSlot: update.signatureSlot,
+    finalizedHeaderSlot: update.finalizedHeader.beacon.slot,
+    isSyncCommitteeUpdate: isSyncCommitteeUpdate(update),
+    isFinalityUpdate: isFinalityUpdate(update),
+  };
+}