# Drand: User Guide A drand beacon provides several public services to clients. Those services are exposed 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. This document explains ways to retrieve randomness from a running drand node. The first section shows the commands using the Go command-line application to retrieve public and private randomness. The second section shows how to communicate with drand nodes using plain HTTP methods with curl and [drandjs](https://github.com/PizzaWhisperer/drandjs), a Javascript library. ## Command-line application The command-line application can fetch public and private randomness from a running drand node, as well as its distributed public key. **Note on TLS**: Communication to a drand node is protected through TLS *by default*. If the contacted node is using a self-signed certificate, the client can use the `--tls-cert` flag to specify the server's certificate. As well, if the contacted node does not use TLS, the client must add the `--tls-disable` flag. ### Fetching Public Randomness To get the latest public random value, run: ```bash drand get public <group.toml> [--round <i>] ``` 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: ```json { "round": 1969, "previous": "e3a3e302335812e3bf4b684e1ddccef42eeff4d8a3625467d516286100d43744", "signature": "8019f77e6e3ef94a477d9dd0f9ca169e1fca917f3a6412eef581f855bc72c711c155fe0b6c2dc6ae005baa00a04ece3f1845955d408442a84a7a91a48327ff5ddb5d95d0363a79da27a929e4e05d22c3314c69435c6049da824335461437a01b", "randomness": "2b8a2db9fd29462991e3cc7b664eab2832a0b102d85ab70dc987c35d1d008862" } ``` Here `randomness` is the latest random value produced by the network: it is the hash (sha256) of the threshold BLS signature produced by the participants over the previous signature `previous` and the round number. The field `round` specifies the index of `randomness` in the sequence of all random values produced by this drand instance. The **message signed** is the concatenation of the round number treated as a `uint64` and the previous signature. Currently, the signature is using the [BLS12-381 curve](https://electriccoin.co/fr/blog/new-snark-curve/), signature are made over $\mathbf{G_2}$ and public keys are over $\mathbf{G_1}$. ### Fetching Private Randomness To get a private random value, run: ```bash drand get private <group.toml> ``` The JSON-formatted output produced by drand should look like the following: ```json { "Randomness": "764f6e3eecdc4aba8b2f0119e7b2fd8c35948bf2be3f87ebb5823150c6065764" } ``` The output is a 32-byte hex-encoded random value generated from the local randomness engine of the contacted server. The private randomness contained in the response is encrypted towards an ephemereal public key embedded in the request. The encryption is done using the [ECIES](https://en.wikipedia.org/wiki/Integrated_Encryption_Scheme) scheme. If the encryption is not correct, the command outputs an error instead. ### Using HTTP endpoints One may want get the public randomness by issuing a GET to a HTTP endpoint instead of using a gRPC client. This can be done easily with curl. For example, to get the last randomness value, you can use: ```bash curl <address>/api/public ``` All the REST endpoints specified in the [`api.proto`](https://github.com/dedis/drand/tree/master/protobuf/drand/api.proto) protobuf file. ## drandjs [drandjs](https://github.com/drand/drandjs) facilitates the use of drand's randomness in JavaScript-based applications. The main method `fetchAndVerify` of this JavaScript library fetches from a drand node the latest random beacon generated and then verifies it against the distributed key. For more details on the procedure and instructions on how to use it, please refer to the [readme](https://github.com/drand/drandjs/blob/master/README.md) of the library.