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.
chainsafe-bls/README.md

125 lines
3.9 KiB
Markdown
Raw Normal View History

2020-04-17 20:23:30 +00:00
# bls
2019-08-05 15:48:26 +00:00
2019-08-05 18:11:56 +00:00
[![codecov](https://codecov.io/gh/ChainSafe/lodestar/branch/master/graph/badge.svg)](https://codecov.io/gh/ChainSafe/lodestar)
2020-11-30 20:19:10 +00:00
![ETH2.0_Spec_Version 1.0.0](https://img.shields.io/badge/ETH2.0_Spec_Version-1.0.0-2e86c1.svg)
2020-07-03 23:05:24 +00:00
![ES Version](https://img.shields.io/badge/ES-2017-yellow)
![Node Version](https://img.shields.io/badge/node-12.x-green)
2019-08-05 15:48:26 +00:00
2020-11-30 20:19:10 +00:00
Javascript library for BLS (Boneh-Lynn-Shacham) signatures and signature aggregation, tailored for use in Eth2.
2020-11-25 15:03:11 +00:00
## Usage
2020-11-25 16:17:48 +00:00
```bash
yarn add @chainsafe/bls
```
2020-11-29 12:21:31 +00:00
To use native bindings you must install peer dependency `@chainsafe/blst`
```bash
yarn add @chainsafe/bls @chainsafe/blst
```
2020-11-25 16:17:48 +00:00
You must initialize the library once in your application before using it. The result is cached and use across all your imports
2020-11-25 15:03:11 +00:00
```ts
2020-11-30 20:19:10 +00:00
import {init, SecretKey, secretKeyToPublicKey, sign, verify} from "@chainsafe/bls";
2020-11-25 15:03:11 +00:00
2020-11-25 16:09:44 +00:00
(async () => {
await init("herumi");
2020-11-25 15:03:11 +00:00
2020-11-30 20:19:10 +00:00
// class-based interface
const secretKey = SecretKey.fromKeygen();
2020-11-25 16:09:44 +00:00
const publicKey = secretKey.toPublicKey();
const message = new Uint8Array(32);
const signature = secretKey.sign(message);
console.log("Is valid: ", signature.verify(publicKey, message));
2020-11-30 20:19:10 +00:00
// functional interface
const sk = secretKey.toBytes();
const pk = secretKeyToPublicKey(sk);
const sig = sign(sk, message);
console.log("Is valid: ", verify(pk, message, sig));
2020-11-25 16:09:44 +00:00
})();
2020-11-25 15:03:11 +00:00
```
### Browser
2020-11-25 16:17:48 +00:00
If you are in the browser, import from `/browser` to import directly the WASM version
2020-11-25 15:03:11 +00:00
```ts
import bls from "@chainsafe/bls/browser";
```
### Native bindings only
2020-11-25 16:17:48 +00:00
If you are in NodeJS, import from `/node` to skip browser specific code. Also install peer dependency `@chainsafe/blst` which has the native bindings
```bash
yarn add @chainsafe/bls @chainsafe/blst
```
2020-11-25 15:03:11 +00:00
```ts
import bls from "@chainsafe/bls/node";
```
### Native bindings + WASM fallback
2020-11-25 16:17:48 +00:00
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
```bash
yarn add @chainsafe/bls @chainsafe/blst
```
2020-11-25 15:03:11 +00:00
```ts
2020-11-30 20:19:10 +00:00
import {init} from "@chainsafe/bls";
2020-11-25 15:03:11 +00:00
try {
2020-11-30 20:19:10 +00:00
await init("blst-native");
2020-11-25 15:03:11 +00:00
} catch (e) {
2020-11-30 20:19:10 +00:00
await init("herumi");
2020-11-25 15:03:11 +00:00
console.warn("Using WASM");
}
```
The API is identical for all implementations.
2020-12-01 09:01:45 +00:00
## Benchmarks
- `blst`: [src/blst](src/blst) (node.js-only, bindings to C via node-gyp)
2020-12-07 22:22:37 +00:00
- `herumi`: [src/herumi](src/herumi) (node.js & browser, wasm)
- `noble`: [noble-bls12-381](https://github.com/paulmillr/noble-bls12-381) (node.js & browser, pure JS)
2020-12-01 09:01:45 +00:00
2020-12-02 21:10:34 +00:00
Results are in `ops/sec (x times slower)`, where `x times slower` = times slower than fastest implementation (`blst`).
2020-12-02 20:45:29 +00:00
2020-12-07 22:22:37 +00:00
| 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) |
2020-12-02 20:45:29 +00:00
2020-12-07 22:22:37 +00:00
\* `blst` and `herumi` performed 100 runs each, `noble` 10 runs.
2020-12-01 09:01:45 +00:00
2020-12-07 22:22:37 +00:00
Results from CI run https://github.com/ChainSafe/bls/runs/1513710175?check_suite_focus=true#step:12:13
2020-12-01 09:32:15 +00:00
2020-11-25 15:03:11 +00:00
## Spec versioning
2019-08-05 15:48:26 +00:00
2020-11-30 20:19:10 +00:00
| Version | Bls spec hash-to-curve version |
2020-12-01 09:01:45 +00:00
| ------- | :----------------------------: |
| 5.x.x | draft #9 |
| 2.x.x | draft #7 |
| 1.x.x | draft #6 |
| 0.3.x | initial version |
2020-05-21 17:10:46 +00:00
2020-11-30 20:19:10 +00:00
> [spec](https://github.com/ethereum/eth2.0-specs/blob/v1.0.0/specs/phase0/beacon-chain.md#bls-signatures)
2019-08-05 15:48:26 +00:00
2020-11-04 17:40:36 +00:00
> [test vectors](https://github.com/ethereum/eth2.0-spec-tests/tree/master/tests/bls)
2020-02-25 08:28:47 +00:00
2020-04-17 20:15:17 +00:00
## License
Apache-2.0