This repository has been archived on 2023-04-09. You can view files and clone it, but cannot push or open issues or pull requests.

4.0 KiB

Raw Blame History

bls

Javascript library for BLS (Boneh-Lynn-Shacham) signatures and signature aggregation, tailored for use in Eth2.

Usage

yarn add @chainsafe/bls

To use native bindings you must install peer dependency @chainsafe/blst

yarn add @chainsafe/bls @chainsafe/blst

You must initialize the library once in your application before using it. The result is cached and use across all your imports

import {init, SecretKey, secretKeyToPublicKey, sign, verify} from "@chainsafe/bls";

(async () => {
  await init("herumi");

  // class-based interface
  const secretKey = SecretKey.fromKeygen();
  const publicKey = secretKey.toPublicKey();
  const message = new Uint8Array(32);

  const signature = secretKey.sign(message);
  console.log("Is valid: ", signature.verify(publicKey, message));

  // functional interface
  const sk = secretKey.toBytes();
  const pk = secretKeyToPublicKey(sk);
  const sig = sign(sk, message);
  console.log("Is valid: ", verify(pk, message, sig));
})();

Browser

If you are in the browser, import from /browser to import directly the WASM version

import bls from "@chainsafe/bls/browser";

Native bindings only

If you are in NodeJS, import from /node to skip browser specific code. Also install peer dependency @chainsafe/blst which has the native bindings

yarn add @chainsafe/bls @chainsafe/blst

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. Also install peer dependency @chainsafe/blst which has the native bindings

yarn add @chainsafe/bls @chainsafe/blst

import {init} from "@chainsafe/bls";

try {
  await init("blst-native");
} catch (e) {
  await init("herumi");
  console.warn("Using WASM");
}

The API is identical for all implementations.

Benchmarks

blst: src/blst (node.js-only, bindings to C via node-gyp)
herumi: src/herumi (node.js & browser, bindings to C++ via wasm)
noble: noble-bls12-381 (node.js & browser, pure JS)

Results are in ops/sec (x times slower), where x times slower = times slower than fastest implementation (blst).

Function - `ops/sec`	`blst`	`herumi`	`noble`*
`verify`	443.75	46.658 (x9)	12.355 (x36)
`verifyAggregate` (30)	438.68	46.615 (x9)	9.8803 (x44)
`verifyMultiple` (30)	35.138	3.4332 (x10)	0.9217 (x38)
`aggregate` (pubkeys, 30)	15761	2603.5 (x6)	42.956 (x366)
`aggregate` (sigs, 30)	6587.8	1018.7 (x6)	-

*noble methods include serialization and deserialization to bytes, which may impact all benchmarks specially aggregate. ** blst and herumi performed 100 runs each, noble 10 runs.

Results from CI run https://github.com/ChainSafe/bls/runs/1488856560?check_suite_focus=true#step:12:13

Spec versioning

Version	Bls spec hash-to-curve version
5.x.x	draft #9
2.x.x	draft #7
1.x.x	draft #6
0.3.x	initial version

spec

test vectors

License

Apache-2.0

4.0 KiB Raw Blame History

bls