Serve Lightclient related data via p2p (#4365)

* rename to LightClientBootstrap to keep consistent with spec

* updating types in preparation to start serving LightClientBootstrap via p2p resp/req

* should be able to serve LightClientBootstrap via p2p

* aligning types in preparation to be able to serve light client update via p2p

* added a comment to take care of error handling for light client bootstrap

* fix type error

* handle error when lighclientBootstrap cannot be returned

* Add ability to serve LightclientUpdate via p2p req/resp

* Aligning types in prep for being able to serve LightClientFinalityUpdate via p2p resp/req

* Added ability to serve LightClientFinalityUpdate via p2p req/resp

* Serving lightclientFinalityUpdate via p2p

* fix check types

* fix failing lightclient.test.ts test

* fix check-types check

* fix check-types check

* initial changes to have light_client_optimistic_update and light_client_optimistic_update available via the gossip domain

* adding placeholder for validating lightclient's gossip messages

* Added some validation to LightClientFinalityUpdate

* added more gossip validation

* fix check-types errors

* temp disable test

* Unit tests should now be passing

* explicitly binding this to function passed to the chain event emitter handler

* removed TODO comment after processing it

* undo removal of space

* LightClientOptimisticUpdate has no request

* update to return corrosponding ssz type to lightclient gossip type

* turn runtime error to compile time error

* extend gossipsub.test to include tests for LightClientOptimisticUpdate and LightClientFinalityUpdate

* Fix build failure

* Also unsubscribe lightclient's gossip global topics

* Logging topics for debugging in CI

* debugging in CI

* do not override zeroProtoBlock

* removing cli debugging changes

* run the network.test within altair

* split lightclient gossip validation to seperate files

* adding tests for validateLightClientOptimisticUpdate

* undo unintended changes

* Added Light Client Finality Update validation

* corrected type name to be aligned with spec

* extend onRequest with light client

* fix test

* properly setting signatureSlot

* wrapped getting onLightclientUpdate via res/req in a try catch

* Align light client objects naming with spec

* remove comment

* process some TODO

* Add ability to request lightClientBootstrap via Req/Resp

* added ability to request light client optimistic and finality update via req/res

* Add ability to request light client update message via Req/Res channel

* renabled skipped test

* process LightClientUpdate via SSE also

* undo unintended committed changes

* remove unnecessary promise resolve

* remove unnecessary promise resolve

* temp undo commit cd4b595 and c5ca43c

* Revert "temp undo commit cd4b595 and c5ca43c"

This reverts commit b44db38.

* yield LightClientUpdate instead of LightClientUpdates

* removed unused type

* fix compilation in tests

* improve error handling for getOptimisticUpdate

* improve error handling for getFinalityUpdate

* avoid voiding promise. Fix lint errors

* Switch to debug level to prevent unnecessary PublishError.InsufficientPeers

* Adding back promises to api client functions

* resolved confilict/merged in unstable

* Move setting of latestForwardedFinalitySlot and latestForwardedOptimisticSlot from validation logic

* Use correct version for Res/Req

* Use correct version for Res/Req

* use one event stream

* removed redundant async

* Fix tests due to removal of async

* Fixed test

* Do not forward if local light client updates do not exist yet

* fix lightClientOptimisticUpdate.test and wait 1/3 slot before publishing

* Added tests for scenarios where validation does not fail for validateLightClientFinalityUpdate and validateLightClientOptimisticUpdate

* Remove redefinition of Root. Removed utility functions in test

* Passing in syncAggregate and signatureSlot instead of whole block

* Make getUpdates more flexible

* use strong equality check

* do not publish events if sync committee is below MIN_SYNC_COMMITTEE_PARTICIPANTS

* doGetUpdate => getUpdate. private => public

* Allow gaps in light client updates instead of throwing

* Address pr comments

* Remove light client latest cached slot

* Revert "Remove light client latest cached slot"

This reverts commit 50fe56f.

* Use simple for loop

* Remove trailing slash from lightclient apis

* Fix finality update gossip validation

* fixing failing tests

* invalid with not matching local when no local update yet

* Limit REST getUpdates response to MAX_REQUEST_LIGHT_CLIENT_UPDATES

* unbind listeners on close

* removed the need to bind to this

* fix lint

* wait one third before publishing lc updates in on onSyncAggregate

* Revert "wait one third before publishing lc updates in on onSyncAggregate"

This reverts commit 003a233.

* update waiting logic before publishing lc update to network

* making use of abort signal when sleeping

* only publish lc updates if node has atleast one sync committee member

* Remove stray comment

* Use strict equals

* More consistent naming

* Reorg reqresp methods

* Add light client server error

* Fix seconds to miliseconds typo

* Remove need for -1 default

* Remove unnecessary arrow function

* Allow to publish to zero peers

* Use spec name LightClientUpdatesByRange

* Clarify FINALITY_UPDATE_RECEIVED_TOO_EARLY math

* De-duplicate updateReceivedToEarly condition

* Update emit comments

* Fix typo in updateReceivedTooEarly

Co-authored-by: Cayman <caymannava@gmail.com>
Co-authored-by: dapplion <35266934+dapplion@users.noreply.github.com>

packages/api/src/beacon/routes/events.ts

@@ -5,18 +5,6 @@ import {RouteDef, TypeJson} from "../../utils/index.js";
 
 // See /packages/api/src/routes/index.ts for reasoning and instructions to add new routes
 
-export type LightclientOptimisticHeaderUpdate = {
-  syncAggregate: altair.SyncAggregate;
-  attestedHeader: phase0.BeaconBlockHeader;
-};
-
-export type LightclientFinalizedUpdate = {
-  attestedHeader: phase0.BeaconBlockHeader;
-  finalizedHeader: phase0.BeaconBlockHeader;
-  finalityBranch: Uint8Array[];
-  syncAggregate: altair.SyncAggregate;
-};
-
 export enum EventType {
   /**
    * The node has finished processing, resulting in a new head. previous_duty_dependent_root is
@@ -38,9 +26,11 @@ export enum EventType {
   /** The node has received a valid sync committee SignedContributionAndProof (from P2P or API) */
   contributionAndProof = "contribution_and_proof",
   /** New or better optimistic header update available */
-  lightclientOptimisticUpdate = "light_client_optimistic_update",
-  /** New or better finalized update available */
-  lightclientFinalizedUpdate = "light_client_finalized_update",
+  lightClientOptimisticUpdate = "light_client_optimistic_update",
+  /** New or better finality update available */
+  lightClientFinalityUpdate = "light_client_finality_update",
+  /** New or better light client update available */
+  lightClientUpdate = "light_client_update",
 }
 
 export type EventData = {
@@ -77,8 +67,9 @@ export type EventData = {
     executionOptimistic: boolean;
   };
   [EventType.contributionAndProof]: altair.SignedContributionAndProof;
-  [EventType.lightclientOptimisticUpdate]: LightclientOptimisticHeaderUpdate;
-  [EventType.lightclientFinalizedUpdate]: LightclientFinalizedUpdate;
+  [EventType.lightClientOptimisticUpdate]: altair.LightClientOptimisticUpdate;
+  [EventType.lightClientFinalityUpdate]: altair.LightClientFinalityUpdate;
+  [EventType.lightClientUpdate]: altair.LightClientUpdate;
 };
 
 export type BeaconEvent = {[K in EventType]: {type: K; message: EventData[K]}}[EventType];
@@ -163,22 +154,25 @@ export function getTypeByEvent(): {[K in EventType]: Type<EventData[K]>} {
 
     [EventType.contributionAndProof]: ssz.altair.SignedContributionAndProof,
 
-    [EventType.lightclientOptimisticUpdate]: new ContainerType(
+    [EventType.lightClientOptimisticUpdate]: new ContainerType(
       {
         syncAggregate: ssz.altair.SyncAggregate,
         attestedHeader: ssz.phase0.BeaconBlockHeader,
+        signatureSlot: ssz.Slot,
       },
       {jsonCase: "eth2"}
     ),
-    [EventType.lightclientFinalizedUpdate]: new ContainerType(
+    [EventType.lightClientFinalityUpdate]: new ContainerType(
       {
         attestedHeader: ssz.phase0.BeaconBlockHeader,
         finalizedHeader: ssz.phase0.BeaconBlockHeader,
         finalityBranch: new VectorCompositeType(ssz.Bytes32, FINALIZED_ROOT_DEPTH),
         syncAggregate: ssz.altair.SyncAggregate,
+        signatureSlot: ssz.Slot,
       },
       {jsonCase: "eth2"}
     ),
+    [EventType.lightClientUpdate]: ssz.altair.LightClientUpdate,
   };
 }
 

packages/api/src/beacon/routes/lightclient.ts

@@ -1,6 +1,5 @@
-import {ContainerType, JsonPath, VectorCompositeType} from "@chainsafe/ssz";
+import {JsonPath} from "@chainsafe/ssz";
 import {Proof} from "@chainsafe/persistent-merkle-tree";
-import {FINALIZED_ROOT_DEPTH} from "@lodestar/params";
 import {altair, phase0, ssz, SyncPeriod} from "@lodestar/types";
 import {
   ArrayOf,
@@ -14,14 +13,10 @@ import {
   ReqEmpty,
 } from "../../utils/index.js";
 import {queryParseProofPathsArr, querySerializeProofPathsArr} from "../../utils/serdes.js";
-import {LightclientOptimisticHeaderUpdate, LightclientFinalizedUpdate} from "./events.js";
-
-// Re-export for convenience when importing routes.lightclient.LightclientOptimisticHeaderUpdate
-export {LightclientOptimisticHeaderUpdate, LightclientFinalizedUpdate};
 
 // See /packages/api/src/routes/index.ts for reasoning and instructions to add new routes
 
-export type LightclientSnapshotWithProof = {
+export type LightClientBootstrap = {
   header: phase0.BeaconBlockHeader;
   currentSyncCommittee: altair.SyncCommittee;
   /** Single branch proof from state root to currentSyncCommittee */
@@ -46,14 +41,14 @@ export type Api = {
    * Returns the latest optimistic head update available. Clients should use the SSE type `light_client_optimistic_update`
    * unless to get the very first head update after syncing, or if SSE are not supported by the server.
    */
-  getOptimisticUpdate(): Promise<{data: LightclientOptimisticHeaderUpdate}>;
-  getFinalityUpdate(): Promise<{data: LightclientFinalizedUpdate}>;
+  getOptimisticUpdate(): Promise<{data: altair.LightClientOptimisticUpdate}>;
+  getFinalityUpdate(): Promise<{data: altair.LightClientFinalityUpdate}>;
   /**
    * Fetch a bootstrapping state with a proof to a trusted block root.
    * The trusted block root should be fetched with similar means to a weak subjectivity checkpoint.
    * Only block roots for checkpoints are guaranteed to be available.
    */
-  getBootstrap(blockRoot: string): Promise<{data: LightclientSnapshotWithProof}>;
+  getBootstrap(blockRoot: string): Promise<{data: LightClientBootstrap}>;
 };
 
 /**
@@ -62,8 +57,8 @@ export type Api = {
 export const routesData: RoutesData<Api> = {
   getStateProof: {url: "/eth/v1/beacon/light_client/proof/{state_id}", method: "GET"},
   getUpdates: {url: "/eth/v1/beacon/light_client/updates", method: "GET"},
-  getOptimisticUpdate: {url: "/eth/v1/beacon/light_client/optimistic_update/", method: "GET"},
-  getFinalityUpdate: {url: "/eth/v1/beacon/light_client/finality_update/", method: "GET"},
+  getOptimisticUpdate: {url: "/eth/v1/beacon/light_client/optimistic_update", method: "GET"},
+  getFinalityUpdate: {url: "/eth/v1/beacon/light_client/finality_update", method: "GET"},
   getBootstrap: {url: "/eth/v1/beacon/light_client/bootstrap/{block_root}", method: "GET"},
 };
 
@@ -102,39 +97,12 @@ export function getReqSerializers(): ReqSerializers<Api, ReqTypes> {
 }
 
 export function getReturnTypes(): ReturnTypes<Api> {
-  const lightclientSnapshotWithProofType = new ContainerType(
-    {
-      header: ssz.phase0.BeaconBlockHeader,
-      currentSyncCommittee: ssz.altair.SyncCommittee,
-      currentSyncCommitteeBranch: new VectorCompositeType(ssz.Root, 5),
-    },
-    {jsonCase: "eth2"}
-  );
-
-  const lightclientHeaderUpdate = new ContainerType(
-    {
-      syncAggregate: ssz.altair.SyncAggregate,
-      attestedHeader: ssz.phase0.BeaconBlockHeader,
-    },
-    {jsonCase: "eth2"}
-  );
-
-  const lightclientFinalizedUpdate = new ContainerType(
-    {
-      attestedHeader: ssz.phase0.BeaconBlockHeader,
-      finalizedHeader: ssz.phase0.BeaconBlockHeader,
-      finalityBranch: new VectorCompositeType(ssz.Bytes32, FINALIZED_ROOT_DEPTH),
-      syncAggregate: ssz.altair.SyncAggregate,
-    },
-    {jsonCase: "eth2"}
-  );
-
   return {
     // Just sent the proof JSON as-is
     getStateProof: sameType(),
     getUpdates: ContainerData(ArrayOf(ssz.altair.LightClientUpdate)),
-    getOptimisticUpdate: ContainerData(lightclientHeaderUpdate),
-    getFinalityUpdate: ContainerData(lightclientFinalizedUpdate),
-    getBootstrap: ContainerData(lightclientSnapshotWithProofType),
+    getOptimisticUpdate: ContainerData(ssz.altair.LightClientOptimisticUpdate),
+    getFinalityUpdate: ContainerData(ssz.altair.LightClientFinalityUpdate),
+    getBootstrap: ContainerData(ssz.altair.LightClientBootstrap),
   };
 }

packages/api/test/unit/beacon/testData/events.ts

@@ -81,14 +81,17 @@ export const eventTestData: EventData = {
     signature:
       "0xac118511474a94f857300b315c50585c32a713e4452e26a6bb98cdb619936370f126ed3b6bb64469259ee92e69791d9e12d324ce6fd90081680ce72f39d85d50b0ff977260a8667465e613362c6d6e6e745e1f9323ec1d6f16041c4e358839ac",
   }),
-  [EventType.lightclientOptimisticUpdate]: {
+  [EventType.lightClientOptimisticUpdate]: {
     syncAggregate: ssz.altair.SyncAggregate.defaultValue(),
     attestedHeader: ssz.phase0.BeaconBlockHeader.defaultValue(),
+    signatureSlot: ssz.Slot.defaultValue(),
   },
-  [EventType.lightclientFinalizedUpdate]: {
+  [EventType.lightClientFinalityUpdate]: {
     attestedHeader: ssz.phase0.BeaconBlockHeader.defaultValue(),
     finalizedHeader: ssz.phase0.BeaconBlockHeader.defaultValue(),
     finalityBranch: [root],
     syncAggregate: ssz.altair.SyncAggregate.defaultValue(),
+    signatureSlot: ssz.Slot.defaultValue(),
   },
+  [EventType.lightClientUpdate]: ssz.altair.LightClientUpdate.defaultValue(),
 };

packages/api/test/unit/beacon/testData/lightclient.ts

@@ -9,6 +9,7 @@ const root = Uint8Array.from(Buffer.alloc(32, 1));
 const lightClientUpdate = ssz.altair.LightClientUpdate.defaultValue();
 const syncAggregate = ssz.altair.SyncAggregate.defaultValue();
 const header = ssz.phase0.BeaconBlockHeader.defaultValue();
+const signatureSlot = ssz.Slot.defaultValue();
 
 export const testData: GenericServerTestCases<Api> = {
   getStateProof: {
@@ -41,7 +42,7 @@ export const testData: GenericServerTestCases<Api> = {
   },
   getOptimisticUpdate: {
     args: [],
-    res: {data: {syncAggregate, attestedHeader: header}},
+    res: {data: {syncAggregate, attestedHeader: header, signatureSlot}},
   },
   getFinalityUpdate: {
     args: [],
@@ -51,6 +52,7 @@ export const testData: GenericServerTestCases<Api> = {
         attestedHeader: header,
         finalizedHeader: lightClientUpdate.finalizedHeader,
         finalityBranch: lightClientUpdate.finalityBranch,
+        signatureSlot: lightClientUpdate.attestedHeader.slot + 1,
       },
     },
   },

packages/beacon-node/src/api/impl/events/index.ts

@@ -16,8 +16,9 @@ const chainEventMap = {
   [routes.events.EventType.finalizedCheckpoint]: ChainEvent.finalized as const,
   [routes.events.EventType.chainReorg]: ChainEvent.forkChoiceReorg as const,
   [routes.events.EventType.contributionAndProof]: ChainEvent.contributionAndProof as const,
-  [routes.events.EventType.lightclientOptimisticUpdate]: ChainEvent.lightclientOptimisticUpdate as const,
-  [routes.events.EventType.lightclientFinalizedUpdate]: ChainEvent.lightclientFinalizedUpdate as const,
+  [routes.events.EventType.lightClientOptimisticUpdate]: ChainEvent.lightClientOptimisticUpdate as const,
+  [routes.events.EventType.lightClientFinalityUpdate]: ChainEvent.lightClientFinalityUpdate as const,
+  [routes.events.EventType.lightClientUpdate]: ChainEvent.lightClientUpdate as const,
 };
 
 export function getEventsApi({chain, config}: Pick<ApiModules, "chain" | "config">): routes.events.Api {
@@ -60,8 +61,9 @@ export function getEventsApi({chain, config}: Pick<ApiModules, "chain" | "config
       },
     ],
     [routes.events.EventType.contributionAndProof]: (contributionAndProof) => [contributionAndProof],
-    [routes.events.EventType.lightclientOptimisticUpdate]: (headerUpdate) => [headerUpdate],
-    [routes.events.EventType.lightclientFinalizedUpdate]: (headerUpdate) => [headerUpdate],
+    [routes.events.EventType.lightClientOptimisticUpdate]: (headerUpdate) => [headerUpdate],
+    [routes.events.EventType.lightClientFinalityUpdate]: (headerUpdate) => [headerUpdate],
+    [routes.events.EventType.lightClientUpdate]: (headerUpdate) => [headerUpdate],
   };
 
   return {

packages/beacon-node/src/api/impl/lightclient/index.ts

@@ -1,6 +1,8 @@
 import {routes} from "@lodestar/api";
 import {fromHexString} from "@chainsafe/ssz";
 import {ProofType, Tree} from "@chainsafe/persistent-merkle-tree";
+import {SyncPeriod} from "@lodestar/types";
+import {MAX_REQUEST_LIGHT_CLIENT_UPDATES} from "@lodestar/params";
 import {ApiModules} from "../types.js";
 import {resolveStateId} from "../beacon/state/utils.js";
 import {IApiOptions} from "../../options.js";
@@ -41,19 +43,27 @@ export function getLightclientApi(
       };
     },
 
-    // eslint-disable-next-line @typescript-eslint/naming-convention
-    async getUpdates(start_period, count) {
-      const periods = Array.from({length: count}, (_ignored, i) => i + start_period);
-      const updates = await Promise.all(periods.map((period) => chain.lightClientServer.getUpdates(period)));
+    async getUpdates(startPeriod: SyncPeriod, count: number) {
+      const maxAllowedCount = Math.min(MAX_REQUEST_LIGHT_CLIENT_UPDATES, count);
+      const periods = Array.from({length: maxAllowedCount}, (_ignored, i) => i + startPeriod);
+      const updates = await Promise.all(periods.map((period) => chain.lightClientServer.getUpdate(period)));
       return {data: updates};
     },
 
     async getOptimisticUpdate() {
-      return {data: await chain.lightClientServer.getOptimisticUpdate()};
+      const data = chain.lightClientServer.getOptimisticUpdate();
+      if (data === null) {
+        throw Error("No optimistic update available");
+      }
+      return {data};
     },
 
     async getFinalityUpdate() {
-      return {data: await chain.lightClientServer.getFinalityUpdate()};
+      const data = chain.lightClientServer.getFinalityUpdate();
+      if (data === null) {
+        throw Error("No finality update available");
+      }
+      return {data};
     },
 
     async getBootstrap(blockRoot) {

packages/beacon-node/src/chain/emitter.ts

@@ -88,11 +88,15 @@ export enum ChainEvent {
   /**
    * A new lightclient optimistic header update is available to be broadcasted to connected light-clients
    */
-  lightclientOptimisticUpdate = "lightclient:header_update",
+  lightClientOptimisticUpdate = "lightclient:header_update",
   /**
    * A new lightclient finalized header update is available to be broadcasted to connected light-clients
    */
-  lightclientFinalizedUpdate = "lightclient:finalized_update",
+  lightClientFinalityUpdate = "lightclient:finality_update",
+  /**
+   * A new lightclient update is available to be broadcasted to connected light-clients
+   */
+  lightClientUpdate = "lightclient:update",
 }
 
 export type HeadEventData = routes.events.EventData[routes.events.EventType.head];
@@ -114,8 +118,9 @@ export interface IChainEvents {
   [ChainEvent.forkChoiceJustified]: (checkpoint: CheckpointWithHex) => void;
   [ChainEvent.forkChoiceFinalized]: (checkpoint: CheckpointWithHex) => void;
 
-  [ChainEvent.lightclientOptimisticUpdate]: (optimisticUpdate: routes.events.LightclientOptimisticHeaderUpdate) => void;
-  [ChainEvent.lightclientFinalizedUpdate]: (finalizedUpdate: routes.events.LightclientFinalizedUpdate) => void;
+  [ChainEvent.lightClientOptimisticUpdate]: (optimisticUpdate: altair.LightClientOptimisticUpdate) => void;
+  [ChainEvent.lightClientFinalityUpdate]: (finalizedUpdate: altair.LightClientFinalityUpdate) => void;
+  [ChainEvent.lightClientUpdate]: (update: altair.LightClientUpdate) => void;
 }
 
 /**

packages/beacon-node/src/chain/errors/lightClientError.ts

@@ -0,0 +1,30 @@
+import {LodestarError} from "@lodestar/utils";
+import {GossipActionError} from "./gossipValidation.js";
+
+export enum LightClientErrorCode {
+  FINALITY_UPDATE_ALREADY_FORWARDED = "FINALITY_UPDATE_ALREADY_FORWARDED",
+  OPTIMISTIC_UPDATE_ALREADY_FORWARDED = "OPTIMISTIC_UPDATE_ALREADY_FORWARDED",
+  FINALITY_UPDATE_RECEIVED_TOO_EARLY = "FINALITY_UPDATE_RECEIVED_TOO_EARLY",
+  OPTIMISTIC_UPDATE_RECEIVED_TOO_EARLY = "OPTIMISTIC_UPDATE_RECEIVED_TOO_EARLY",
+  FINALITY_UPDATE_NOT_MATCHING_LOCAL = "FINALITY_UPDATE_NOT_MATCHING_LOCAL",
+  OPTIMISTIC_UPDATE_NOT_MATCHING_LOCAL = "OPTIMISTIC_UPDATE_NOT_MATCHING_LOCAL",
+}
+export type LightClientErrorType =
+  | {code: LightClientErrorCode.FINALITY_UPDATE_ALREADY_FORWARDED}
+  | {code: LightClientErrorCode.OPTIMISTIC_UPDATE_ALREADY_FORWARDED}
+  | {code: LightClientErrorCode.FINALITY_UPDATE_RECEIVED_TOO_EARLY}
+  | {code: LightClientErrorCode.OPTIMISTIC_UPDATE_RECEIVED_TOO_EARLY}
+  | {code: LightClientErrorCode.FINALITY_UPDATE_NOT_MATCHING_LOCAL}
+  | {code: LightClientErrorCode.OPTIMISTIC_UPDATE_NOT_MATCHING_LOCAL};
+
+export class LightClientError extends GossipActionError<LightClientErrorType> {}
+
+// Errors for the light client server
+
+export enum LightClientServerErrorCode {
+  RESOURCE_UNAVAILABLE = "RESOURCE_UNAVALIABLE",
+}
+
+export type LightClientServerErrorType = {code: LightClientServerErrorCode.RESOURCE_UNAVAILABLE};
+
+export class LightClientServerError extends LodestarError<LightClientServerErrorType> {}