# index

**@buff-beacon-project/curby-client** • **Docs**

***

## @buff-beacon-project/curby-client

This is the official client library for the [CURBy Project](https://random.colorado.edu). It fetches and validates both the regular randomness chain and the DIRNG chain.

### Example

```js
import { Client, DIRNGClient } from '@buff-beacon-project/curby-client'

const client = Client.create()
const randomness = await client.randomness()
const myArray = [1, 2, 3, 4, 5]
const shuffled = randomness.shuffled(myArray)
// shuffled = [3, 4, 2, 5, 1]

const dirng = DIRNGClient.create()
const latest = await dirng.latest()
console.log(`Got info for round ${latest.round}. Stage is ${latest.stage}`)
```

### Using random bits

The randomness returned by this library is a [ByteHelper](/curby-js-client/interfaces/bytehelper.md) object. It provides many utility functions for working with random bits such as [ByteHelper.shuffled](/curby-js-client/interfaces/bytehelper.md#shuffled) to shuffle lists.

There is also an acompaning library, [rand-utils](https://curby.gitbook.io/rand-utils) that provides more utilities for working with random bits. It is particularly useful for getting unbiased random integers from a bitstream.

When using public randomness for the purpose of transparency, such as in a lottery, it is important to first publically commit to using a future round number. This prevents the operator from retroactively choosing a round that benefits them. Additionally, the operator should commit to the specific algorithm that is using the randomness.

A simple example of this would be to use a git commit hash of code to serve as the algorithm. The code should explicitly state the chainCid, round number, and be fully deterministic given the initial seed. There should also be a clear explanation of what to do in the event of an error.

### How to use this library

The CURBy client library provides two main classes, [Client](/curby-js-client/classes/client.md) (for classical randomness) and [DIRNGClient](/curby-js-client/classes/dirngclient.md) (for Quantum DIRNG randomness).

#### Classical Randomness

The [Client](/curby-js-client/classes/client.md) class is used to fetch randomness from the main classical CURBy chain which produces randomness every minute. The latest randomness can be fetched by simply calling the [Client.randomness](/curby-js-client/classes/client.md#randomness) method. The client library checks the following when fetching randomness:

* The chain has a valid signature
* The pulse and previous pulse have valid signatures
* The pulse index matches the expected index (round)
* The randomness has a valid precommitment value

For more information on the randomness generation process, see the [CURBy-RNG Chain reference](https://random.colorado.edu/concepts/curby-network#curby-rng-\(nist-beacon-inspired\)-chain).

#### Quantum DIRNG Randomness

The [DIRNGClient](/curby-js-client/classes/dirngclient.md) class is used to fetch randomness from the Quantum DIRNG chain, CURBY-Q. The latest randomness can be fetched by calling the [DIRNGClient.randomness](/curby-js-client/classes/dirngclient.md#randomness) method and to get randomness from a specific round, you can instead call [DIRNGClient.fetchRound](/curby-js-client/classes/dirngclient.md#fetchround) and use the `.randomness` property of the returned object, which is a [ByteHelper](/curby-js-client/interfaces/bytehelper.md) object.

The client library checks the following when fetching randomness:

* The chain has a valid signature
* All pulses have valid signatures
* The response pulse from the bell data chain has correct causal ordering with the CURBY-Q pulses.
* The seed pulse on the seed chain has correct causal ordering with the CURBY-Q pulses.
* The seed was correctly expanded to the correct number of bits. (NOTE: this requires the setting `validateSeed` to be true)

What is not validated, due to technical limitations:

* The DIRNG certificate, and randomness extraction.

In order to validate the randomness, a separate utility is required. See \[curby\_verify docker image)\[<https://github.com/buff-beacon-project/curby\\_verify>] for more information.

### See

<https://github.com/buff-beacon-project/curby_verify>

### Type Aliases

| Type alias                                                  | Description                  |
| ----------------------------------------------------------- | ---------------------------- |
| [NumberArray](/curby-js-client/type-aliases/numberarray.md) | A type for arrays of numbers |
| [WaitOptions](/curby-js-client/type-aliases/waitoptions.md) | The options for waiting      |

### Classical RNG

| Class, Type alias                                                   | Description                                               |
| ------------------------------------------------------------------- | --------------------------------------------------------- |
| [Client](/curby-js-client/classes/client.md)                        | A client for fetching randomness from the CURBy RNG chain |
| [ClientOptions](/curby-js-client/type-aliases/clientoptions.md)     | The options for the Rng Client                            |
| [LatestPulsePair](/curby-js-client/type-aliases/latestpulsepair.md) | A latest pulse pair                                       |
| [PulsePair](/curby-js-client/type-aliases/pulsepair.md)             | A pair of sequential pulses                               |
| [RandomnessRound](/curby-js-client/type-aliases/randomnessround.md) | A randomness round                                        |

### Constants

| Variable                                                       | Description                          |
| -------------------------------------------------------------- | ------------------------------------ |
| [CHAINS](/curby-js-client/variables/chains.md)                 | A constant containing the chain CIDs |
| [CURBY\_API\_URL](/curby-js-client/variables/curby_api_url.md) | The base URL for the CURBy API       |

### DIRNG

| Class, Type alias, Function                                               | Description                                                             |
| ------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| [DIRNGClient](/curby-js-client/classes/dirngclient.md)                    | A client for the Device Independent Randomness Generation (DIRNG) chain |
| [DIRNGClientOptions](/curby-js-client/type-aliases/dirngclientoptions.md) | The options for the DIRNG client                                        |
| [RoundData](/curby-js-client/type-aliases/rounddata.md)                   | A DIRNG round's data                                                    |
| [RoundValidations](/curby-js-client/type-aliases/roundvalidations.md)     | A round's validations                                                   |
| [pulsesToRoundData](/curby-js-client/functions/pulsestorounddata.md)      | Convert pulses to round data                                            |
| [withValidations](/curby-js-client/functions/withvalidations.md)          | Add validations to a round                                              |

### Errors

| Class                                                      | Description                                        |
| ---------------------------------------------------------- | -------------------------------------------------- |
| [InvalidPrecom](/curby-js-client/classes/invalidprecom.md) | An error for when a precommitment value is invalid |

### Utilities

| Interface, Function                                                          | Description                                                                                          |
| ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| [ByteHelper](/curby-js-client/interfaces/bytehelper.md)                      | A helper for working with randomness.                                                                |
| [byteHelper](/curby-js-client/functions/bytehelper.md)                       | Create a [ByteHelper](/curby-js-client/interfaces/bytehelper.md) from a set of bytes and a timestamp |
| [extractRandomness](/curby-js-client/functions/extractrandomness.md)         | Extract randomness from a pulse on an RNG chain                                                      |
| [getPrecommitmentValue](/curby-js-client/functions/getprecommitmentvalue.md) | Get the precommitment value for a pulse                                                              |
| [timeToNext](/curby-js-client/functions/timetonext.md)                       | Time until next rng pulse in milliseconds                                                            |
| [wait](/curby-js-client/functions/wait.md)                                   | Wait a specified number of milliseconds                                                              |
| [xorArrays](/curby-js-client/functions/xorarrays.md)                         | Perform an XOR operation on two arrays                                                               |
| [zip](/curby-js-client/functions/zip.md)                                     | zip the provided arrays together                                                                     |

### Validations

| Type alias, Function                                                                       | Description                             |
| ------------------------------------------------------------------------------------------ | --------------------------------------- |
| [Validation](/curby-js-client/type-aliases/validation.md)                                  | A validation result                     |
| [checkValidPrecommitmentValue](/curby-js-client/functions/checkvalidprecommitmentvalue.md) | Check if a precommitment value is valid |
| [usesDeterministicAlgorithm](/curby-js-client/functions/usesdeterministicalgorithm.md)     | -                                       |
| [validateBellResponse](/curby-js-client/functions/validatebellresponse.md)                 | Validate a bell response pulse          |
| [validateSeed](/curby-js-client/functions/validateseed.md)                                 | Validate the seed value                 |
| [validateSeedOrdering](/curby-js-client/functions/validateseedordering.md)                 | Validate the ordering of the seed pulse |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://curby.gitbook.io/curby-js-client/index.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.