Random number generation

Random number generation for Tact smart contracts.

Common

random

fun random(min: Int, max: Int): Int;

Generates and returns a new pseudo-random unsigned Int value x in the provided semi-closed interval: min $≤$ x $<$ max, or min $≥$ x $>$ max if both min and max are negative. Note that the max value is never included in the interval.

Usage examples:

random(42, 43); // 42, always
random(0, 42);  // 0-41, but never 42

randomInt

fun randomInt(): Int;

Generates and returns a new pseudo-random unsigned 256-bit Int value x.

The algorithm works as follows: first, the sha512(r) is computed. There, r is an old value of the random seed, which is taken as a 32-byte array constructed from the big-endian representation of an unsigned 256-bit Int. The first 32 bytes of this hash are stored as the new value r' of the random seed, and the remaining 32 bytes are returned as the next random value x.

Usage example:

let allYourRandomBelongToUs: Int = randomInt(); // ???, it's random :)

Advanced

Various niche, dangerous, or unstable features which can produce unexpected results and are meant to be used by more experienced users.

getSeed

Available since Tact 1.6

fun getSeed(): Int;

Generates and returns an unsigned 256-bit Int seed for the random number generator. The resulting seed is commonly used with the setSeed() and nativeRandomize() functions.

Usage example:

let seed: Int = getSeed();
setSeed(seed); // From now on, the results of the pseudorandom number generator
               // are completely determined by the seed, which can be handy in tests,
               // but must not be used in production code!

setSeed

Available since Tact 1.6

fun setSeed(seed: Int);

Sets the seed of the random number generator to the unsigned 256-bit Int seed, which can be obtained with the getSeed() function.

Attempts to specify a negative value for seed throw an exception with exit code 5: Integer out of expected range.

Usage example:

let seed: Int = getSeed();
setSeed(seed); // From now on, the results of the pseudorandom number generator
               // are completely determined by the seed, which can be handy in tests,
               // but must not be used in production code!

nativePrepareRandom

fun nativePrepareRandom();

Prepares the random number generator by using nativeRandomizeLt(). Automatically called by the randomInt() and random() functions.

Usage example:

nativePrepareRandom(); // Prepare the RNG
// ... do your random things ...

nativeRandomize

fun nativeRandomize(x: Int);

Randomizes the pseudorandom number generator with the specified unsigned 256-bit Int x by mixing it with the current seed. The new seed is the unsigned 256-bit Int value of the SHA-256 hash of the concatenated old seed and x in their 32-byte strings big-endian representation.

Attempts to specify a negative value for x throw an exception with exit code 5: Integer out of expected range.

Usage example:

nativeRandomize(42);        // Now, random numbers are less predictable
let idk: Int = randomInt(); // ???, it's random,
                            // but the seed was adjusted deterministically!

nativeRandomizeLt

fun nativeRandomizeLt();

Randomizes the random number generator with the logical time of the current transaction. Equivalent to calling nativeRandomize(curLt()).

Usage example:

nativeRandomizeLt();        // Now, random numbers are unpredictable for users,
                            // but still may be affected by validators or collators
                            // as they determine the seed of the current block.
let idk: Int = randomInt(); // ???, it's random!

nativeRandom

fun nativeRandom(): Int;

Generates and returns a 256-bit random number just like randomInt() but does not initialize the random generator with nativePrepareRandom() beforehand.

nativeRandomInterval

fun nativeRandomInterval(max: Int): Int;

Generates and returns a 256-bit random number in the range from 0 to max, similar to random(), but doesn’t initialize the random generator with nativePrepareRandom() beforehand.