Solrand - Simple pseudo-random number generator library for Solidity

This library provides a simple and efficient way of pseudo-random number generation for Solidity smart contracts. It ensures that users commit to a given block in the future, making it impossible to know the outcome beforehand or manipulate it after. The package operates in two key phases:

1. Request randomness (Commit): Users initiate a request by committing to a future block number, nonce (allowing multiple requests within the same transaction) and some custom data that can be chose by the protocol developer. This request is stored on-chain and remains unpredictable until the reveal phase. A future block number (e.g., current block + 5) is selected to ensure the result remains unpredictable.

2. Fulfill randomness (Reveal): The actual randomness is determined by hashing the future block number hash and other committed parameters. This produces a bytes32 hash that can be cast to a number. In order to generate a number from range you can use the modulo operation. A safety check ensures the committed block number is not older than 256 blocks, as the EVM only retains block hashes for the last 256 blocks. If the block is too old, the transaction reverts with an "EXPIRED" status.

   If you plan to use this library to generate random traits on sellable items, make sure that users pay when requesting randomness. This way, they cannot cancel the request and try again if they don't like the result.

Installation

npm i solrand

How to use

1. SolrandConsumer base contract

You can inherit from the base SolrandConsumer contract and use _requestRandomness and _fullfillRandomness functions to request and fullfill randomness:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

import { SolrandConsumer } from "solrand/contracts/Solrand.sol";

contract SolrandConsumerExample is SolrandConsumer {
  uint256 public number;

  /**
   * Request a random number from the Solrand library and wait at least 5 blocks for it to be
   * fullfillable.
   * @return requestId The ID of the request
   */
  function requestRandomNumber() public returns (bytes32 requestId) {
    return
      _requestRandomness(
        block.number + 5,
        abi.encodePacked("Counter", msg.sender)
      );
  }

  /**
   *
   * @param requestId The ID of the request to fullfill
   * @return The random number
   */
  function fullfillRandomNumber(bytes32 requestId) public returns (uint256) {
    bytes32 randomValue = _fullfillRandomness(requestId);
    number = uint256(randomValue);
    return number;
  }
}

SolrandConsumer uses ERC7201 storage pattern, so you can safely use it in upgradeable contracts.

2. SolrandLib

This is the underlying library used by the SolrandConsumer base contract. You can use the library directly to generate randomness in your contracts, just make sure to keep the parameters in your contract.

  uint requestBlockNumber = block.number;
  uint targetBlockNumber = block.number + 10;
  uint nonce = 1;
  bytes memory requesterIdentifier = abi.encodePacked(
    // arbitrary data like user address, NFT ID they hold, in game points amount, etc.
    "unique requester identifier",
    address(0x1337),
    timestamp
  );

  bytes32 requestId = SolrandLib.requestRandomness(
    targetBlockNumber,
    nonce,
    requesterIdentifier
  );

  // Wait until the target block +1 is reached (+1 because the blockhash of current block is not
  // available, only the last 256 block hashes are available)
  // In foundry you can use the following cheatcode to wait for the block:
  // vm.roll(targetBlockNumber + 1);

  // Consumer contract should hold this data like shown in the SolrandConsumer
  uint256 randomNumber = uint256(
    SolrandLib.fullfillRandomness(
      requestBlockNumber,
      targetBlockNumber,
      nonce,
      requesterIdentifier
    )
  );

Build

pnpm build

Test

pnpm test

Format

pnpm prettier:write

Deploy example contract

forge script script/SolrandConsumerDeployment.s.sol:SolrandConsumerDeploymentScript --rpc-url <your_rpc_url> --private-key <your_private_key> --broadcast