Export strategies

README.md

@@ -6,22 +6,66 @@
 ![ES Version](https://img.shields.io/badge/ES-2017-yellow)
 ![Node Version](https://img.shields.io/badge/node-12.x-green)
 
-This is a Javascript library that implements BLS (Boneh-Lynn-Shacham) signatures and supports signature aggregation.
+Javascript library for BLS (Boneh-Lynn-Shacham) signatures and signature aggregation.
+
+## Usage
+
+```ts
+import {PrivateKey} from "@chainsafe/bls";
+
+const secretKey = PrivateKey.fromKeygen();
+const publicKey = secretKey.toPublicKey();
+const message = new Uint8Array(32);
+
+const signature = secretKey.sign(message);
+console.log("Is valid: ", signature.verify(publicKey, message));
+```
+
+### Browser
+
+If you are in the browser, import from `/browser`
+
+```ts
+import bls from "@chainsafe/bls/browser";
+```
+
+### Native bindings only
+
+If you are in NodeJS, import from `/node` to skip browser specific code
+
+```ts
+import bls from "@chainsafe/bls/node";
+```
+
+### Native bindings + WASM fallback
+
+If you want to offer a fallback in NodeJS, first try to load native bindings and then fallback to WASM
+
+```ts
+import bls from "@chainsafe/bls";
+
+try {
+  await bls.init("blst-native");
+} catch (e) {
+  await bls.init("herumi");
+  console.warn("Using WASM");
+}
+```
+
+The API is identical for all implementations.
+
+## Spec versioning
 
 | Version | Bls spec version |
 | ------- | :--------------: |
-| 0.3.x   | initial version  |
-| 1.x.x   |     draft #6     |
 | 2.x.x   |     draft #7     |
+| 1.x.x   |     draft #6     |
+| 0.3.x   | initial version  |
 
 > [spec](https://github.com/ethereum/eth2.0-specs/blob/v0.11.1/specs/phase0/beacon-chain.md#bls-signatures)
 
 > [test vectors](https://github.com/ethereum/eth2.0-spec-tests/tree/master/tests/bls)
 
-## Usage
-
-- `yarn add @chainsafe/bls`
-
 ## License
 
 Apache-2.0

blst-native.d.ts

@@ -0,0 +1 @@
+export * from "./lib/blst";

blst-native.js

@@ -0,0 +1 @@
+module.exports = require("./lib/blst");

browser.d.ts

@@ -0,0 +1 @@
+export * from "./lib/herumi";

browser.js

@@ -0,0 +1 @@
+export * from "./lib/herumi";

herumi.d.ts

@@ -0,0 +1 @@
+export * from "./lib/herumi";

herumi.js

@@ -0,0 +1 @@
+module.exports = require("./lib/herumi");

node.d.ts

@@ -0,0 +1 @@
+export * from "./lib/blst";

node.js

@@ -0,0 +1 @@
+module.exports = require("./lib/blst");

package.json

@@ -4,6 +4,8 @@
   "description": "Implementation of bls signature verification for ethereum 2.0",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
+  "module": "./browser",
+  "browser": "./browser",
   "homepage": "https://github.com/chainsafe/bls",
   "author": "ChainSafe Systems",
   "license": "Apache-2.0",

src/index.ts

@@ -1,3 +1,34 @@
-import blst from "./blst";
+import {IBls} from "./interface";
-export default blst;
+import blsHerumi from "./herumi";
-export * from "./blst";
+
+export type Implementation = "herumi" | "blst-native";
+
+// This proxy makes sure a nice error is printed if BLS is used before init()
+export let bls: IBls = new Proxy({} as IBls, {
+  get: function () {
+    throw Error("BLS not initialized, call init() before");
+  },
+});
+
+async function getImplementation(impl: Implementation) {
+  switch (impl) {
+    case "herumi":
+      await blsHerumi.initBLS();
+      return blsHerumi;
+
+    case "blst-native":
+      if (typeof require !== "function") {
+        throw Error("blst-native is only supported in NodeJS");
+      }
+      return require("./blst");
+
+    default:
+      throw new Error(`Unsupported implementation - ${impl}`);
+  }
+}
+
+export async function init(impl: Implementation) {
+  bls = await getImplementation(impl);
+}
+
+export default bls;