SecretVRF stands out in the competitive landscape of verifiable random functions (VRFs) by offering a significant cost and speed advantage over its principal competitors. Notably, it provides approximately a 4 times cost benefit, which is a massive saving for projects that rely on random number generation at scale. This economic efficiency is largely due to its optimized gas usage, which minimizes the on-chain transaction cost.

In addition to its cost benefits, SecretVRF is also twice as fast as its closest competitor. This speed improvement is critical for applications that require almost real-time randomness, such as gaming, lotteries, and various DeFi protocols.

To demonstrate, we have this small video here outlining all of the advantages of SecretVRF vs. its biggest competitor:

Gas Figures for SecretVRF vs Competitors

An example contract call using SecretVRF on Ethereum Sepolia which requests 20 random words is compared for its gas usage. Here, we use the example contracts provided in the documentation of Chainlink. In both cases, response time for Secret VRF is at around 1-2 blocks, so around 10s.

For calling the VRF for 20 random numbers (less is better):

94k Gas with Secretpath: Etherscan Sepolia

300k+ Gas for Chainlink VRF with their example project: Etherscan Sepolia

For the Callback (less is better):

55k gas with Secretpath: Etherscan Sepolia

200k+ gas for Chainlink VRF with their example project: Etherscan Sepolia

In total, we also do not need to pay in special LINK tokens and instead can just pay in the native gas token of the chain (here: Sepolia ETH), which saves you additional costs.

To summarize, SecretVRF's combination of cost efficiency, speed, and EVM chain compatibility makes it a compelling choice for developers and projects seeking reliable and economical verifiable random functions. Its technical innovations position it as a leader in the space, offering tangible benefits that can significantly enhance the performance and cost-effectiveness of a wide range of blockchain applications.

Converting from Chainlink VRF to Secret VRF is easier than you expect. Within four easy steps you can free your contract from bloat and use the lightweight and faster Secret VRF solution.

We start off with the example code from Chainlink from :

Removing Chainlink bloat

In the first step, we remove the imports and the inheritance of the VRFConsumerBaseV2 and add our SecretVRF interface from this. There is no

to get to this:

Here, the behavior of the callbackGasLimit is different than in ChainlinkVRF. The callback Gas limit is simply all of the gas that you need to pay in order to make callback, which includes the verification of the result as well. The callback gas is the amount of gas that you have to pay for the message coming on the way back. We recommend at least using 100_000+ in Callback gas to ensure that enough gas is available. In case you did not pay enough gas, the contract callback execution will fail.

Simplifying the Constructor

Next, we can also simplify the constructor since we do not need to define any extra variables or subscriptionIds. Going from this:

to this

Change request randomness function

Next, we need to slightly adjust the behavior of the function rollDice(address roller) function and how it calls the Request Randomness function within Secret VRF. Here, we need to use the Secret VRF gateway and call it directly instead.

Please make sure to actually prepay the right amount of callback gas directly as a value transfer into the contract. The callback gas is the amount of gas that you have to pay for the message coming on the way back. If you do pay less than the amount specified below, your Gateway TX will fail:

Add a check for the Secret VRF Gateway

Lastly, we'll add a small check to ensure that we actually got an incoming call from the SecretVRF gateway contract. For this, remove the internal and override flags on the function and add the require:

Conclusion

That's all that you need to convert your contract from ChainlinkVRF to SecretVRF.

Overview

SecretVRF over SecretPath enables EVM developers to access on-chain verifiable random numbers at a fraction of the cost and block time of traditional RNG oracles such as ChainlinkVRF. With fewer than 100 lines of code, you will have access to an infinite supply of randomness.

Getting Started

To get started, clone the repo:

git clone https://github.com/SecretFoundation/evm-secretpath-rng.git

EVM Prerequisites

1. Add Polygon Amoy testnet to Metamask.

2. Fund your Amoy wallet.

Configuring Environment Variables

