Example - Get Random Number

The GetRandomNumberExample contract is an example of how to use the GeneralRandcastConsumerBase to request and consume randomness of type Randomness.

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

import {
    GeneralRandcastConsumerBase,
    BasicRandcastConsumerBase
} from "randcast-user-contract/user/GeneralRandcastConsumerBase.sol";

contract GetRandomNumberExample is GeneralRandcastConsumerBase {
    /* requestId -> randomness */
    mapping(bytes32 => uint256) public randomResults;
    uint256[] public randomnessResults;

    constructor(address adapter) BasicRandcastConsumerBase(adapter) {}

    /**
     * Requests randomness
     */
    function getRandomNumber() external returns (bytes32) {
        bytes memory params;
        return requestRandomness(RequestType.Randomness, params);
    }

    /**
     * Callback function used by Randcast Adapter
     */
    function fulfillRandomness(bytes32 requestId, uint256 randomness) internal override {
        randomResults[requestId] = randomness;
        randomnessResults.push(randomness);
    }

    function lengthOfRandomnessResults() public view returns (uint256) {
        return randomnessResults.length;
    }

    function lastRandomnessResult() public view returns (uint256) {
        return randomnessResults[randomnessResults.length - 1];
    }
}

Here's a step-by-step explanation of the GetRandomNumberExample contract:

1. Inherit the GeneralRandcastConsumerBase contract:

contract GetRandomNumberExample is GeneralRandcastConsumerBase { ... }

2. Define a mapping randomResults to store randomness associated with each request ID:

mapping(bytes32 => uint256) public randomResults;

3. Define an array randomnessResults to store all received randomness values:

uint256[] public randomnessResults;

4. Implement the constructor to initialize the adapter address from the GeneralRandcastConsumerBase contract:

constructor(address adapter) BasicRandcastConsumerBase(adapter) {}

5. Provide the getRandomNumber() function to request randomness:

function getRandomNumber() external returns (bytes32) {
    bytes memory params;
    return requestRandomness(RequestType.Randomness, params);
}

This function calls the requestRandomness() function from the GeneralRandcastConsumerBase contract, which sends the randomness request to the adapter.

6. Override the fulfillRandomness() callback function:

function fulfillRandomness(bytes32 requestId, uint256 randomness) internal override {
    randomResults[requestId] = randomness;
    randomnessResults.push(randomness);
}

When the adapter fulfills the randomness request, this function is called with the requestId and the generated randomness. The randomness value is stored in both the randomResults mapping and the randomnessResults array.

7. Provides helper functions to retrieve the length of the randomnessResults array and the last randomness result:

function lengthOfRandomnessResults() public view returns (uint256) {
    return randomnessResults.length;
}

function lastRandomnessResult() public view returns (uint256) {
    return randomnessResults[randomnessResults.length - 1];
}

These functions allow users to query the length of the randomnessResults array and retrieve the last received randomness value.

Next, we will look at another example that uses the received random number as an entropy to throw a dice.