Example - Shuffle an Array

The GetShuffledArrayExample is an example of how to use the GeneralRandcastConsumerBase to request and consume randomness of type Shuffling to request a shuffled array.

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

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

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

    constructor(address adapter) BasicRandcastConsumerBase(adapter) {}

    /**
     * Requests randomness
     */
    function getShuffledArray(uint32 upper) external returns (bytes32) {
        bytes memory params = abi.encode(upper);
        return requestRandomness(RequestType.Shuffling, params);
    }

    /**
     * Callback function used by Randcast Adapter
     */
    function fulfillShuffledArray(bytes32 requestId, uint256[] memory array) internal override {
        randomResults[requestId] = array;
        shuffleResults = array;
    }

    function lengthOfShuffleResults() public view returns (uint256) {
        return shuffleResults.length;
    }
}

Here's a breakdown of the GetShuffledArrayExample contract:

1. Imports the necessary contract:

import "../GeneralRandcastConsumerBase.sol";

2. Inherits the imported contract:

contract GetShuffledArrayExample is GeneralRandcastConsumerBase { ... }

3. Defines a mapping and an array to store the randomness results:

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

randomResults maps request IDs to the corresponding shuffled arrays received from the adapter. shuffleResults holds the latest shuffled array.

4. Initializes the contract with the adapter address:

constructor(address adapter) BasicRandcastConsumerBase(adapter) {}

5. Implements the getShuffledArray() function to request a shuffled array:

function getShuffledArray(uint32 upper) external returns (bytes32) {
    bytes memory params = abi.encode(upper);
    return requestRandomness(RequestType.Shuffling, params);
}

The function takes an upper parameter to define the upper bound of the array elements (0 to upper - 1) and requests a shuffled array from the adapter using the requestRandomness function inherited from GeneralRandcastConsumerBase.

6. Overrides the fulfillShuffledArray() function to handle the shuffled array returned by the adapter:

function fulfillShuffledArray(bytes32 requestId, uint256[] memory array) internal override {
    randomResults[requestId] = array;
    shuffleResults = array;
}

This function stores the shuffled array in the randomResults mapping and updates the shuffleResults array with the latest shuffled array.

7. Implements the lengthOfShuffleResults() function to return the length of the latest shuffled array:

function lengthOfShuffleResults() public view returns (uint256) {
    return shuffleResults.length;
}

In summary, the GetShuffledArrayExample contract demonstrates how to use the GeneralRandcastConsumerBase to request a shuffled array of elements from a randomness Adapter and store the received shuffled arrays.