Introduction
Smart contract developers
Witnet Node Operators
Developer Reference
Code Examples
Example 1: Bare Minimal
On each of the EVM compatible chains supported by Witnet there is an instance of the
WitnetRandomness contract that exposes the main randomness oracle functionality through a very simple interface.The best way to interact with the
WitnetRandomness contract is through the IWitnetRandomness interface, which is readily available in the witnet-solidity-bridge npm package.This very basic example shows how easy is to source random
uint32 values into your own contracts:1
// SPDX-License-Identifier: MIT
2
pragma solidity >=0.7.0 <0.9.0;
3
4
import "witnet-solidity-bridge/contracts/interfaces/IWitnetRandomness.sol";
5
6
contract MyContract {
7
8
uint32 public randomness;
9
uint256 public latestRandomizingBlock;
10
IWitnetRandomness immutable public witnet;
11
12
/// @param _witnetRandomness Address of the WitnetRandomness contract.
13
constructor (IWitnetRandomness _witnetRandomness) {
14
assert(address(_witnetRandomness) != address(0));
15
witnet = _witnetRandomness;
16
}
17
18
receive () external payable {}
19
20
function requestRandomNumber() external payable {
21
latestRandomizingBlock = block.number;
22
uint _usedFunds = witnet.randomize{ value: msg.value }();
23
if (_usedFunds < msg.value) {
24
payable(msg.sender).transfer(msg.value - _usedFunds);
25
}
26
}
27
28
function fetchRandomNumber() external {
29
assert(latestRandomizingBlock > 0);
30
randomness = witnet.random(type(uint32).max, 0, latestRandomizingBlock);
31
}
32
}
Copied!
Two-step Generation of Randomness
This example follows a very common workflow for many randomness use cases: first you need to take note of the current block number and ask the
WitnetRandomness to reseed itself, then, at a later time, you will be retrieving a random number that is derived from the random seed that was generated as a response to your former request.This 2-step process preserves unpredictability of the random numbers that you get because it guarantees that the number is derived from a seed that was generated only after the request was sent.
Range of the Random Numbers
This example is generating random numbers in the range
[0, 4294967296), but you can narrow that range down at will through the first argument of the witnet.random function:1
fromZeroToNine = witnet.random(10, 0, latestRandomizingBlock);
Copied!
As
witnet.random always assumes that the range starts with 0, you can use an addition to offset the range. For example, to make it [1, 12]:1
month = 1 + witnet.random(12, 0, latestRandomizingBlock);
Copied!
And for
[-100, 100]:1
temperature = -100 + witnet.random(201, 0, latestRandomizingBlock);
Copied!
Take into account that this example implements an asynchronous workflow — calling
fetchRandomNumber() right after requestRandomNumber() will most likely cause the transaction to revert. Please allow 5-10 minutes for the randomization request to complete.Example 2: Roll a die!
This example is doing something slightly more interesting: it simulates a dice game in which you need to pick a certain number, and then, after rolling the die, you will see if you guessed correctly what the lucky number would be:
1
// SPDX-License-Identifier: MIT
2
pragma solidity >=0.7.0 <0.9.0;
3
4
import "witnet-solidity-bridge/contracts/interfaces/IWitnetRandomness.sol";
5
6
contract DieContract {
7
8
uint32 sides;
9
struct Guess {
10
uint32 guessedNumber;
11
uint256 blockHeight;
12
}
13
mapping (address => Guess) public guesses;
14
IWitnetRandomness immutable public witnet;
15
16
event Right(string message);
17
event Wrong(string message);
18
19
/// @param _witnetRandomness Address of the WitnetRandomness contract.
20
constructor (IWitnetRandomness _witnetRandomness, uint32 _sides) {
21
assert(address(_witnetRandomness) != address(0));
22
witnet = _witnetRandomness;
23
sides = _sides;
24
}
25
26
receive () external payable {}
27
28
function guessNumber(uint32 _number) external payable {
29
assert(_number > 0);
30
assert(_number <= sides);
31
assert(guesses[msg.sender].guessedNumber == 0);
32
33
guesses[msg.sender].guessedNumber = _number;
34
guesses[msg.sender].blockNumber = block.number;
35
36
uint _usedFunds = witnet.randomize{ value: msg.value }();
37
if (_usedFunds < msg.value) {
38
payable(msg.sender).transfer(msg.value - _usedFunds);
39
}
40
}
41
42
function roll() external {
43
assert(guesses[msg.sender].guessedNumber != 0);
44
45
uint32 luckyNumber = 1 + witnet.random(
46
sides,
47
0,
48
guesses[msg.sender].blockNumber
49
);
50
51
if (luckyNumber == guesses[msg.sender].guessedNumber) {
52
emit Right("Congratulations! You guessed the right number!");
53
} else {
54
emit Wrong("Sorry! You didn't guess the right number!");
55
}
56
57
guesses[msg.sender].guessedNumber = 0;
58
}
59
}
Copied!
As this example allows multiple users to play the dice game at the same time, a
mapping (address => Guess) is used to separately track everyone's choice of numbers and the block in which they placed their guess. In this way, you can make sure that every roll of the die is only affecting guesses that were placed at least 1 block in advance, and that further rolls of the die will not affect the outcome of past guesses.Take into account that this example implements an asynchronous workflow — calling
fulfillRandomness() right after getRandomNumber() will most likely cause the transaction to revert. Please allow 5-10 minutes for the randomization request to complete.Example 3: Random Bytes
In addition to random numbers, the Witnet randomness oracle can also generate random sequences of bytes. Namely, these have the
bytes32 type in Solidity:1
// SPDX-License-Identifier: MIT
2
pragma solidity >=0.7.0 <0.9.0;
3
4
import "witnet-solidity-bridge/contracts/interfaces/IWitnetRandomness.sol";
5
6
contract MyContract {
7
8
bytes32 public randomness;
9
uint256 public latestRandomizingBlock;
10
IWitnetRandomness immutable public witnet;
11
12
/// @param _witnetRandomness Address of the WitnetRandomness contract.
13
constructor (IWitnetRandomness _witnetRandomness) {
14
assert(address(_witnetRandomness) != address(0));
15
witnet = _witnetRandomness;
16
}
17
18
receive () external payable {}
19
20
function requestRandomness() external payable {
21
latestRandomizingBlock = block.number;
22
uint _usedFunds = witnet.randomize{ value: msg.value }();
23
if (_usedFunds < msg.value) {
24
payable(msg.sender).transfer(msg.value - _usedFunds);
25
}
26
}
27
28
function fetchRandomness() external {
29
assert(latestRandomizingBlock > 0);
30
randomness = witnet.getRandomnessAfter(latestRandomizingBlock);
31
}
32
33
}
Copied!
As you can see, this example is very similar to the Example 1 above. The
requestRandomness() function works the same as requestRandomNumber() above, but fetchRandomness() however uses the lower-level witnet.getRandomnessAfter() function to read the underlying random bytes instead of trying to derive a random integer from those:1
randomness = witnet.getRandomnessAfter(latestRandomizingBlock);
Copied!
Generating random bytes is specially interesting for many NFT use cases in which you need to assign attributes and traits at random to each of the item in a colllection. By sourcing 32 random bytes at once, you can use each of the bytes to affect the different traits that you want to assign.
Take into account that this example implements an asynchronous workflow — calling
fetchRandomness() right after requestRandomness() will most likely cause the transaction to revert. Please allow 5-10 minutes for the randomization request to complete.Example 4: Post a low-level hardcoded randomness request
1
pragma solidity ^0.8.0;
2
3
import "witnet-solidity-bridge/contracts/UsingWitnet.sol";
4
import "witnet-solidity-bridge/contracts/requests/WitnetRequest.sol";
5
6
import "@openzeppelin/contracts/access/Ownable.sol";
7
8
contract MyContract
9
is
10
Ownable,
11
UsingWitnet
12
{
13
/// @dev Low-level Witnet Data Request composed on construction.
14
IWitnetRequest public witnetRequest;
15
16
/// @dev Randomness value eventually fetched from the Witnet oracle.
17
bytes32 public witnetRandomness;
18
19
/// @dev Unique identifier for the latest request posted to the Witnet Request Board.
20
uint256 public witnetQueryId;
21
22
enum Status {
23
Playing,
24
Randomizing,
25
Awarding
26
}
27
28
modifier inStatus(Status _status) {
29
require(status() == _status, "bad mood");
30
}
31
32
constructor(WitnetRequestBoard _witnet)
33
UsingWitnet(_witnet)
34
{
35
// Compose low-level Witnet data request bytecode,
36
// that will be eventually posted to the Witnet side-chain
37
// when calling to _witnetPostRequest(witnetRequest)
38
witnetRequest = new WitnetRequest(
39
hex"0a0f120508021a01801a0210022202100b10e807180a200a2833308094ebdc03"
40
);
41
/// @dev Witnet Data Request decoded as:
42
///
43
/// {
44
/// "retrieve": [
45
/// {
46
/// "kind": "RNG",
47
/// "url": "",
48
/// "script": []
49
/// }
50
/// ],
51
/// "aggregate": {
52
/// "filters": [],
53
/// "reducer": 2
54
/// },
55
/// "tally": {
56
/// "filters": [],
57
/// "reducer": 11
58
/// }
59
/// }
60
///
61
}
62
63
/// @dev Calculate current status.
64
function status() public view returns (Status) {
65
if (witnetRandomness != bytes32(0)) {
66
return Status.Awarding;
67
} else if (witnetQueryId > 0) {
68
return Status.Randomizing;
69
} else {
70
return Status.Playing;
71
}
72
}
73
74
/// @dev Pass from 'Playing' to 'Randomizing' status
75
function stopPlaying()
76
external payable
77
onlyOwner
78
inStatus(Status.Playing)
79
{
80
// Use internal method inherited from UsingWitnet, as to send the low-level randomness
81
// request to the WitnetRequestBoard instance. `msg.value` needs to be high enough as
82
// to cover for `_witnetReward`
83
uint256 _witnetReward;
84
(witnetQueryId, _witnetReward) = _witnetPostRequest(witnetRequest);
85
86
// Transfer back unused funds:
87
if (msg.value > _witnetReward) {
88
payable(msg.sender).transfer(msg.value - _witnetReward);
89
}
90
}
91
92
/// @dev Pass from 'Randomizing' to either 'Awarding' or 'Playing' status, depending
93
/// @dev on whether the randomness request was solved, or reverted, respectively.
94
function startAwarding()
95
external
96
inStatus(Status.Randomizing)
97
{
98
uint _queryId = witnetQueryId;
99
100
// Use internal method inherited from UsingWitnet, as to check whether the randomness
101
// request has already been reported:
102
require(_witnetCheckResultAvailability(_queryId), "not yet reported");
103
104
// Low-level interaction with the WitnetRequestBoard as to deserialize the result,
105
// and check whether the randomness request failed or succeeded:
106
Witnet.Result memory _result = witnet.readResponseResult(_queryId);
107
if (_result.success) {
108
witnetRandomness = witnet.asBytes32(_result);
109
} else {
110
// step back to 'Playing' status:
111
witnetQueryId = 0;
112
}
113
}
114
115
/// ...
116
}
Copied!
Example 5: Clone a pre-deployed WitnetRequestRandomness contract
1
contract MyContract {
2
WitnetRequestRandomness public witnetRequest;
3
contructor(IWitnetRandomness _witnet) {
4
witnetRequest = _witnet.witnetRandomnessRequest();
5
// transfer request ownership to deployer:
6
witnetRequest.transferOwnership(msg.sender);
7
}
8
// ...
9
}
Copied!
Last modified 1mo ago