Quantum Random Function (QRF)

Introduction #

QCentroid QRF (Quantum Random Function) is a provably fair and verifiable quantum random number generator (RNG) that enables smart contracts to access random values without compromising security or usability.

If you are new to the QCentroid Embedded Framework and Smart Contracts, we recommend to start with the Quick start guide to learn the basics and build your first smart contract on Polygon.

What are quantum random numbers? #

Quantum Random Number are generated in a Quantum Random Number Generator Chip. These chips work by measuring the quantum random phase in light pulses. 

Get a random number #

This guide explains how to get random values using a simple contract to request and receive random values from QCentroid QRF v1. For more advanced examples with programmatic subscription configuration, see the Example Contracts section.

Table of contents

1. Requirements
2. Create and deploy a QRF v1 consumer contract
3. Request random values

1. Requirements #

This guide assumes that you know how to create and deploy smart contracts on Ethereum/Polygon testnets using the following tools:

• The Remix IDE
• MetaMask
• Polygon Mumbai testnet MATIC

2. Create and deploy a QRF v1 consumer contract #

For this example, use the QRFConsumer.sol sample contract. This contract imports the following dependencies:

• Ownable.sol
• QRFProviderInterface.sol

The Ownable import is used to add security to the contract. We strongly recommend you to use it.

QRF provider interface #

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

contract QRFProviderInterface {
    
    function requestQuantumRandomNumber(uint lengthBits, string memory callback_name) public payable returns (bytes32) {}
    
}										

The contract also includes pre-configured values for the necessary request parameters such as _QRFProviderAddress or _gasLimit and _QRFFee.

The getRandomNumber() function #

function getRandomNumber(uint lenghtBits) public payable returns (bytes32) 
{
    require( msg.value >= _QRFFee, "Provide some wei to call the provider" );
        
    // Call the Provider method
    QRFProviderInterface qrf = QRFProviderInterface(_QRFProviderAddress);

    _lastRandomNumber = 0; // Clear the last random number while it's been updated

    _lastRequestId = qrf.requestQuantumRandomNumber{value: _QRFFee}(lenghtBits, "randomNumberCallback");

    return _lastRequestId;
}										

This function receives one parameter, lenghtBits, the length of the random number to get (in bits), from 32 to 256. This number must be in multiples of 32.

The callback function #

function randomNumberCallback(uint256 number) public 
{
    _lastRandomNumber = number;
}										

Build and deploy the contract on Mumbai.

1. Open the QRFConsumer.sol contract in Remix.
2. On the Compile tab in Remix, compile the QRFConsumer.sol contract.
3. Configure your deployment. On the Deploy tab in Remix, select the Injected Web3 Environment, select the QRFConsumer contract from the contract list.
4. Click the Deploy button to deploy your contract on-chain (testnet). MetaMask opens and asks you to confirm the transaction.
5. After you deploy your contract, you’ll see your contract’s address and functions.

Your example contract is deployed and ready to use the QRF Provider. Next, request random values from QCentroid QRF.

3. Request random values #

The deployed contract rquests random values from QCentroid QRF, receives those values, and sotres them in the _lastRandomNumber variable. Run the getRandomNumber() function on your contract to start the request.

1. Return to Remix and view your deployed contract functions in the Deployed Contracts list.
2. Click the getRandomNumber() function to send the request for random values to QCentroid QRF. MetaMask opens and asks you to confirm the transaction. After you approve the transaction, QCentroid QRF processes your request.
3. QCentroid QRF fulfills the request and returns the random values to your contract in a callback that you can especify, it is the randomNumberCallback() function in our example.
   Depending on current testnet conditions, it might take a few minutes for the callback to return the requested random values to your contract.
4. After the QCentroid QRF returns the random values to your contract, the _lastRandomNumber variable stores the last requested random value. Click to check the value.

You deployed a simple contract that can request and receive random values from QCentroid QRF. See the Example Contracts section for the complete code of this example.

Example contracts #

The full code used in this example is shown below.

QRF consumer contact #

In this example, you created a consumer contract that calls the QRF Provider. The consumer contract uses static configuration parameters.

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

import "https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v4.5.0/contracts/access/Ownable.sol";
import "./QRFProviderInterface.sol";


contract QRFConsumer is Ownable{
   
    address public _QRFProviderAddress = 0x6db09363B6e30D59Dc90aE57A4A56519fD3569d2;
     
    uint256 public _lastRandomNumber;
    bytes32 public _lastRequestId;

    uint public fallback_counter = 0;
    uint public receive_counter = 0;

    uint public fallback_amount_counter = 0;
    uint public receive_amount_counter = 0;

    string public last_message;

    uint public _gasLimit = 500000;
    uint public _QRFFee = 10 ** 18;  // 1 MATIC

    constructor() {
    }

    function setQRFProviderAddress(address providerAddress) public onlyOwner {

        _QRFProviderAddress = providerAddress;
    }

    function setGasLimit(uint gasLimit) public onlyOwner {

        _gasLimit = gasLimit;
    }

    function setQRFFee(uint fee) public onlyOwner {

        _QRFFee = fee;
    }

    function getRandomNumber(uint lenghtBits) public payable returns (bytes32) 
    {
        require( msg.value >= _QRFFee, "Contract doesn't have enough funds to call the provider" );
        
        // Call the Provider method
        QRFProviderInterface qrf = QRFProviderInterface(_QRFProviderAddress);

        _lastRandomNumber = 0; // Clear the last random number while it's been updated

        _lastRequestId = qrf.requestQuantumRandomNumber{value: _QRFFee}(lenghtBits, "randomNumberCallback");

        return _lastRequestId;
    }

    /**
     * Receive the response in the form of uint256
     */ 
    function randomNumberCallback(uint256 number) public 
    {
        _lastRandomNumber = number;
    }

    
    receive() external payable {
        
        receive_counter++;
        receive_amount_counter += msg.value;
    }

    fallback(bytes calldata data) external payable returns(bytes memory){
        
        fallback_counter++;
        fallback_amount_counter += msg.value;

        last_message = string(data);

        return data;
    }

    function getBalance() public view onlyOwner returns(uint){
        return address(this).balance;
    }

    function withdraw() external onlyOwner {
        payable(owner()).transfer(address(this).balance);
    }

}										

Contract addresses #

Here are the addresses of the contracts deployed on chain.

Polygon Testnet (Mumbai) #

QRF Provider address: 0x6db09363B6e30D59Dc90aE57A4A56519fD3569d2  

Glossary #

• QRF. Quantum Random Function.
• QRF Provider. The smart contract deployed by QCentroid that provides the quantum random numbers to the blockchain.
• QRF Consumer. Any smart contract that consumes quantum random numbers through requests to the QRF Provider.
• Callback. A function that is invoked by an external smart contract (in our case, the QRF Provider) in response a previous request.