Install the node dependencies:

npm install

Update the env file with your EVM wallet private key and Infura API key.

Upload & Instantiate RandomnessReceiver.sol

Compile your Solidity smart contract:

npx hardhat compile

Once the contract is compiled successfully, upload the contract to Polygon testnet:

npx hardhat run scripts/deploy.js --network polygon

Note the contract address:

RandomnessReceiver deployed to: 0x08D05bC52e503C68c38A32c1fA997FB521e614C4

Add the RandomnessReceiver contract address to your env file:

RANDOMNESS_RECEIVER_CONTRACT_ADDRESS="0x08D05bC52e503C68c38A32c1fA997FB521e614C4"

Execute RandomnessReceiver.sol

Now that you've uploaded your contract, it's time to set the SecretPath gateway address for Polygon Amoy and then request on-chain verifiable random numbers!

Set Gateway Contract

First, set the gateway address for Polygon Amoy testnet. You can do this by executing set_gateway.js:

npx hardhat --network polygon run ./scripts/set_gateway.js

Create Randomness Event Listener

Next, create an event listener so you can listen to when the random numbers that you request have been fulfilled.

Create the event listener by executing fulfill_randomness_event.js:

npx hardhat --network polygon run ./scripts/fulfill_randomness_event.js

Request Random Numbers

Now it's time to request random numbers! Currently, request_random.js is configured to request 3 random numbers, but you can update how many numbers you would like to request here (up to 2000 for this example).

Once you have configured how many random numbers you want to request, execute request_random.js:

npx hardhat --network polygon run ./scripts/request_random.js

Upon successful execution, your terminal will log the following:

Current gas price: 1.500000016 gwei
Amount of gas: 202500002160000
Transaction hash: 0x47efe733c6b64a5c65fae68a5fa0f2eb39be107a7d4930325104dfcee36474c2
Random Numbers requested successfully!

Navigate to your event listener terminal to see the returned random numbers:

Random numbers fulfilled for request ID: 7
Random Numbers: 94412630379044474934232934838909700375960606882138821083837396872559692127250,113337239238407277551866961530595655396141218773986266698805816049961297644274,27422614896457590254145871678336430245204859898445275988406473498974116581231

Congrats! You've just used SecretPath to request your first verifiable on-chain random numbers! 🎉

Conclusion

Secret VRF offers an innovative and cost-effective solution for EVM developers seeking access to verifiable random numbers. By following this guide, you've successfully set up your environment, deployed the RandomnessReceiver.sol contract, and interacted with the SecretPath network to request and receive random numbers. Dive into the world of decentralized randomness with SecretPath, where security meets simplicity. 🌟

Install and import dependencies

First, install all of the the dependencies via NPM:

npm install @solar-republic/cosmos-grpc @solar-republic/neutrino ethers secure-random

Next, import the following into your code:

import { ethers } from "ethers"; 
import { arrayify, hexlify, SigningKey, keccak256, recoverPublicKey, computeAddress } from "ethers/lib/utils"; 
import {ecdh, chacha20_poly1305_seal} from "@solar-republic/neutrino"; 
import {bytes, bytes_to_base64, json_to_bytes, sha256, concat, text_to_bytes, base64_to_bytes} from '@blake.regalia/belt';

In your vite.config.ts in the project, you need to add the support for bigInt into the esbuildOptions:

optimizeDeps: { 
    esbuildOptions: { 
        target: "esnext", 
        supported: { 
        bigint: true 
        }, 
    } 
}

Defining variables

To start, we first define all of our variables that we need for the encryption, as well as the gateway information:

const publicClientAddress = '0x3879E146140b627a5C858a08e507B171D9E43139' //EVM gateway contract address
const routing_contract = "secret1fxs74g8tltrngq3utldtxu9yys5tje8dzdvghr" //the contract you want to call in secret
const routing_code_hash = "49ffed0df451622ac1865710380c14d4af98dca2d32342bb20f2b22faca3d00d" //its codehash

