dice

Summary. Return a uniformly distributed integer in the half-open range [0, sides). This API is provided by the featureRNG amendment.

Signature.

int64_t dice(uint32_t sides);

Parameters.

Name	Type	Description
sides	uint32_t	Number of outcomes. Must be non-zero.

Return value. On success, returns a value from 0 through sides - 1. Errors:

Code	Value	Cause
INVALID_ARGUMENT	-7	sides == 0.
TOO_LITTLE_ENTROPY	-46	The current ledger has no usable random seed, is not sufficiently seeded, or has no qualifying entropy contribution.
TOO_MANY_NONCES	-12	More than 256 RNG draws in one Hook execution.

Common failure patterns.

• Passing sides == 0 → INVALID_ARGUMENT.
• Drawing in a ledger that has no usable entropy → TOO_LITTLE_ENTROPY; treat a negative return as "no randomness available" rather than as a value.
• Drawing more than 256 times in one execution → TOO_MANY_NONCES.

Caveats / notes.

• Requires the featureRNG amendment; without it the function is not available.
• Every successful call consumes one of the 256 RNG draws shared with util_random.
• The draw limit reuses the existing TOO_MANY_NONCES return code.

Minimal example.

int64_t roll = dice(6);
if (roll < 0)
    rollback(SBUF("random draw unavailable"), 1);

Related APIs. util_random returns random bytes instead of an integer.