Random

type State = { var bytes : [Nat8]; var index : Nat; var bits : Nat8; var bitMask : Nat8 }

type SeedState = { random : State; prng : PRNG.State }

public func blob() : async Blob

public func emptyState() : State

Initializes a random number generator state. This is used to create a Random or AsyncRandom instance with a specific state. The state is empty, but it can be reused after upgrading the canister.

Example:

import Random "mo:core/Random";

persistent actor {
  let state = Random.emptyState();
  transient let random = Random.cryptoFromState(state);

  public func main() : async () {
    let coin = await* random.bool(); // true or false
  }
}

public func seedState(seed : Nat64) : SeedState

Initializes a pseudo-random number generator state with a 64-bit seed. This is used to create a Random instance with a specific seed. The seed is used to initialize the PRNG state.

Example:

import Random "mo:core/Random";

persistent actor {
  let state = Random.seedState(123);
  transient let random = Random.seedFromState(state);

  public func main() : async () {
    let coin = random.bool(); // true or false
  }
}

public func seed(seed : Nat64) : Random

Creates a pseudo-random number generator from a 64-bit seed. The seed is used to initialize the PRNG state. This is suitable for simulations and testing, but not for cryptographic purposes.

Example:

motoko include=import
let random = Random.seed(123);
let coin = random.bool(); // true or false

public func seedFromState(state : SeedState) : Random

Creates a pseudo-random number generator with the given state. This provides statistical randomness suitable for simulations and testing, but should not be used for cryptographic purposes.

Example:

import Random "mo:core/Random";

persistent actor {
  let state = Random.seedState(123);
  transient let random = Random.seedFromState(state);

  public func main() : async () {
    let coin = random.bool(); // true or false
  }
}

public func crypto() : AsyncRandom

Initializes a cryptographic random number generator using entropy from the ICP management canister.

Example:

import Random "mo:core/Random";

persistent actor {
  transient let random = Random.crypto();

  public func main() : async () {
    let coin = await* random.bool(); // true or false
  }
}

public func cryptoFromState(state : State) : AsyncRandom

Creates a random number generator suitable for cryptography using entropy from the ICP management canister. Initializing from a state makes it possible to reuse entropy after upgrading the canister.

Example:

import Random "mo:core/Random";

persistent actor {
  let state = Random.emptyState();
  transient let random = Random.cryptoFromState(state);

  func example() : async () {
    let coin = await* random.bool(); // true or false
  }
}

class Random(state : State, generator : () -> Blob)

motoko include=import
let random = Random.seed(42);
let coin = random.bool(); // true or false

motoko include=import
let random = Random.seed(42);
let byte = random.nat8(); // 0 to 255

motoko include=import
let random = Random.seed(42);
let number = random.nat64(); // 0 to 18446744073709551615

motoko include=import
let random = Random.seed(42);
let dice = random.nat64Range(1, 7); // 1 to 6

motoko include=import
let random = Random.seed(42);
let index = random.natRange(0, 10); // 0 to 9

class AsyncRandom(state : State, generator : () -> async* Blob)