First, we define the Gateway address that is specific to each chain, which can you can look up here Supported Networks.

Second, you need to input the private contract that you are going to call, in our case the Secret VRF RNG contact on Secret Network. The code for this example contract can be found here in case you want to deploy it yourself.

Initializing the Ethereum client

Next, init the Ethereum client that you are using to call the contract with. Here, we init the chainId to use the Ethereum sepolia testnet and use ethers.js to retrieve the address.

 await (window as any).ethereum.request({
    method: 'wallet_switchEthereumChain',
    params: [{ chainId: '0xAA36A7' }], // chainId must be in hexadecimal numbers
});

// @ts-ignore
const provider = new ethers.providers.Web3Provider(window.ethereum);
const [myAddress] = await provider.send("eth_requestAccounts", []);

Generating the encryption key using ECDH

Next, you generate ephermal keys and load in the public encryption key for the Secret Gateway that you can look up in Supported Networks. Then, use ECDH to create the encryption key:

//Generating ephemeral keys
const wallet = ethers.Wallet.createRandom();
const userPrivateKeyBytes = arrayify(wallet.privateKey);
const userPublicKey: string = new SigningKey(wallet.privateKey).compressedPublicKey;
const userPublicKeyBytes = arrayify(userPublicKey)

//Gateway Encryption key for ChaCha20-Poly1305 Payload encryption
const gatewayPublicKey = "A20KrD7xDmkFXpNMqJn1CLpRaDLcdKpO1NdBBS7VpWh3";
const gatewayPublicKeyBytes = base64_to_bytes(gatewayPublicKey);

//create the sharedKey via ECDH
const sharedKey = await sha256(ecdh(userPrivateKeyBytes, gatewayPublicKeyBytes));

Define the Calldata for the secret contract & Callback information

Next, you define all of the information that you need for calling the private contract on Secret + add the callback information for the message on its way back.

We begin by defining the function that we are going to call on the private secret contract, here it's request_random . Next, we add the parameters/calldata for this function, which is ("{ numWords: Number(numWords) }"and convert it into a JSON string.

Next, we define the callback Information. In this case, we are using the gateway contract as an example callback. Here, you would typically put in your own custom callback address and callback selector in.

//the function name of the function that is called on the private contract
const handle = "request_random"

//data are the calldata/parameters that are passed into the contract 
const data = JSON.stringify({ numWords: Number(numWords) })
    
const callbackAddress = publicClientAddress.toLowerCase();
//This is an empty callback for the sake of having a callback in the sample code.
//Here, you would put your callback selector for you contract in. 
const callbackSelector = iface.getSighash(iface.getFunction("upgradeHandler"))
const callbackGasLimit = Number(callback_gas_limit)

After defining the contract call and callback, we now construct the payload:

//payload data that are going to be encrypted
const payload = {
      data: data,
      routing_info: routing_contract,
      routing_code_hash: routing_code_hash,
      user_address: myAddress,
      user_key: bytes_to_base64(userPublicKeyBytes),
      callback_address: bytes_to_base64(arrayify(callbackAddress)),
      callback_selector: bytes_to_base64(arrayify(callbackSelector)),
      callback_gas_limit: callbackGasLimit,
}

Encrypting the Payload

Next, we encrypt the payload using ChaCha20-Poly1305. Then, we hash the encrypted payload into a ciphertextHash using Keccak256.

//build a Json of the payload 
const payloadJson = JSON.stringify(payload); 
const plaintext = json_to_bytes(payload);
//generate a nonce for ChaCha20-Poly1305 encryption 
//DO NOT skip this, stream cipher encryptions are only secure with a random nonce!
const nonce = crypto.getRandomValues(bytes(12));

//Encrypt the payload using ChachaPoly1305 and concat the ciphertext+tag to fit the Rust ChaChaPoly1305 requirements
const [ciphertextClient, tagClient] = chacha20_poly1305_seal(sharedKey, nonce, plaintext);
const ciphertext = concat([ciphertextClient, tagClient]);

