chainsafe-bls/README.md

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
• herumi: src/herumi
• noble: noble-bls12-381

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