drand / drand-client

🎲 A JavaScript client to the drand randomness beacon network.

Drand - A Distributed Randomness Beacon Daemon

Drand (pronounced "dee-rand") is a distributed randomness beacon daemon written in Golang.

Linked drand nodes collectively produce publicly verifiable, unbiased and unpredictable random values at fixed intervals using bilinear pairings and threshold cryptography.

Drand was first developed within the DEDIS organization, and as of December 2019, is now under the drand organization.

Table of Contents

• Goal and Overview
  • Public Randomness
• Installation
  • Official release
  • Manual installation
  • Via Golang
  • Via Docker
• Usage
  • Run Drand locally
  • Create a Drand deployment
  • Fetching Public Randomness
  • Using HTTP endpoints
  • JavaScript client
• Documentation
• What's Next?
• Development
• Acknowledgments
• Coverage
• Tracing
• License

Goal and Overview

The need for digital randomness is paramount in multiple digital applications ([e]voting, lottery, cryptographic parameters, embedded devices bootstrapping randomness, blockchain systems etc) as well in non-digital such as statistical sampling (used for example to check results of an election), assigning court cases to random judges, random financial audits, etc. However, constructing a secure source of randomness is anything but easy: there are countless examples of attacks where the randomness generation was the culprit (static keys, non-uniform distribution, biased output, etc). drand aims to fix that gap by providing a Randomness-as-a-Service network (similar to NTP servers for time, or Certificate Authority servers for CAs verification), providing continuous source of randomness which is:

• Decentralized: drand is a software ran by a diverse set of reputable entities on the Internet and a threshold of them is needed to generate randomness, there is no central point of failure.
• Publicly verifiable & unbiased: drand periodically delivers publicly verifiable and unbiased randomness. Any third party can fetch and verify the authenticity of the randomness and by that making sure it hasn't been tampered with.

A drand network is operated by a group of organizations around the world that includes Cloudflare, EPFL, Kudelski Security, Protocol Labs, Celo, UCL, and UIUC. You can learn more by visiting the League of Entropy website, where you can also see the random values being generated by the network in real time.

Public Randomness

Generating public randomness is the primary functionality of drand. Public randomness is generated collectively by drand nodes and publicly available. The main challenge in generating good randomness is that no party involved in the randomness generation process should be able to predict or bias the final output. Additionally, the final result has to be third-party verifiable to make it actually useful for applications like lotteries, sharding, or parameter generation in security protocols.

A drand randomness beacon is composed of a distributed set of nodes and has two phases:

• Setup: Each node first generates a long-term public/private key pair. Then all of the public keys are written to a group file together with some further metadata required to operate the beacon. After this group file has been distributed, the nodes perform a distributed key generation (DKG) protocol to create the collective public key and one private key share per server. The participants NEVER see/use the actual (distributed) private key explicitly but instead utilize their respective private key shares for the generation of public randomness.
• Generation: After the setup, the nodes switch to the randomness generation mode. Any of the nodes can initiate a randomness generation round by broadcasting a message which all the other participants sign using a t-of-n threshold version of the Boneh-Lynn-Shacham (BLS) signature scheme and their respective private key shares. Once any node (or third-party observer) has gathered t partial signatures, it can reconstruct the full BLS signature (using Lagrange interpolation). The signature is then hashed using SHA-256 to ensure that there is no bias in the byte representation of the final output. This hash corresponds to the collective random value and can be verified against the collective public key.

Installation

Official release

Please go use the latest drand binary in the release page.

Manual installation

Drand can be installed via Golang or Docker. By default, drand saves the configuration files such as the long-term key pair, the group file, and the collective public key in the directory $HOME/.drand/.

The docker image can also be built manually by running docker build --build-arg version=$(git describe --tags) --build-arg gitCommit=$(git rev-parse HEAD) -t drandorg/go-drand:latest . in the project root folder Additional instructions for running a node or network using docker can be found in the docker directory

Via Golang

Make sure that you have a working Golang installation and that your GOPATH is set.

Then install drand via:

git clone https://github.com/drand/drand
cd drand
make install

Via Docker

The setup is explained in docker/README.md.

Usage

Run Drand locally

