Quickstart

Installation

Solidity

We recommend foundry for managing your Solidity dependencies.
Install the latest conditional encryption Solidity library by running forge install randa-mu/[email protected].

Typescript

Install the latest conditional encryption library by running npm install @randamu/randomness.
This comes with Typescript types out of the box.

Write a smart contract that gets a random number

First create a contract that will request a random number at some future block:

import {Randomness} from "../lib/Randomness.sol";
contract MyLottery {
    bool drawInProgress;
    uint256 currentRequestID;
    address[] entrants;

    function startDraw() external {
        require(!drawInProgress, "cannot start a draw when one is in progress!");
        // we store the requestID so we can process the respose later
        currentRequestID = Randomness.request();
        
        drawInProgress = true;
    }
}

Then extend this contract to implement the IRandomnessReceiver interface:

import {Randomness, IRandomnessReceiver} from "../lib/Randomness.sol";

contract MyLottery is IRandomnessReceiver {
    bool drawInProgress;
    uint256 currentRequestID;
    address[] entrants;
    
    function onRandomnessReceived(uint256 requestID, bytes calldata signature) external {
        require(requestID == currentRequestID, "received the wrong randomness?");
        // strictly speaking this isn't necessary, as it's verified already by our smart contract
        // but if you're paranoid you can reverify it :)
        require(Randomness.verify(signature, requestID), "randomness was invalid!!");

        // note: the signature itself isn't randomness until it's been hashed, but our library handles that for you
        uint256 winnerIndex = Randomness.selectArrayIndices(entrants.length, 1, signature);
        address winner = entrants[winnerIndex];
        // pay out the winner
    }
}

Verifying random values with the typescript library

To verify random values, we pull them from chain and can verify them simply in the library

import { verify } from "@randamu/randomness"

const signature = // fetch the signature from chain using ethers.js or similar
    
const result: boolean = await verify(signature, { requestID: 12345, chainID: 31337 }) // chainID 31337 is the `furnace` testnet