In this tutorial, you will learn how to access the randomness feature and use it with a smart contract that returns a truly random coin flip 🎉

For a detailed feature explainer head to the network technical documentation

Import Secret VRF

In your Cargo.toml file, add secret-toolkit-storage 0.10.1:

[dependencies]
cosmwasm-std = { package = "secret-cosmwasm-std", version = "1.1.10" }
cosmwasm-storage = { package = "secret-cosmwasm-storage", version = "1.1.10" }
secret-toolkit-storage = "0.10.1"

Tutorial - Coin Flip

What follows is a step-by-step tutorial of how to use Secret Network's randomness API to generate a coin flip (returning either 0 or 1) with true randomness. You can follow along and/or view the completed code in this repo.

Contract.rs

To consume the random number, you need to import the necessary dependencies in your contract.rs file in order to access the random number from the env parameter.

In your contract, import the necessary dependencies (these are already imported in the cloned repo):

use cosmwasm_std::{Binary, Env, MessageInfo, Response, Result};

In the contract's entry point (e.g., execute, instantiate, or query), you can access the random number from the env parameter:

#[entry_point]
pub fn execute(
    deps: DepsMut,
    env: Env,
    _info: MessageInfo,
    msg: ExecuteMsg,
) -> Result<Response, ContractError> {
    match msg {
        ExecuteMsg::Flip {} => try_flip(deps, env),
    }
}

The env and block_info structures are defined as:

pub struct Env {
    pub block: BlockInfo,
    pub contract: ContractInfo,
    pub transaction: Option<TransactionInfo>,
}

pub struct BlockInfo {
    /// The height of a block is the number of blocks preceding it in the blockchain.
    pub height: u64,
    pub time: Timestamp,
    pub chain_id: String,
    #[cfg(feature = "random")]
    #[serde(skip_serializing_if = "Option::is_none")]
    pub random: Option<Binary>,
}

Where random is 32 bytes and base64 encoded.

Accessing the Env struct

Below is a simple coin flip function that uses the randomness feature:

pub fn try_flip(deps: DepsMut, env: Env) -> Result<Response, ContractError> {
    config(deps.storage).update(|mut state| -> Result<_, ContractError> {
        let coin_flip = env.block.random.unwrap().0[0] % 2;
        state.flip = coin_flip;
        Ok(state)
    })?;

    deps.api.debug("flipped!");
    Ok(Response::default())
}

try_flip() uses the config function to update the state of the smart contract by flipping a coin and storing the result in the flip field in the state variable. Specifically, it generates a random number using the random field of the env.block object, which is an optional value representing the most recent block's metadata, and takes the modulo 2 to obtain a value of either 0 or 1. It then updates the flip field of the state variable to this value.

Interacting with the Coin Flip Contract

Now, let's compile, upload, instantiate, and execute the contract to see it in action!

Compile

To compile your contract, run make build-mainnet-reproducible

make build-mainnet-reproducible

This returns the optimized contract wasm file, ie contract.wasm.gz

Upload and Instantiate randomness contract

Upload and instantiate your contract to Secret Network testnet with the upload script here.

If you would like to use your own wallet addres, be sure to update the mnemonic.

cd node 
npm i
node index

Execute

Now that you have a contract address you can execute the coin flip with the randomness feature!

To flip the coin, update the contract address and code hash with your parameters and run:

node try-flip

And to query that it was successful, update the contract address and code hash with your parameters and run:

node query-flip

Summary

Congrats! In this step-by-step tutorial on creating a coin flip contract, you learned how to compile, upload, instantiate, and execute a contract on Secret testnet using Secret Network's randomness API to generate random numbers 🎉 For documentation on Secret VRF in a contract on another IBC-connected chain, click here.

Introduction

Secret Network's randomness API allows developers to access random numbers in their CosmWasm contracts, enhancing the capabilities of the platform. The randomness feature is accessible within Secret Contracts through the Env struct. It includes an optional random field, which contains a random number as a Binary type. The random field is only available when the "random" feature is enabled.

Use Cases

Randomness is essential in many applications, including:

• Gaming and gambling platforms, where fair and unpredictable outcomes are crucial

• Cryptographic systems that require secure random keys or nonces

• Randomized algorithms for various use cases, such as distributed systems or optimization problems

How It Works

1. The proposer for each block generates a strong, random seed inside .

2. This seed is then included in the block header and signed by all validators who can verify its authenticity inside their SGX.

3. Secret Network's in-SGX light client prevents the proposer from simulating a block before all other validators sign it. Consequently, the proposer cannot gain maximal extractable value (MEV) by generating random seeds until they find a favorable simulation of the block.

4. Before calling the contract, the chain injects env.block.random = hkdf_sha256(block_random_seed + wasm_call_count).

   Thus each contract call gets a unique random seed.