To run a local demo, you can simply run:

make demo

The script spins up a few drand local processes, performs resharing and other operations and will continue to print out new randomness every Xs (currently 6s). For more information, look at the demo README.

A drand beacon provides several public services to clients. A drand node exposes its public services on a gRPC endpoint as well as a REST JSON endpoint, on the same port. The latter is especially useful if one wishes to retrieve randomness from a JavaScript application. Communication is meant to be protected through TLS by using a reverse-proxy to perform TLS termination.

Create a Drand deployment

Consult full instructions at DEPLOYMENT

Fetching Public Randomness

To get the latest public random value, run

drand get public --round <i> <group.toml>

where <group.toml> is the group identity file of a drand node. You can specify the round number when the public randomness has been generated. If not specified, this command returns the most recent random beacon.

The JSON-formatted output produced by drand is of the following form:

{
  "round": 367,
  "signature": "b62dd642e939191af1f9e15bef0f0b0e9562a5f570a12a231864afe468377e2a6424a92ccfc34ef1471cbd58c37c6b020cf75ce9446d2aa1252a090250b2b1441f8a2a0d22208dcc09332eaa0143c4a508be13de63978dbed273e3b9813130d5",
  "previous_signature": "afc545efb57f591dbdf833c339b3369f569566a93e49578db46b6586299422483b7a2d595814046e2847494b401650a0050981e716e531b6f4b620909c2bf1476fd82cf788a110becbc77e55746a7cccd47fb171e8ae2eea2a22fcc6a512486d",
  "randomness": "d7aed3686bf2be657e6d38c20999831308ee6244b68c8825676db580e7e3bec6"
}

Here Signature is the threshold BLS signature on the previous signature value Previous and the current round number. Randomness is the hash of Signature, to be used as the random value for this round. The field Round specifies the index of Randomness in the sequence of all random values produced by this drand instance. The message signed is therefore the concatenation of the round number treated as a uint64 and the previous signature. At the moment, we are only using BLS signatures on the bls12-381 curves and the signature is made over G1.

(Note that this command expects access to a drand group member, this won't work with the current League of Entropy nodes, since they are not exposing their GRPC endpoints directly.)

Using HTTP endpoints

This is the recommended way of using drand randomness, but don't forget to validate the beacons' signatures against the group public key.

One may want to get the distributed key or public randomness by issuing a GET to a HTTP endpoint instead of using a gRPC client. Here is a basic example on how to do so with curl.

To get the distributed key, you can use:

curl <address>/group

Similarly, to get the latest round of randomness from the drand beacon, you can use

curl <address>/public/latest

JavaScript client

To facilitate the use of drand's randomness in JavaScript-based applications, we provide drand-client.

For more details on the procedure and instructions on how to use it, refer to the readme.

Documentation

Here is a list of all documentation related to drand:

• To learn more about the protocol, the motivation and its background
  • For a high level presentation of motivations and background, here are some public slides about drand or online video.
  • A basic explainer of the cryptography behind drand,
  • Protocol Specification
• API documentation
  • The client-side API documentation of drand
• DevOps/Deployment documentation
  • Deployment instructions
  • Security Model

As well, here is a list of background readings w.r.t to the cryptography used in drand:

• Pairing-based cryptography and Barreto-Naehrig curves.
• Pedersen's distributed key generation protocol for the setup.
• Threshold BLS signatures for the generation of public randomness.
• The resharing scheme used comes from the paper from Y. Desmedt and S. Jajodia.

Note that drand was originally a DEDIS-owned project that is now spinning off on its own Github organization. For related previous work on public randomness, see DEDIS's academic paper Scalable Bias-Resistant Distributed Randomness.

What's Next?

Although being already functional, drand is still at an early development stage and there is a lot left to be done. The list of opened issues is a good place to start. On top of this, drand would benefit from higher-level enhancements such as the following:

• Implement a more failure-resilient DKG protocol or an approach based on verifiable succinct computations (zk-SNARKs, etc).
• Use / implement a faster pairing based library in JavaScript
• Add more unit tests
• Add a systemd unit file

Feel free to submit feature requests or, even better, pull requests ;)

Development

If you want to contribute to Drand, head over to our Development documentation.

