Skip to main content

Web3 API

Info

This API enables you to use our RNG in a smart contract. If you need to call our RNG from anything else than a smart contract, use the Web2 API instead.

Introduction​

Requesting randomness on Random.win consists of deploying a random draw request onchain.

Once the request is fulfilled and the random numbers are generated, you are automatically notified, and can export these numbers to use them in your smart contract.

Request randomness​

Without a verification page​

If your smart contract doesn't need a verification page it can permissionlessly call the deployDraw functions of the Main contract.

With a verification page​

To request randomness with a verification page your can call the deployDraw function of the Deployer contract.

Endpoint

Deployer(deployerAddress).deployDraw(string memory title, string memory rules, string memory participants, string memory numbers, string memory scheduledAt, string memory algorithm)

where deployerAddress is the address of our deployer contract.

Parameters

  • title: The title of the page that will be created for your draw
  • rules: Description of the rules of the draw
  • participants: What we call participants are the entities that you want to draw from. It can be either:
    • A list of participants with each participant separated by the delimiter \n, for example "John\nJack\nJoe" or "1\n2\n3\n4\n5\n6\n7\n8\n9". The maximum number of participants is 1,000,000.
    • Alternatively, you can set this parameter to the number of participants without specifying a list of participants, for example "3" instead of "John\nJack\nJoe", or "9" instead of "1\n2\n3\n4\n5\n6\n7\n8\n9".
  • numbers: The number of random numbers that will be generated, that is, the number of participants that will be randomly selected. Maximum is 500. Should be less or equal to the number of participants.
  • scheduledAt: The timestamp, in seconds, when the randomness generation will be triggered. It will take 5 more seconds after that for the randomness generation to complete. This parameter enables you to post a request onchain now but generate the randomness at a later date, which can be useful in some cases. Use 0 to ask for randomness immediately.
  • algorithm: The random draw algorithm to use. Use 0 for Ordered outcomes, 1 for Fisher-Yates, or 2 for Fisher-Yates (GLI-19 certified). If you don't know which one to choose we recommend you to use 0.

Return value

  • requestId: The request ID for the deployment

Callbacks

Additionnaly, we recommend you to implement the following 2 functions in your contract to track the progress of your deployments:

interface CallbackContract {
    function fulfillDrawCid(bytes32 requestId, string memory cid, bytes memory error) external;
    function fulfillDrawWinners(string memory cid) external;
}
  • fulfillDrawCid will be called whenever a deployment is completed. Either cid or error parameter will be set, but never both.
  • fulfillDrawWinners will be called whenever a random draw is completed and the winners are publicly available. You can then use the received cid to call checkRandomNumbers in our main contract to retrive the winners in your contract.

Example code

You can use the following contract to test our API:

ExampleContract.sol
pragma solidity 0.8.23;

import {ConfirmedOwner} from "chainlink/src/v0.8/shared/access/ConfirmedOwner.sol";


contract ExampleContract is ConfirmedOwner {

    event fulfilledRequestId(bytes32 requestId);
    event fulfilledDrawCid(bytes32 requestId, string cid, bytes err);
    event fulfilledDrawWinners(uint32[] memory winners);

    private Main mainContract;

    constructor(address mainAddress) ConfirmedOwner(msg.sender) {
        mainContract = Main(mainAddress);
    }

    function deployDraw(address deployerAddress, string memory title, string memory rules, string memory participants, string memory numbers, string memory scheduledAt, string memory algorithm) external onlyOwner returns (bytes32 requestId) {
        requestId = Deployer(deployerAddress).deployDraw(title, rules, participants, numbers, scheduledAt, algorithm);
        emit fulfilledRequestId(requestId);
        return requestId;
    }

    function fulfillDrawCid(bytes32 requestId, string memory cid, bytes memory err) external {
        emit fulfilledDrawCid(requestId, cid, err);
    }

    function fulfillDrawWinners(string memory cid) external {

        uint32[] memory winners = mainContract.checkRandomNumbers(cid);
        emit fulfilledDrawWinners(winners);
    }
   
}

interface Deployer {
    function deployDraw(string memory title, string memory rules, string memory participants, string memory numbers, string memory scheduledAt, string memory algorithm) external returns (bytes32 requestId);
}

interface Main {
    function checkRandomNumbers(string memory cid) external view returns (uint32[] memory);
}
info

Don't forget to top up your account before calling deployDraw otherwise any deployment will fail.

Last updated on