labs4dev/drandjs

Javascript library which enables the use of drand's randomness in JavaScript-based applications

drandjs

drandjs is a Javascript library able to communicate with a public drand network. drandjs can fetch public randomness from a node or a group of nodes and verify it in the browser. drandjs uses the pairing-based library kyberJS from dedis to perform the verification locally.

NOTE: This software was created under the supervision of dedis lab. It is considered experimental and has NOT received a third-party audit yet. Therefore, DO NOT USE it in production or for anything security critical at this point.

Installation

The simplest way to use drandjs is to import the script from jsdelivr as in the following:

<script src="https://cdn.jsdelivr.net/gh/PizzaWhisperer/drandjs/dist/drand.js"></script>

Compile from sources: To compile the sources into a single bundled Javascript file, you can run make compile to create the file dist/drand.js ready to be included in your application.

Usage

The following is a Javascript snippet showing the shortest way to get verified randomness from a running drand network:

// the identity of the node we want to contact
var identity = {
  Address: "drand.zerobyte.io:8888",
  TLS: true,
};
// the distributed key of the public drand network (optional).
var dist_key = "51e1014efb8be0c0c8c70cec1473a0d5b2f40d3d926635b9e74c41f89673f6b37c0c752f67419a32db91abf31360d8659471b8709040cf650e908db7f4bda9308e01400477e3f586ccb607d7bcd47a0272cca6ec52d38d2599aedc70788f739a8dc265b7aaf7b6fd4aeb67058cbe5c586024c97068321117958b871741758b89";

fetchAndVerify(identity, dist_key)
  .then(function (fulfilled) {
  // The randomness was successfully fetched and verified. fulfilled has 
  // the following structure:
  // {
  //     round: <integer>,
  //     previous: <hexadecimal encoding of the previous randomness>,
  //     randomness: <hexadecimal encoding of randomness generated at 
  //     the given round>,
  // }
  })
  .catch(function (error) {
    // A problem occurred during the verification process. error has the 
    // same structure as fulfilled.
  })

There are two important pieces of information to provide to drandjs:

• Identity: It holds all required information to contact a drand node. The Address is the IP address or DNS name of the drand node the user wishes to contact. TLS is true if drandjs should contact this node over HTTPS (drand nodes by default are using HTTPS) and false if the node does not have a TLS certificate. One can retrieve the identity of drand nodes from the group configuration file of the network. See drand for more information.

• Distributed Key: It holds the distributed public key created during the setup phase of a drand network. The key must be in hexadecimal format and should be given out-of-bands (it can be obtained from the group configuration file or fetched from a drand node operator. If the key is not available, fetchAndVerifỳ allows to give an empty string in place of the dist_key argument, in which case, drandjs fetches the distributed key from the server as well as the randomness. However, in this mode of operation, the server can lie about the distributed key and thus create any valid randomness it wants.

API

Here is a list of public function drandjs exposes. Note that all byte-like arguments (such as the randomness), unless otherwise noted, are hexadecimal-encoded strings.

• fetchPublic(identity) fetches the latest public randomness at the specified drand node. See the service definition for the structure of the resulting JSON.

• verifyDrand(previous, randomness, round, distkey) returns true if the verification of the given randomness against the distkey over the message formed from both the previous and round arguments is successful. It returns false if an error occured during the verification process.

• fetchAndVerify(identity, distkey) sequentially calls fetchPublic and verifyDrand and returns a Promise, holding the eventual randomness in case of success and the error in case of failure. It returns a JSON structure such as:

{
  "randomness": "3393f21a641e7324b0b75ad0a40ba388e0add0bb5c9d61532ff501f35815bca85af6471f1f181a4d3c484d9cdf7a8fded25645ddde15fc33a15a01f61361c723",
  "previous": "05b851a3b36f11c6f38b2cfa808e3ed55256359694dc482639103c7668e702e70a165d73438cb30b5b73531cd6e17bed1ff623c3638cfdae85d815f339e85120",
  "round": 18332
}

• fetchGroup(identity) returns the current group the node denoted by the identity belongs to. The returned group contains all the nodes in the network, the threshold, the period and the distributed public key as well. We refer to the protobuf definition for more information.

• fetchKey(identity) returns only the distributed key from which the node denoted by the given identity holds a share. We refer to the protobuf definition for more information.

Test Server

We provide a script to locally run a server that will fake a drand node and a simple html file which show what you could do with fetchAndVerify.

To launch the server and open the html file, go to the example folder and execute:

python3 script.py