Example - Roll a Dice

The RollDiceExample contract is an example of how to use the GeneralRandcastConsumerBase to request and consume randomness of type RandomWords simulating dice rolls.

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

import {
    GeneralRandcastConsumerBase,
    BasicRandcastConsumerBase
} from "randcast-user-contract/user/GeneralRandcastConsumerBase.sol";
// solhint-disable-next-line no-global-import
import "randcast-user-contract/user/RandcastSDK.sol" as RandcastSDK;

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

    // solhint-disable-next-line no-empty-blocks
    constructor(address adapter) BasicRandcastConsumerBase(adapter) {}

    /**
     * Requests randomness
     */
    function rollDice(uint32 bunch) external returns (bytes32) {
        bytes memory params = abi.encode(bunch);
        return _requestRandomness(RequestType.RandomWords, params);
    }

    /**
     * Callback function used by Randcast Adapter
     */
    function _fulfillRandomWords(bytes32 requestId, uint256[] memory randomWords) internal override {
        randomResults[requestId] = randomWords;
        diceResults = new uint256[](randomWords.length);
        for (uint32 i = 0; i < randomWords.length; i++) {
            diceResults[i] = RandcastSDK.roll(randomWords[i], 6) + 1;
        }
    }

    function lengthOfDiceResults() public view returns (uint256) {
        return diceResults.length;
    }
}

Here's a step-by-step explanation of the RollDiceExample contract and RandcastSDK:

1. Import GeneralRandcastConsumerBase contract:

import {GeneralRandcastConsumerBase, BasicRandcastConsumerBase} from "../GeneralRandcastConsumerBase.sol";
import "src/user/RandcastSDK.sol" as RandcastSDK;

2. Inherit the GeneralRandcastConsumerBase contract:

contract RollDiceExample is GeneralRandcastConsumerBase { ... }

3. Defines two mappings to store the random results for each requestId and the processed dice roll results:

mapping(bytes32 => uint256[]) public randomResults;
uint256[] public diceResults;

4. Implement the constructor, which takes the adapter address as an argument and passes it to the base contract:

constructor(address adapter) BasicRandcastConsumerBase(adapter) {}

5. Provide the rollDice() function that takes a bunch argument, representing the number of random words (dice rolls) to request, and sends the randomness request using the _requestRandomness() function:

function rollDice(uint32 bunch) external returns (bytes32) {
    bytes memory params = abi.encode(bunch);
    return _requestRandomness(RequestType.RandomWords, params);
}

6. Override the _fulfillRandomWords() function from BasicRandcastConsumerBase to handle the received random words and useRandcastSDK.roll to process them into dice roll results:

function _fulfillRandomWords(bytes32 requestId, uint256[] memory randomWords) internal override {
    randomResults[requestId] = randomWords;
    diceResults = new uint256[](randomWords.length);
    for (uint32 i = 0; i < randomWords.length; i++) {
        diceResults[i] = RandcastSDK.roll(randomWords[i], 6) + 1;
    }
}

7. Implement a lengthOfDiceResults() function to return the length of the diceResults array:

function lengthOfDiceResults() public view returns (uint256) {
    return diceResults.length;
}

The RollDiceExample contract showcases how to request randomness and process the received random words to simulate dice rolls. The contract leverages the capabilities provided by the GeneralRandcastConsumerBase contract to interact with the randomness Adapter.

In the next example, we will try to shuffle a deck of cards using the entropy retrieved.