# @pooltogether/uniform-random-number

> PoolTogether Solidity Modulo Bias library

Latest version **1.0.0-beta.2** (published 2021-07-26) · SEE LICENSE IN LICENSE license · 0 weekly downloads

## Install

```sh
npm install @pooltogether/uniform-random-number
pnpm add @pooltogether/uniform-random-number
yarn add @pooltogether/uniform-random-number
bun add @pooltogether/uniform-random-number
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.0-beta.2 |
| Published | 2021-07-26 |
| First published | 2020-12-08 |
| Weekly downloads | 0 |
| License | SEE LICENSE IN LICENSE |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 173.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 365 |
| Author | Brendan Asselstine brendan@pooltogether.com |
| Maintainers | asselstine, chuckbergeron, dylandesrosier, aodhgan, pierrick, kamesdev |

## Links

- npm: https://www.npmjs.com/package/@pooltogether/uniform-random-number
- Repository: git@github.com:pooltogether/pooltogether-contracts
- npm.io page: https://npm.io/package/@pooltogether/uniform-random-number

## Recent versions

- 1.0.0-beta.2 (latest) — 2021-07-26
- 1.0.0-beta.1 (beta) — 2020-12-08
- 1.0.0 — 2021-07-24

## README

# Uniform Random Number

[![CircleCI](https://circleci.com/gh/pooltogether/uniform-random-number.svg?style=svg)](https://circleci.com/gh/pooltogether/uniform-random-number)

This Solidity library eliminates module bias when using a large number to select from a limited range of numbers.

For example:

- Assume the max unsigned integer is 5
- random() selects an integer between 0 and 5

We want to use the random number to select a value between 0 and 3.

selection = random() % 4

The above might do, until we realize that:

| random() | selection |
| ---------| --------- |
| 0 | 0 |
| 1 | 1 |
| 2 | 2 |
| 3 | 3 |
| 4 | 0 |
| 5 | 1 |

Notice that 0 and 1 are overrepresented.  This is modulo bias, and is problematic when making *fair* selection algorithms.

This library mitigates modulo bias using an algorithm described in [this article](https://medium.com/hownetworks/dont-waste-cycles-with-modulo-bias-35b6fdafcf94).

# Installation

Add to your `package.json`:

```json
{
  "dependencies": {
    "@pooltogether/uniform-random-number": "pooltogether/uniform-random-number#master"
  }
}
```

# Usage

```solidity
import "pooltogether/uniform-random-number/contracts/UniformRandomNumber.sol";

// ...

uint256 randomNumber = uint256(keccak('Hello'));
uint256 upperLimit = 10;
UniformRandomNumber.uniform(randomNumber, upperLimit);
```

# Audit

This code has been audited by [OpenZeppelin](https://openzeppelin.com/) and [Quantstamp](https://quantstamp.com/) as part of the [PoolTogether codebase](https://github.com/pooltogether/pooltogether-contracts).

---
_Source: https://npm.io/package/@pooltogether/uniform-random-number · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._