//get Metamask to sign the payloadhash with personal_sign
const ciphertextHash = keccak256(ciphertext)

Signing the Payload with Metamask

Next, we use Metamask to sign the ciphertextHash using personal_sign. Then, we recover the user_pubkey from this signed message, which will be also passed into the Public Gateway.

//this is what metamask really signs with personal_sign, it prepends the ethereum signed message here
const payloadHash = keccak256(concat([
      text_to_bytes("\x19Ethereum Signed Message:\n32"),
      arrayify(ciphertextHash),
]))
//this is what we provide to metamask
const msgParams = ciphertextHash;
const from = myAddress;
const params = [from, msgParams];
const method = 'personal_sign';

const payloadSignature = await provider.send(method, params)
console.log(`Payload Signature: ${payloadSignature}`)

const user_pubkey = recoverPublicKey(payloadHash, payloadSignature)
console.log(`Recovered public key: ${user_pubkey}`)

Estimate the Callback Gas

The callback gas is the amount of gas that you have to pay for the message coming on the way back. If you do pay less than the amount specified below, your Gateway TX will fail:

/// @notice Increase the task_id to check for problems 
/// @param _callbackGasLimit the Callback Gas Limit

function estimateRequestPrice(uint32 _callbackGasLimit) private view returns (uint256) {
    uint256 baseFee = _callbackGasLimit*block.basefee;
    return baseFee;
}

Since this check is dependent on the current block.basefee of the block it is included in, it is recommended that you estimate the gas fee beforehand and add some extra overhead to it. An example of how this can be implemented in your frontend can be found in this example and here:

//Then calculate how much gas you have to pay for the callback
//Forumla: callbackGasLimit*block.basefee.
//Use an appropriate overhead for the transaction, 1,5x = 3/2 is recommended since gasPrice fluctuates.

const gasFee = await provider.getGasPrice();
const amountOfGas = gasFee.mul(callbackGasLimit).mul(3).div(2);

Packing the Transaction & Send

Lastly, we pack all the information we collected during previous steps into an info struct that we send into the Gateway contract. We the encode the function data. Finally, we set the tx_params. Please make sure to set an approiate gas amount for your contract call, here we used 150k gas. For the value of the TX, we send over the estimated callback gas that we calculated above.

// function data to be abi encoded
const _userAddress = myAddress
const _routingInfo = routing_contract
const _payloadHash = payloadHash
const _info = {
        user_key: hexlify(userPublicKeyBytes),
        user_pubkey: user_pubkey, 
        routing_code_hash: routing_code_hash,
        task_destination_network: "pulsar-3",  //Destination for the task, here: pulsar-3 testnet
        handle: handle,
        nonce: hexlify(nonce),
        payload: hexlify(ciphertext),
        payload_signature: payloadSignature,
        callback_gas_limit: Number(callbackGasLimit)
}

const functionData = iface.encodeFunctionData("send",
        [
            _payloadHash,
            _userAddress,
            _routingInfo,
            _info,
        ]
    )
    
const tx_params = [
    {
            gas: hexlify(150000),
            to: publicClientAddress,
            from: myAddress,
            value: hexlify(amountOfGas), // send that extra amount of gas in to pay for the Callback Gas Limit that you set
            data: functionData, 
        },
      ];

const txHash = await provider.send("eth_sendTransaction", tx_params);

For a detailed demonstration, you can watch our video tutorial available here:

After we've gone through an extensive example on how our example contract works, here's how to implement SecretVRF via SecretPath in your own contract in 4 easy steps:

Importing the Interface

First, import the ISecretVRF interface into your Solidity Contract:

/// @notice Interface of the VRF Gateway contract. Must be imported. 
interface ISecretVRF { 
    function requestRandomness(uint32 _numWords, uint32 _callbackGasLimit) external payable returns (uint256 requestId); 
}

