feat: add support for browser bundle for lightclient

.eslintrc.js

@@ -194,7 +194,14 @@ module.exports = {
   },
   overrides: [
     {
-      files: ["**/*.config.js", "**/*.config.mjs", "**/*.config.cjs", "**/*.config.ts"],
+      files: [
+        "**/*.config.js",
+        "**/*.config.mjs",
+        "**/*.config.cjs",
+        "**/*.config.ts",
+        "scripts/vitest/**/*.ts",
+        "scripts/vite/**/*.ts",
+      ],
       rules: {
         "@typescript-eslint/naming-convention": "off",
         // Allow require in CJS modules

.gitignore

@@ -1,6 +1,7 @@
 .__testdb*
 node_modules/
 lib
+dist
 .nyc_output/
 coverage/**
 .DS_Store
@@ -21,6 +22,7 @@ validators
 **/coverage
 **/node_modules
 **/lib
+**/dist
 **/.nyc_output
 .tmp
 .vscode

.wordlist.txt

@@ -98,6 +98,7 @@ blockRoot
 blockchain
 bootnode
 bootnodes
+bundlers
 chainConfig
 chainsafe
 chiado
@@ -193,11 +194,14 @@ testnets
 todo
 typesafe
 udp
+unpkg
 util
 utils
 validator
 validators
+vite
 vitest
+webpack
 wip
 xcode
 yaml

package.json

@@ -51,8 +51,8 @@
     "@types/node": "^20.11.28",
     "@typescript-eslint/eslint-plugin": "^7.2.0",
     "@typescript-eslint/parser": "^7.2.0",
-    "@vitest/coverage-v8": "^1.4.0",
-    "@vitest/browser": "^1.4.0",
+    "@vitest/coverage-v8": "^1.5.0",
+    "@vitest/browser": "^1.5.0",
     "crypto-browserify": "^3.12.0",
     "dotenv": "^16.4.5",
     "electron": "^26.2.2",
@@ -71,6 +71,7 @@
     "path-browserify": "^1.0.1",
     "prettier": "^3.2.5",
     "process": "^0.11.10",
+    "rollup-plugin-visualizer": "^5.12.0",
     "stream-browserify": "^3.0.0",
     "stream-http": "^3.2.0",
     "supertest": "^6.3.3",
@@ -79,7 +80,8 @@
     "typescript-docs-verifier": "^2.5.0",
     "vite-plugin-node-polyfills": "^0.21.0",
     "vite-plugin-top-level-await": "^1.4.1",
-    "vitest": "^1.4.0",
+    "vite": "^5.2.9",
+    "vitest": "^1.5.0",
     "vitest-when": "^0.3.1",
     "wait-port": "^1.1.0",
     "webdriverio": "^8.34.1"
@@ -88,6 +90,6 @@
     "@puppeteer/browsers": "^2.1.0",
     "dns-over-http-resolver": "^2.1.1",
     "loupe": "^2.3.6",
-    "vite": "^5.0.0"
+    "vite": "^5.2.9"
   }
 }

packages/beacon-node/vitest.config.ts

@@ -1,5 +1,5 @@
 import {defineConfig, mergeConfig} from "vitest/config";
-import {buildTargetPlugin} from "../../scripts/vitest/plugins/buildTargetPlugin.js";
+import {buildTargetPlugin} from "../../scripts/vite/plugins/buildTargetPlugin.js";
 import vitestConfig from "../../vitest.base.unit.config";
 
 export default mergeConfig(

packages/beacon-node/vitest.e2e.config.ts

@@ -1,5 +1,5 @@
 import {defineConfig, mergeConfig} from "vitest/config";
-import {buildTargetPlugin} from "../../scripts/vitest/plugins/buildTargetPlugin";
+import {buildTargetPlugin} from "../../scripts/vite/plugins/buildTargetPlugin";
 import vitestConfig from "../../vitest.base.e2e.config";
 
 export default mergeConfig(

packages/beacon-node/vitest.spec.config.ts

@@ -1,5 +1,5 @@
 import {defineConfig, mergeConfig} from "vitest/config";
-import {buildTargetPlugin} from "../../scripts/vitest/plugins/buildTargetPlugin";
+import {buildTargetPlugin} from "../../scripts/vite/plugins/buildTargetPlugin";
 import vitestConfig from "../../vitest.base.spec.config";
 
 export default mergeConfig(

packages/light-client/README.md

@@ -41,14 +41,14 @@ It is possible to start up the light-client as a standalone process.
 
 ```bash
 lodestar lightclient \
-    --network mainnet \
-    --beacon-api-url https://beacon-node.your-domain.com \
+    --network sepolia \
+    --beacon-api-url https://lodestar-sepolia.chainsafe.io \
     --checkpoint-root "0xccaff4b99986a7b05e06738f1828a32e40799b277fd9f9ff069be55341fe0229"
 ```
 
 ## Light-Client Programmatic Example
 
-For this example we will assume there is a running beacon node at `https://beacon-node.your-domain.com`
+For this example we will assume there is a running beacon node at `https://lodestar-sepolia.chainsafe.io`
 
 If you are running light-client on a server/node environment there is a faster version of bls that can help with performance. It is a peerDependency and needs to be installed separately by the consumer of this package. This was done so that for browser situations there is not a hard requirement for node-only code that will cause bundling errors. On startup, if running in a node environment, and `@chainsafe/blst` is installed the LightClient will automatically use the faster bls bindings.
 
@@ -57,16 +57,19 @@ npm i -S @chainsafe/blst
 ```
 
 ```ts
-import {getClient} from "@lodestar/api";
-import {createChainForkConfig} from "@lodestar/config";
-import {networksChainConfig} from "@lodestar/config/networks";
 import {Lightclient, LightclientEvent} from "@lodestar/light-client";
 import {LightClientRestTransport} from "@lodestar/light-client/transport";
-import {getFinalizedSyncCheckpoint, getGenesisData, getLcLoggerConsole} from "@lodestar/light-client/utils";
-
-const config = createChainForkConfig(networksChainConfig.mainnet);
-const logger = getLcLoggerConsole({logDebug: Boolean(process.env.DEBUG)});
-const api = getClient({urls: ["https://beacon-node.your-domain.com"]}, {config});
+import {
+  getFinalizedSyncCheckpoint,
+  getGenesisData,
+  getConsoleLogger,
+  getApiFromUrl,
+  getChainForkConfigFromNetwork,
+} from "@lodestar/light-client/utils";
+
+const config = getChainForkConfigFromNetwork("sepolia");
+const logger = getConsoleLogger({logDebug: Boolean(process.env.DEBUG)});
+const api = getApiFromUrl({urls: ["https://lodestar-sepolia.chainsafe.io"]}, {config});
 
 const lightclient = await Lightclient.initializeFromCheckpointRoot({
   config,
@@ -94,6 +97,31 @@ lightclient.emitter.on(LightclientEvent.lightClientOptimisticHeader, async (opti
 });
 ```
 
+## Browser Integration
+
+If you want to use Lightclient in browser and facing some issues in building it with bundlers like webpack, vite. We suggest to use our distribution build. The support for single distribution build is started from `1.19.0` version.
+
+Directly link the dist build with the `<script />` tag with tools like unpkg or other. e.g.
+
+```html
+<script src="https://www.unpkg.com/@lodestar/light-client@1.18.0/dist/lightclient.es.min.js" type="module">
+```
+
+Then the lightclient package will be exposed to `globalThis`, in case of browser environment that will be `window`. You can access the package as `window.lodestar.lightclient`. All named exports will also be available from this interface. e.g. `window.lodestar.lightclient.transport`.
+
+NOTE: Due to `top-level-await` used in one of dependent library, the package will not be available right after the load. You have to use a hack to clear up that await from the event loop.
+
+```html
+<script>
+  window.addEventListener("DOMContentLoaded", () => {
+    setTimeout(function () {
+      // here you can access the Lightclient
+      // window.lodestar.lightclient
+    }, 50);
+  });
+</script>
+```
+
 ## Contributors
 
 Read our [contribution documentation](https://chainsafe.github.io/lodestar/contribution/getting-started), [submit an issue](https://github.com/ChainSafe/lodestar/issues/new/choose) or talk to us on our [discord](https://discord.gg/yjyvFRP)!

packages/light-client/package.json

@@ -45,22 +45,29 @@
     "lib/**/*.js",
     "lib/**/*.js.map",
     "*.d.ts",
-    "*.js"
+    "*.js",
+    "dist/**/*.js",
+    "dist/**/*.mjs",
+    "dist/**/*.cjs",
+    "dist/**/*.map",
+    "dist/**/*.json",
+    "dist/**/*.d.ts"
   ],
   "scripts": {
     "clean": "rm -rf lib && rm -f *.tsbuildinfo",
     "build": "tsc -p tsconfig.build.json",
+    "build:dist": "vite build",
     "build:watch": "yarn run build --watch",
-    "build:release": "yarn clean && yarn run build",
+    "build:release": "yarn clean && yarn run build && yarn run build:dist",
     "check-build": "node -e \"(async function() { await import('./lib/index.js') })()\"",
     "check-types": "tsc",
     "lint": "eslint --color --ext .ts src/ test/",
     "lint:fix": "yarn run lint --fix",
     "test": "yarn test:unit",
     "test:unit": "vitest --run --dir test/unit/",
     "test:browsers": "yarn test:browsers:chrome && yarn test:browsers:firefox && yarn test:browsers:electron",
-    "test:browsers:chrome": "vitest --run --browser chrome --config ./vitest.browser.config.ts --dir test/unit",
-    "test:browsers:firefox": "vitest --run --browser firefox --config ./vitest.browser.config.ts --dir test/unit",
+    "test:browsers:chrome": "yarn run build:dist && vitest --run --browser chrome --config ./vitest.browser.config.ts --dir test/unit",
+    "test:browsers:firefox": "yarn run build:dist && vitest --run --browser firefox --config ./vitest.browser.config.ts --dir test/unit",
     "test:browsers:electron": "echo 'Electron tests will be introduced back in the future as soon vitest supports electron.'",
     "check-readme": "typescript-docs-verifier"
   },

packages/light-client/src/index.ts

@@ -7,7 +7,7 @@ import {isErrorAborted, sleep} from "@lodestar/utils";
 import {getCurrentSlot, slotWithFutureTolerance, timeUntilNextEpoch} from "./utils/clock.js";
 import {chunkifyInclusiveRange} from "./utils/chunkify.js";
 import {LightclientEmitter, LightclientEvent} from "./events.js";
-import {getLcLoggerConsole, ILcLogger} from "./utils/logger.js";
+import {getConsoleLogger, ILcLogger} from "./utils/logger.js";
 import {computeSyncPeriodAtEpoch, computeSyncPeriodAtSlot, computeEpochAtSlot} from "./utils/clock.js";
 import {LightclientSpec} from "./spec/index.js";
 import {validateLightClientBootstrap} from "./spec/validateLightClientBootstrap.js";
@@ -114,7 +114,7 @@ export class Lightclient {
         : genesisData.genesisValidatorsRoot;
 
     this.config = createBeaconConfig(config, this.genesisValidatorsRoot);
-    this.logger = logger ?? getLcLoggerConsole();
+    this.logger = logger ?? getConsoleLogger();
     this.transport = transport;
     this.runStatus = {code: RunStatusCode.uninitialized};
 
@@ -318,3 +318,8 @@ export class Lightclient {
     this.emitter.emit(LightclientEvent.statusChange, this.runStatus.code);
   }
 }
+
+// To export these name spaces to the bundle JS
+export * as utils from "./utils.js";
+export * as validation from "./validation.js";
+export * as transport from "./transport.js";

packages/light-client/src/transport.ts

@@ -0,0 +1,2 @@
+// This file exists to have proper namespace for the web bundle
+export * from "./transport/index.js";

packages/light-client/src/utils.ts

@@ -0,0 +1,2 @@
+// This file exists to have proper namespace for the web bundle
+export * from "./utils/index.js";

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

@@ -0,0 +1,19 @@
+import {getClient, Api} from "@lodestar/api";
+import {ChainForkConfig, createChainForkConfig} from "@lodestar/config";
+import {NetworkName, networksChainConfig} from "@lodestar/config/networks";
+
+export function getApiFromUrl(url: string, network: NetworkName): Api {
+  if (!(network in networksChainConfig)) {
+    throw Error(`Invalid network name "${network}". Valid options are: ${Object.keys(networksChainConfig).join()}`);
+  }
+
+  return getClient({urls: [url]}, {config: createChainForkConfig(networksChainConfig[network])});
+}
+
+export function getChainForkConfigFromNetwork(network: NetworkName): ChainForkConfig {
+  if (!(network in networksChainConfig)) {
+    throw Error(`Invalid network name "${network}". Valid options are: ${Object.keys(networksChainConfig).join()}`);
+  }
+
+  return createChainForkConfig(networksChainConfig[network]);
+}

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

@@ -1,3 +1,4 @@
+export * from "./api.js";
 export * from "./chunkify.js";
 export * from "./clock.js";
 export * from "./domain.js";

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

@@ -13,11 +13,16 @@ export type ILcLogger = {
 /**
  * With `console` module and ignoring debug logs
  */
-export function getLcLoggerConsole(opts?: {logDebug?: boolean}): ILcLogger {
+export function getConsoleLogger(opts?: {logDebug?: boolean}): ILcLogger {
   return {
     error: console.error,
     warn: console.warn,
     info: console.log,
     debug: opts?.logDebug ? console.log : () => {},
   };
 }
+
+/**
+ * @deprecated - Use `getConsoleLogger` instead.
+ */
+export const getLcLoggerConsole = getConsoleLogger;

packages/light-client/test/unit/webEsmBundle.browser.test.ts

@@ -0,0 +1,63 @@
+/* eslint-disable @typescript-eslint/no-unsafe-assignment,@typescript-eslint/no-unsafe-member-access,@typescript-eslint/no-unsafe-call */
+import {expect, describe, it, beforeEach, vi} from "vitest";
+import "../../dist/lightclient.min.mjs";
+
+describe("web bundle for lightclient", () => {
+  vi.setConfig({testTimeout: 20_000});
+
+  let lightclient: any;
+
+  beforeEach(() => {
+    lightclient = (window as any)["lodestar"]["lightclient"];
+  });
+
+  it("should have a global interface", () => {
+    expect(lightclient).toBeDefined();
+  });
+
+  it("should have all relevant exports", () => {
+    expect(lightclient).toHaveProperty("Lightclient");
+    expect(lightclient).toHaveProperty("LightclientEvent");
+    expect(lightclient).toHaveProperty("RunStatusCode");
+    expect(lightclient).toHaveProperty("upgradeLightClientFinalityUpdate");
+    expect(lightclient).toHaveProperty("upgradeLightClientOptimisticUpdate");
+    expect(lightclient).toHaveProperty("utils");
+    expect(lightclient).toHaveProperty("transport");
+    expect(lightclient).toHaveProperty("validation");
+
+    expect(lightclient.Lightclient).toBeTypeOf("function");
+  });
+
+  it("should start the lightclient and sync", async () => {
+    const {Lightclient, LightclientEvent, transport, utils} = lightclient;
+
+    const logger = utils.getConsoleLogger({logDebug: true});
+    const config = utils.getChainForkConfigFromNetwork("mainnet");
+
+    // TODO: Decide to check which node to use in testing
+    // We have one node in CI, but that only starts with e2e tests
+    const api = utils.getApiFromUrl("https://lodestar-mainnet.chainsafe.io", "mainnet");
+
+    const lc = await Lightclient.initializeFromCheckpointRoot({
+      config,
+      logger,
+      transport: new transport.LightClientRestTransport(api),
+      genesisData: await utils.getGenesisData(api),
+      checkpointRoot: await utils.getFinalizedSyncCheckpoint(api),
+      opts: {
+        allowForcedUpdates: true,
+        updateHeadersOnForcedUpdate: true,
+      },
+    });
+
+    await expect(lc.start()).resolves.toBeUndefined();
+
+    await expect(
+      new Promise((resolve) => {
+        lc.emitter.on(LightclientEvent.lightClientOptimisticHeader, async (optimisticUpdate: unknown) => {
+          resolve(optimisticUpdate);
+        });
+      })
+    ).resolves.toBeDefined();
+  });
+});

packages/light-client/test/utils/utils.ts

@@ -14,7 +14,7 @@ import {
 import {altair, phase0, Slot, ssz, SyncPeriod, allForks} from "@lodestar/types";
 import {SyncCommitteeFast} from "../../src/types.js";
 import {computeSigningRoot} from "../../src/utils/domain.js";
-import {getLcLoggerConsole} from "../../src/utils/logger.js";
+import {getConsoleLogger} from "../../src/utils/logger.js";
 
 const CURRENT_SYNC_COMMITTEE_INDEX = 22;
 const CURRENT_SYNC_COMMITTEE_DEPTH = 5;
@@ -25,7 +25,7 @@ const CURRENT_SYNC_COMMITTEE_DEPTH = 5;
  * DEBUG=true vitest ...
  * ```
  */
-export const testLogger = getLcLoggerConsole({logDebug: Boolean(process.env.DEBUG)});
+export const testLogger = getConsoleLogger({logDebug: Boolean(process.env.DEBUG)});
 
 export const genesisValidatorsRoot = Buffer.alloc(32, 0xaa);
 export const SOME_HASH = Buffer.alloc(32, 0xaa);

packages/light-client/tsconfig.json

@@ -1,4 +1,5 @@
 {
   "extends": "../../tsconfig.json",
+  "exclude": ["src/index.browser.ts"],
   "compilerOptions": {}
 }