Acknowledgments

Thanks to @herumi for providing support on his optimized pairing-based cryptographic library used in the first version.

Thanks to Apostol Vassilev for its interest in drand and the extensive and helpful discussions on the drand design.

Thanks to @Bren2010 and @grittygrease for providing the native Golang bn256 implementation and for their help in the design of drand and future ideas.

Finally, a special note for Bryan Ford from the DEDIS lab for letting me work on this project and helping me grow it.

Coverage

• EPFL blog post
• Cloudflare crypto week introduction post and the more technical post.
• Kudelski Security blog post
• OneZero post on the league of entropy
• SlashDot post
• Duo post
• Liftr
• (French) nextimpact

Tracing

In the ./docker folder, you can use the docker-compose.tracing.yaml to spin up the necessary components for monitoring a drand binary in-depth. To run tracing, you will need to pass the --traces command line flag with the endpoint of the tool running in the docker-compose file (or another OpenTelemetry endpoint). You can optionally pass the --traces-probability flag to configure how many calls you wish to sample for telemetry.

License

The drand project is dual-licensed under Apache 2.0 and MIT terms:

• Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

drand-client's Issues

CORS issues with the `User-Agent`

The newly added user-agent to the drand-client can cause some issues with CORS in browsers, as fetch does not pass the "mode": "cors" option

see: https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch#supplying_request_options

Support Webpack 4 (e.g. for Create React App)

When trying to use this lib from npm in a React project, I get the error

Failed to compile.

./node_modules/drand-client/verifying.js 16:29
Module parse failed: Unexpected token (16:29)
File was processed with these loaders:
 * ./node_modules/react-scripts/node_modules/babel-loader/lib/index.js
You may need an additional loader to handle the result of these loaders.
|         // TODO: switch to TinyGo when math/big works for smaller wasm file and non-global exports.
|         const go = new Go();
>         const url = `${import.meta.url.split('/').slice(0, -1).join('/')}/wasm/drand.wasm`;
|         let result;
|

This is because import.meta.url is not supported in Webpack 4. Webpack 5 support probably will take some more time.

I have no great idea how to solve this, but let's see.

Fetch chains

In order to support multiple chains, the client should be able to fetch the list of chains using, e.g. http://pl-us.testnet.drand.sh/chains which is currently supported in the go client. This allows a user to make followup requests to chainInfo and programmatically select chains that fulfill their required criteria (e.g. chained vs unchained)

Update tests to work with newest node LTS

All the jest-http-mock tests fail on the latest LTS version of node, as they appear to use actual fetch rather than the mock (presumably because fetch is now available on LTS)

Provide isomorphic fetch for older node envs

The fetch API was introduced into node via an experimental flag in node 17, and without a flag in node 18. Currently it isn't polyfilled in this library for node < 17 - we use node-fetch in the tests, but isomorphic-fetch should be added to provide a better experience for users in older versions of node.

Rust client for Drand

I am working on a drand-client in rust. I am using the go implementation drand/client for reference and so far it checks fine. For verification I am using drand-verify. Before I put some serious effort in drand-rs I want to make sure that the rust-client aligns with Drand requirements and specification. We can have this as the tracking issue for that.

code: https://github.com/prataprc/drand-rs

comment says public_key from`/info` is Ed25519 instead of BLS12-381

This line says the public_key from /info is Ed25519, while the drand cryptographic specification and the library dependency says it's the BLS12-381 G1 point. Please let me know if this comment needs updating or if I'm just losing my mind. Thanks!

Update testnet node URLs

