Native On-chain randomness
A step-by-step tutorial of how to use Secret Network's randomness API to generate a coin flip
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.9.0:
Make sure you're compiling with rust < 1.70. Newer versions are currently not compatible.
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.
Environment Configuration
LocalSecret is a tool that allows you to run a local Secret Network on your machine for testing and development purposes.
Here are the steps to use the randomness feature with LocalSecret:
Configure your developer environment and be sure to install the latest version of SecretCLI.
Clone the Secret Labs examples repo and then navigate to the vrf-randomness-tutorial folder:
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):
In the contract's entry point (e.g., execute, instantiate, or query), you can access the random number from the env
parameter:
The env and block_info structures are defined as:
Where random
is 32 bytes and base64 encoded.
Accessing the Env struct
Below is a simple coin flip function that uses the randomness feature:
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, in your terminal, make sure you have docker open, and then run:
This returns the optimized contract wasm file, ie contract.wasm.gz
Upload
To upload your contract to a containerized version of LocalSecret in docker, make sure you have docker installed and open, and then create a new tab in your terminal and run:
Congrats, you now have a new instance of LocalSecret running that can access the random number feature!
Next, create and fund a wallet so you can upload the contract to LocalSecret. Then run the following to upload:
To confirm that the contract upload was successful:
Instantiate
Now let's instantiate our contract with a starting flip of 1 (1 meaning Heads or Tales, up to you!)
To confirm that the contract instantiation was successful:
Execute
Now that we have a contract address (which is returned from the list-contract-by-code
query above), we an execute the coin flip with the randomness feature!
To flip the coin simply run:
And to query that it was successful, run:
You might have to execute the flip function a few times to see the queried flip change, since there is a 50% chance the flip will return the same number :D
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 LocalSecret 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.
Last updated