dice

Concepts

Random ledger object

Behaviour

C

(Requires the RNG amendment.)

• Returns a uniformly distributed random integer in the range [0, sides).
• Uses rejection sampling, so every face is exactly equally likely (no modulo bias).
• The value is 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 util_random.
• 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 dice (
    uint32_t sides
);

Example

C

int64_t roll = dice(6);              // 0..5
if (roll < 0)
    rollback(SBUF("RNG unavailable"), roll);

accept(SBUF("rolled"), roll + 1);    // 1..6

Parameters

C

Name	Type	Description
sides	uint32_t	The number of possible outcomes. Must be at least 1.

Return Code

C

Type	Description
int64_t	A random integer in the range [0, sides). 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 util_random). INVALID_ARGUMENT - sides is 0.

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.