Skip to content

entropy_cr_dice

Behaviour

Returns a random integer in the range [0, sides) derived from the current ledger’s consensus entropy.
The hook must specify a minimum entropy tier (min_tier). If the current ledger’s entropy is below it, the call fails with TOO_LITTLE_ENTROPY.

Definition

int64_t entropy_cr_dice (
    uint32_t sides,
    uint32_t min_tier
);

Example

// Roll a d6, require validator-quorum entropy
int64_t roll = entropy_cr_dice(6, 3);
if (roll < 0)
    rollback(SBUF("No entropy available"), 1);

// Roll a d100, accept any valid tier (including consensus fallback)
int64_t percent = entropy_cr_dice(100, 1);
if (percent < 0)
    rollback(SBUF("No entropy available"), 1);

Parameters

Name	Type	Description
`sides`	uint32_t	Number of sides. Result is in `[0, sides)`.
`min_tier`	uint32_t	Minimum entropy tier required: `1` = consensus fallback, `2` = participant aligned, `3` = validator quorum, `4` = validator full (reveals from every active validator).

Return Code

Type	Description
int64_t	A random integer in `[0, sides)` on success. If negative, an error: `INVALID_ARGUMENT` — `sides` is `0` or `min_tier` is outside `1..4`. `TOO_LITTLE_ENTROPY` — entropy is unavailable, stale, or below the specified `min_tier`. `INTERNAL_ERROR` — the entropy API returned an unexpected byte count.

Determinism

Each call to entropy_cr_dice() draws fresh entropy, even within the same hook execution. The reduced result can still repeat, especially for small sides values. The randomness is derived from:

Ledger sequence, transaction ID, hook hash, account, chain position
Originating account, strong/weak execution flag, and callback/direct dispatch flag
The consensus entropy digest
An internal call counter that increments per call

This ensures deterministic replay (same inputs → same outputs) while using different derivation input per call.