On-chain randomness

Advanced

Concept

The Internet Computer provides a secure and verifiable way to generate random numbers directly within canisters. This functionality is exposed through the raw_rand method offered by the management canister and the Motoko Random module.

The method takes no input and returns 32 pseudo-random bytes to the caller.

How it works

Behind the scenes, ICP utilizes a Verifiable Random Function (VRF) to generate randomness.

During each round, the VRF is evaluated with the current input being the number of the round. This process produces a fresh set of random bytes.

These bytes become the seed for a pseudorandom number generator (PRNG) called random tape. The random tape is built using chain-key cryptography and is used to create unique random values for each canister that requested randomness in the previous round.

raw_rand calls only use the random tape from the next round. This ensures that no one can exploit knowledge of the current round's randomness to predict future outputs. To learn more about the execution layer of ICP, refer to the execution layer documentation.

To learn more about the technical details of randomness on ICP, watch the Community Conversations video on randomness.

How to use

Developers can directly access randomness through the raw_rand method in the management canister. See the examples below.

Motoko

actor {
  let SubnetManager : actor {
    raw_rand() : async Blob;
  } = actor "aaaaa-aa";

  public func random_bytes() : async Blob {
    let bytes = await SubnetManager.raw_rand();
    return bytes;
  };
};

In addition to the raw_rand method, Motoko offers a Random module for generating random numbers.

Rust

let (randomBytes,): (Vec<u8>,) = ic_cdk::api::call(Principal.management_canister(), "raw_rand", ()).await?;

TypeScriptBeta

import { call, IDL, update } from 'azle';

export default class {
    @update([], IDL.Vec(IDL.Nat8))
    async randomBytes(): Promise<Uint8Array> {
        const bytes: Uint8Array = await call('aaaaa-aa', 'raw_rand', {
            returnIdlType: IDL.Vec(IDL.Nat8)
        });

        return bytes;
    }
}

PythonBeta

from kybra import Async, blob, CallResult, match, update, Variant
from kybra.canisters.management import management_canister


class RandomBytesResult(Variant, total=False):
    Ok: blob
    Err: str


@update
def random_bytes() -> Async[RandomBytesResult]:
    call_result: CallResult[blob] = yield management_canister.raw_rand()

    return match(
        call_result, {"Ok": lambda ok: {"Ok": ok}, "Err": lambda err: {"Err": err}}
    )