Set the SecretVRF gateway contract

Second, set your gateway address to the Secret VRF Gateways. You only need to make sure that your contract knows the correct SecretVRF Gateway address, for example:

/// @notice VRFGateway stores address to the Gateway contract to call for VRF
address public VRFGateway;

address public immutable owner;

constructor() {
   owner = msg.sender;
}

modifier onlyOwner() {
    require(msg.sender == owner, "UNAUTHORIZED");
    _;
}

/// @notice Sets the address to the Gateway contract 
/// @param _VRFGateway address of the gateway
function setGatewayAddress(address _VRFGateway) external onlyOwner {
    VRFGateway = _VRFGateway;
}

Call the SecretVRF Gateway contract

Now, we implement the function that calls the SecretVRF Gateway on EVM. Note that you have to pay an extra amount of your gas token as CallbackGas:

/// @notice Event that is emitted when a VRF call was made (optional) 
/// @param requestId requestId of the VRF request. Contract can track a VRF call that way 
event requestedRandomness(uint256 requestId);

/// @notice Demo function on how to implement a VRF call using Secret VRF
function requestRandomnessTest(uint32 _numWords, uint32 _callbackGasLimit) external payable {
    // Get the VRFGateway contract interface 
    ISecretVRF vrfContract = ISecretVRF(VRFGateway);

    // Call the VRF contract to request random numbers. 
    // Returns requestId of the VRF request. A  contract can track a VRF call that way.
    uint256 requestId = vrfContract.requestRandomness{value: msg.value}(_numWords, _callbackGasLimit);

    // Emit the event
    emit requestedRandomness(requestId);
}

The callback gas is the amount of gas that you have to pay for the message coming on the way back. If you do pay less than the amount specified below, your Gateway TX will fail:

/// @notice Increase the task_id to check for problems 
/// @param _callbackGasLimit the Callback Gas Limit

function estimateRequestPrice(uint32 _callbackGasLimit) private view returns (uint256) {
    uint256 baseFee = _callbackGasLimit*block.basefee;
    return baseFee;
}

Since this check is dependent on the current block.basefee of the block it is included in, it is recommended that you estimate the gas fee beforehand and add some extra overhead to it. An example of how this can be implemented in your frontend can be found in this example and here:

//Then calculate how much gas you have to pay for the callback
//Forumla: callbackGasLimit*block.basefee.
//Use an appropriate overhead for the transaction, 1,5x = 3/2 is recommended since gasPrice fluctuates.

const gasFee = await provider.getGasPrice();
const amountOfGas = gasFee.mul(callbackGasLimit).mul(3).div(2);

Wait for the callback

From here, the SecretVRF Gateway will take care of everything, just wait 1-2 blocks for Gateway to provide you the random number by getting it from the Secret Networks on chain VRF and do the callback.

The SecretVRF gateway contract will always call the contract that called the VRF contract (using msg.sender) with the function selector bytes 0x38ba4614, which is the function:

function fulfillRandomWords(uint256 requestId, uint256[] calldata randomWords) external 

Now, the SecretVRF Gateway contract will verify the validity of the call and when all checks pass, it will call this function. In this case, we just emit a log as an example to finish our demo. Emitting a log is not obligatory and optional.

event fulfilledRandomWords(uint256 requestId, uint256[] randomWords);
/// @notice Callback by the Secret VRF with the requested random numbers
/// @param requestId requestId of the VRF request that was initally called
/// @param randomWords Generated Random Numbers in uint256 array
function fulfillRandomWords(uint256 requestId, uint256[] calldata randomWords) external {
    // Checks if the callback was called by the VRFGateway and not by any other address
    require(msg.sender == address(VRFGateway), "only Secret Gateway can fulfill");

    // Do your custom stuff here, for example:
    emit fulfilledRandomWords(requestId, randomWords);
}