Skip to main content

Module sui::random

This module provides functionality for generating secure randomness.

use std::ascii;
use std::bcs;
use std::option;
use std::string;
use std::vector;
use sui::address;
use sui::dynamic_field;
use sui::hex;
use sui::hmac;
use sui::object;
use sui::party;
use sui::transfer;
use sui::tx_context;
use sui::vec_map;
use sui::versioned;

Struct Random​

Singleton shared object which stores the global randomness state.
The actual state is stored in a versioned inner field.

public struct Random has key
Click to open
Fields

Struct RandomInner​

public struct RandomInner has store
Click to open
Fields
version: u64
epoch: u64
randomness_round: u64
random_bytes: vector<u8>

Struct RandomGenerator​

Unique randomness generator, derived from the global randomness.

public struct RandomGenerator has drop
Click to open
Fields
seed: vector<u8>
counter: u16
buffer: vector<u8>

Constants​

const ENotSystemAddress: u64 = 0;

const EWrongInnerVersion: u64 = 1;

const EInvalidRandomnessUpdate: u64 = 2;

const EInvalidRange: u64 = 3;

const EInvalidLength: u64 = 4;

const CURRENT_VERSION: u64 = 1;

const RAND_OUTPUT_LEN: u16 = 32;

const U16_MAX: u64 = 65535;

Function create​

Create and share the Random object. This function is called exactly once, when the Random object is first created.
Can only be called by genesis or change_epoch transactions.

fun create(ctx: &mut sui::tx_context::TxContext)

Function load_inner_mut​

fun load_inner_mut(self: &mut sui::random::Random): &mut sui::random::RandomInner

Function load_inner​

fun load_inner(self: &sui::random::Random): &sui::random::RandomInner

Function update_randomness_state​

Record new randomness. Called when executing the RandomnessStateUpdate system transaction.

fun update_randomness_state(self: &mut sui::random::Random, new_round: u64, new_bytes: vector<u8>, ctx: &sui::tx_context::TxContext)

Function new_generator​

Create a generator. Can be used to derive up to MAX_U16 * 32 random bytes.

Using randomness can be error-prone if you don't observe the subtleties in its correct use, for example, randomness dependent code might be exploitable to attacks that carefully set the gas budget in a way that breaks security. For more information, see: https://docs.sui.io/guides/developer/advanced/randomness-onchain

public fun new_generator(r: &sui::random::Random, ctx: &mut sui::tx_context::TxContext): sui::random::RandomGenerator

Function derive_next_block​

Get the next block of 32 random bytes.

fun derive_next_block(g: &mut sui::random::RandomGenerator): vector<u8>

Function generate_bytes​

Generate n random bytes.

public fun generate_bytes(g: &mut sui::random::RandomGenerator, num_of_bytes: u16): vector<u8>

Macro function uint_from_bytes​

macro fun uint_from_bytes<$T: drop>($g: &mut sui::random::RandomGenerator, $num_of_bytes: u8): $T

Function generate_u256​

Generate a u256.

public fun generate_u256(g: &mut sui::random::RandomGenerator): u256

Function generate_u128​

Generate a u128.

public fun generate_u128(g: &mut sui::random::RandomGenerator): u128

Function generate_u64​

Generate a u64.

public fun generate_u64(g: &mut sui::random::RandomGenerator): u64

Function generate_u32​

Generate a u32.

public fun generate_u32(g: &mut sui::random::RandomGenerator): u32

Function generate_u16​

Generate a u16.

public fun generate_u16(g: &mut sui::random::RandomGenerator): u16

Function generate_u8​

Generate a u8.

public fun generate_u8(g: &mut sui::random::RandomGenerator): u8

Function generate_bool​

Generate a boolean.

public fun generate_bool(g: &mut sui::random::RandomGenerator): bool

Macro function uint_in_range​

Helper macro to generate a random uint in [min, max] using a random number with num_of_bytes bytes.
Assumes that the caller verified the inputs, and uses num_of_bytes to control the bias (e.g., 8 bytes larger than the actual type used by the caller function to limit the bias by 2^{-64}).

macro fun uint_in_range<$T: drop>($g: &mut sui::random::RandomGenerator, $min: $T, $max: $T, $num_of_bytes: u8): $T

Function generate_u128_in_range​

Generate a random u128 in [min, max] (with a bias of 2^{-64}).

public fun generate_u128_in_range(g: &mut sui::random::RandomGenerator, min: u128, max: u128): u128

Function generate_u64_in_range​

public fun generate_u64_in_range(g: &mut sui::random::RandomGenerator, min: u64, max: u64): u64

Function generate_u32_in_range​

Generate a random u32 in [min, max] (with a bias of 2^{-64}).

public fun generate_u32_in_range(g: &mut sui::random::RandomGenerator, min: u32, max: u32): u32

Function generate_u16_in_range​

Generate a random u16 in [min, max] (with a bias of 2^{-64}).

public fun generate_u16_in_range(g: &mut sui::random::RandomGenerator, min: u16, max: u16): u16

Function generate_u8_in_range​

Generate a random u8 in [min, max] (with a bias of 2^{-64}).

public fun generate_u8_in_range(g: &mut sui::random::RandomGenerator, min: u8, max: u8): u8

Function shuffle​

Shuffle a vector using the random generator (Fisher–Yates/Knuth shuffle).

public fun shuffle<T>(g: &mut sui::random::RandomGenerator, v: &mut vector<T>)