@chainsafe/bls

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

By default, native bindings will be used if in NodeJS and they are installed. A WASM implementation ("herumi") is used as a fallback in case any error occurs.

The blst-native implementation offers a multi-threaded approach to verification and utilizes the libuv worker pool to verification. It is a more performant options synchronously and FAR better when utilized asynchronously. All verification functions provide sync and async versions. Both the blst-native and herumi implementations offer verification functions with async prefixes as free functions and also on their respective classes. This was done to preserve the isomorphic architecture of this library. In reality however, only the blst-native bindings have the ability to implement a promise based approach. In the herumi version the async version just proxies to the sync version under the hood.

import bls from "@chainsafe/bls";

(async () => {
    // class-based interface
    const secretKey = bls.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 = bls.secretKeyToPublicKey(sk);
    const sig = bls.sign(sk, message);
    console.log("Is valid: ", bls.verify(pk, message, sig));
})();

Browser

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

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

Native bindings only

If you are in NodeJS, import from /blst-native to explicitly import the native bindings. Also install peer dependency @chainsafe/blst which has the native bindings

yarn add @chainsafe/bls @chainsafe/blst

import bls from "@chainsafe/bls/blst-native";

Get implementation at runtime

If you need to get a bls implementation at runtime, import from /getImplementation.

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

const bls = await getImplementation("herumi");

Switchable singleton

If you need a singleton that is switchable at runtime (the default behavior in <=v6), import from /switchable.

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

// here `bls` is uninitialized
await init("herumi");
// here `bls` is initialized
// now other modules can `import bls from "@chainsafe/bls/switchable"` and it will be initialized

The API is identical for all implementations.

Benchmarks

• blst: src/blst-native (node.js-only, bindings to C via node-gyp)
• herumi: src/herumi (node.js & browser, 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	326.38	47.674 (x7)	17.906 (x18)
verifyAggregate (30)	453.29	51.151 (x9)	18.372 (x25)
verifyMultiple (30)	34.497	3.5233 (x10)	2.0286 (x17)
verifyMultipleSignatures (30)	26.381	3.1633 (x8)	-
aggregate (pubkeys, 30)	15686	2898.9 (x5)	1875.0 (x8)
aggregate (sigs, 30)	6373.4	1033.0 (x6)	526.25 (x12)
sign	925.49	108.81 (x9)	10.246 (x90)

* blst and herumi performed 100 runs each, noble 10 runs.

Results from CI run https://github.com/ChainSafe/bls/runs/1513710175?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