Two of the tree testnet endpoints used for testing this lib (https://github.com/drand/drand-client/blob/42b9dfe/drand.test.js#L10-L14 and https://github.com/drand/drand-client/blob/42b9dfe/optimizing.test.js#L12-L16) are currently unavailable for me:

• http://pl-eu.testnet.drand.sh 🔴
• http://pl-us.testnet.drand.sh 🟢
• http://pl-sin.testnet.drand.sh 🔴

Are they expected to become available again? Are there alternative nodes that can be used for testing with multiple clients?

Push missing git tag for version 1.1.0

There is a 1.1.0 on npm but the v1.1.0 tag seems to be missing here.

`deno` sample code error

Tried to run with the deno sample code and cli invocation which fails, copied from the README. deno was installed on macOS with brew install deno.

import Client, { HTTP } from 'https://cdn.jsdelivr.net/npm/drand-client/drand.js'

const chainHash = '8990e7a9aaed2ffed73dbd7092123d6f289930540d7651336225dc172e51b2ce' // (hex encoded)
const urls = [
  'https://api.drand.sh',
  'https://drand.cloudflare.com'
]

async function main() {
  const options = { chainHash }

  const client = await Client.wrap(HTTP.forURLs(urls, chainHash), options)

  // e.g. use the client to get the latest randomness round:
  const res = await client.get()

  console.log(res.round, res.randomness)
}

main()

Failing run:

$ deno -V
deno 1.3.2

$ deno run --allow-net index.js
error: Uncaught TypeError: WebAssembly.compile(): Argument 0 must be a buffer source

package.json

{
  "name": "foo",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "author": "",
  "license": "ISC",
  "dependencies": {
    "abort-controller": "^3.0.0",
    "drand-client": "^0.2.0",
    "node-fetch": "^2.6.0"
  }
}

watch returns the same round multiple times

I have the following deno script:

import { HttpCachingChain, HttpChainClient, watch } from "npm:[email protected]";

const chainHash = "8990e7a9aaed2ffed73dbd7092123d6f289930540d7651336225dc172e51b2ce";
const publicKey =
  "868f005eb8e6e4ca0a47c8a77ceaa5309a47978a7c71bc5cce96366b5d7a569937c529eeda66c7293784a9402801af31"; // (hex encoded)

const options = {
  disableBeaconVerification: false,
  noCache: false,
  chainVerificationParams: { chainHash, publicKey },
};

if (import.meta.main) {
  const chain = new HttpCachingChain("https://api.drand.sh", options);
  const client = new HttpChainClient(chain, options);

  const abortController = new AbortController();
  for await (const beacon of watch(client, abortController)) {
    console.log(new Date().toUTCString(), "Watch returned a beacon:", beacon);
  }
}

and run it with deno run --allow-read --allow-net main.ts > log.txt. As you can see in the logs, the same round is returned multiple times. E.g. round: 2618607 is there 302 times.

log.txt

deno support for v1.0.0

Deno was supported in v0.* via storing all the JS on a CDN. This is not currently the case for v1 and should be implemented for parity.

Remove backwards compat default DST for v2

In order to not break v1 users of the client, we pass the DST for beacon verification as an optional parameter and set some defaults.
This can be removed in v2 to ensure users don't accidentally try and verify a beacon with the wrong DST

Add support for verifying beacons with the G1-G2 swap

Once drand/drand#1103 lands, and we've launched a new testnet network with the swapped curves for the BLS signature, we should make sure to add support for verifying these beacons.

The Noble library currently doesn't support it, but it should have all the required methods to implement it easily now that hash to curve is supported on both groups:
paulmillr/noble-bls12-381#43

Missing "main": "lib/drand.ts",

in package.json we have "main": "lib/drand.ts", which does not exist.

Also shouldn't this point to a compiled .js file? It seems like the npm package does not contain .js builds at all.

Consider using Rust implementation for Wasm build

drand-verify is a Rust implementation of drand beacon verification based on paired. It can be compiled to Wasm and comes with JavaScript bindings for different environments.

The Wasm blob is 448K big (compared to 3.0M of the current Go-based build). It also speeds up verification time from 150ms to 50ms.

---

Those are the benchmarks I ran in Node.js 14.10. Please note that instantiation times canot be compared fairly since my proof of concept uses synconous CommonJS module loading in Node.js where the Wasm instantiation happens during module loading. However, beacon verification times should be fair.

Verification timings current master

> [email protected] test /projects/drand-client
> ava -v -T 10m
(node:1839) ExperimentalWarning: The ESM module loader is experimental.
(node:1840) ExperimentalWarning: The ESM module loader is experimental.
  ✔ optimizing › should fail to get info if all clients fail
  ✔ optimizing › should fail to get randomness if all clients fail
  ✔ optimizing › should get info from working client
  ✔ optimizing › should get from the fastest client (107ms)
  ✔ optimizing › should get randomness from working client (223ms)
  ✔ optimizing › should switch to a faster client (413ms)
(node:1838) ExperimentalWarning: The ESM module loader is experimental.
  ✔ chain › should get round 1 when time is less than genesis
  ✔ chain › should get round 1 for first round
  ✔ chain › should get round 2 for second round
  ✔ chain › should get time 0 when round is < 0
  ✔ chain › should get time 0 for first round
  ✔ chain › should get time 1000 for second round
Verification time: 1726ms (0ms info; 163ms instantiation; 1563ms verify beacon)
Verification time: 1720ms (0ms info; 797ms instantiation; 923ms verify beacon)
Verification time: 1719ms (0ms info; 1210ms instantiation; 509ms verify beacon)
Verification time: 1606ms (0ms info; 1382ms instantiation; 224ms verify beacon)
  ✔ drand › should abort get (1.8s)
  ✔ drand › should disable beacon verification (1.8s)
Verification time: 155ms (0ms info; 0ms instantiation; 155ms verify beacon)
  ✔ drand › should get specific randomness round (2s)
  ✔ optimizing › should watch from the fastest client (2.1s)
Verification time: 158ms (0ms info; 0ms instantiation; 158ms verify beacon)
Verification time: 143ms (0ms info; 0ms instantiation; 143ms verify beacon)
  ✔ drand › should get latest randomness (2.3s)
Verification time: 313ms (0ms info; 0ms instantiation; 313ms verify beacon)
Verification time: 151ms (0ms info; 0ms instantiation; 151ms verify beacon)
Verification time: 140ms (0ms info; 0ms instantiation; 140ms verify beacon)
  ✔ drand › should watch for randomness (1m 16.6s)
  ─

  18 tests passed

Verification timings using the Rust implementation

> [email protected] test /projects/drand-client
> ava -v -T 10m


(node:1917) ExperimentalWarning: The ESM module loader is experimental.
  ✔ chain › should get round 1 when time is less than genesis
  ✔ chain › should get round 1 for first round
  ✔ chain › should get round 2 for second round
  ✔ chain › should get time 0 when round is < 0
  ✔ chain › should get time 0 for first round
  ✔ chain › should get time 1000 for second round
(node:1918) ExperimentalWarning: The ESM module loader is experimental.
(node:1919) ExperimentalWarning: The ESM module loader is experimental.
  ✔ optimizing › should fail to get info if all clients fail
  ✔ optimizing › should fail to get randomness if all clients fail
  ✔ optimizing › should get info from working client
  ✔ optimizing › should get from the fastest client (107ms)
  ✔ optimizing › should get randomness from working client (181ms)
Verification time: 44ms (0ms info; 0ms instantiation; 44ms verify beacon)
  ✔ drand › should abort get (172ms)
Verification time: 49ms (0ms info; 0ms instantiation; 49ms verify beacon)
Verification time: 44ms (0ms info; 0ms instantiation; 44ms verify beacon)
Verification time: 59ms (0ms info; 0ms instantiation; 59ms verify beacon)
  ✔ optimizing › should switch to a faster client (406ms)
Verification time: 49ms (0ms info; 0ms instantiation; 49ms verify beacon)
  ✔ drand › should get specific randomness round (413ms)
Verification time: 47ms (0ms info; 0ms instantiation; 47ms verify beacon)
  ✔ drand › should disable beacon verification (657ms)
Verification time: 43ms (0ms info; 0ms instantiation; 43ms verify beacon)
  ✔ drand › should get latest randomness (755ms)
  ✔ optimizing › should watch from the fastest client (2.1s)
Verification time: 45ms (0ms info; 0ms instantiation; 45ms verify beacon)
Verification time: 43ms (0ms info; 0ms instantiation; 43ms verify beacon)
Verification time: 51ms (0ms info; 0ms instantiation; 51ms verify beacon)
  ✔ drand › should watch for randomness (56.3s)
  ─

  18 tests passed

Add speed test to optimizing client

Would allow the client to select the fastest URL to get randomness from.

https://github.com/drand/drand/blob/master/client/optimizing.go#L135-L169