util_random

Concepts

Random ledger object

Behaviour

C

(Requires the RNG amendment.)

• Writes write_len (1–512) random bytes to write_ptr.
• The bytes are derived from the ledger’s consensus random seed, mixed with the transaction ID, Hook account, Hook hash, chain position, strong/weak execution, callback flag and the WebAssembly parameter. Two executions never receive the same output.
• Each Hook execution can draw at most 256 times. The limit is shared with dice.
• The function is only on the Hook import whitelist once the RNG amendment is enabled, so a Hook that imports it cannot be installed before then.

Definition

C

int64_t util_random (
    uint32_t write_ptr,
    uint32_t write_len
);

Example

C

uint8_t seed[32];
if (util_random(SBUF(seed)) != 32)
    rollback(SBUF("RNG unavailable"), 1);

Parameters

C

Name	Type	Description
write_ptr	uint32_t	Pointer to a buffer to write the random bytes into.
write_len	uint32_t	Number of random bytes to write. Must be between 1 and 512.

Return Code

C

Type	Description
int64_t	The number of bytes written. If negative, an error: TOO_LITTLE_ENTROPY - No seed exists for this ledger, or fewer than 80% of the UNLReport contributed to it. TOO_MANY_NONCES - The Hook has already drawn 256 times in this execution (shared with dice). TOO_SMALL - write_len is 0. TOO_BIG - write_len is greater than 512. OUT_OF_BOUNDS - The write buffer is outside Hook memory.

Notes

• Draws are never undone. If the transaction fails with a tec code (including tecHOOK_REJECTED) after a Hook drew random numbers, the RNG state still advances. A rollback cannot be used to “re-roll”.
• Open ledger is only a preview. While a transaction is applied to the open ledger, draws may use the previous ledger’s seed. The authoritative result is decided when the ledger closes, so a Hook’s outcome in the open ledger may differ from its validated outcome.
• Auditability. The validated metadata of a transaction whose Hooks drew random numbers contains a RandomData field. It holds the RNG state seen by the transaction’s first draw, and every value its Hooks received is derived from it.