provably-fair-rng

A provably fair RNG based on a stream cipher

Last updated 5 months ago by
emilbayes .

ISC ·
Repository ·
Bugs ·
Original npm ·
Tarball ·
package.json
$ cnpm install provably-fair-rng

SYNC missed versions from
official npm registry.

`provably-fair-rng`

A provably fair RNG based on a stream cipher

```
var pfRng = require('provably-fair-rng')
// Key could come from a hash-chain
var key = Buffer.from('256c83b297114d201b30179f3f0ef0cace9783622da5974326b436178aeef610', 'hex')
// Nonce could be something public, here the bitcoin block hash #611707
// Nonces are 24 bytes, hence we use the 24 low order bytes
var nonce = Buffer.from('0000000000000000000ea81bb2476eeb976af760d27217708a73889a95e1ea2d'.slice(-48), 'hex')
var rng = pfRng(key, nonce)
console.log(rng(8)) // 8 Random bytes
console.log(rng.bytes) // 8
console.log(rng.double()) // Random double. Consumes 7 bytes
console.log(rng.uniform(1001)) // Random integer between [0, 1000]. Consumes 7 bytes for each iteration
console.log(rng.bytes) // 8 + 7 + 7 = 22
console.log(rng.trails) // 3
console.log(rng.sample(3, 10)) // Return 3 integers in [0, 10)
console.log(rng.shuffle(['a', 'b', 'c'])) // Permute a, b, c
```

`const rng = pfRng(key, nonce)`

Create a new RNG from a `key`

and a `nonce`

, which must be `pfRng.KEYBYTES`

and `pfRng.NONCEBYTES`

long respectively. Uses `chacha20`

as the underlying primitive

Other options include:

`const rng = pfRng.xchacha(key, nonce)`

`const rng = pfRng.salsa(key, nonce)`

`const rng = pfRng.xsalsa(key, nonce)`

Each with associated constants on `pfRng.*.KEYBYTES`

and `pfRng.*.NONCEBYTES`

`const bytes = rng.bytes`

How many bytes have been read from the current instance

`const trails = rng.trails`

How many times was a read call made from the instance

`const buf = rng(bytes)`

Return a `Buffer`

of `bytes`

from the stream

`const num = rng.double()`

Return a random double in the interval `[0, 1)`

, which is unbiased, uniform and equidistant. Consumes 7 bytes

`const n = rng.uniform(max)`

Read a random integer uniformly and unbiased in the interval `[0, max)`

. Consumes 7 bytes for each trail, but may do multiple trails in a single call due to rejection sampling

`const xs = rng.sample(n, p)`

Pick `n`

unique, random integers from the interval `[0, p)`

which can be used as indexes into another table. Uses rejection sampling multiple times so the above note from `rng.uniform`

applies

`const arr = rng.shuffle(arr)`

Unbiased shuffle (Fisher-Yates/Knuth) of `arr`

. Note that this mutates `arr`

and returns it (for convenience). Uses rejection sampling multiple times so the above note from `rng.uniform`

applies

`const idx = rng.weighted(weights)`

Samples an index from `weights`

, which are decimal proportions. Samples a single double from `rng.double`

above

`const idx = rng.weightedIntegers(weights)`

Samples an index from `weights`

, which are integer proportions. Uses rejection sampling once so the above note from `rng.uniform`

applies

```
npm install provably-fair-rng
```

- 2.0.2 ... latest (5 months ago)

Maintainers (1)

Downloads

Today
0

This Week
0

This Month
0

Last Day
0

Last Week
0

Last Month
0

Dependencies (2)

- nanoassert ^2.0.0
- sodium-native ^3.1.1

Dev Dependencies (3)

- hash-chain ^2.0.1
- standard ^14.3.1
- tape ^4.12.1

Dependents (0)

None
Copyright 2014 - 2016 © taobao.org |