Skip to content

entropy_cr_status

Behaviour

Returns the consensus entropy metadata visible to the current Hook execution, packed into a single non-negative int64_t: entropy tier, validator reveal count, and participation denominator.
Takes no arguments and writes nothing to hook memory.
Exposes metadata only. The entropy digest itself is never exposed to hooks — randomness is only drawn through entropy_cr_dice() and entropy_cr_random().

Definition

int64_t entropy_cr_status (void);

Packed Return Layout

Bits	Value	Extraction macro
32..39	Entropy tier (`1..4`)	`ENTROPY_TIER(status)`
16..31	Validator reveal count	`ENTROPY_COUNT(status)`
0..15	Participation denominator	`ENTROPY_DENOMINATOR(status)`

The ENTROPY_TIER, ENTROPY_COUNT, and ENTROPY_DENOMINATOR macros ship with the hook API headers. Every valid packed status is non-negative; check for a negative error before applying the macros.

Example

int64_t status = entropy_cr_status();
if (status < 0)
    rollback(SBUF("Entropy unavailable"), 1);

uint32_t tier = ENTROPY_TIER(status);
uint32_t count = ENTROPY_COUNT(status);
uint32_t denominator = ENTROPY_DENOMINATOR(status);

// Classify the tier before any count/denominator arithmetic:
// consensus fallback is tier 1 with count = denominator = 0.
if (tier < 3)
    rollback(SBUF("Validator entropy required"), 1);

// Example participation policies:
// tolerate a single absent validator
if (denominator - count > 1)
    rollback(SBUF("Too many absentees"), 1);

// or: require at least 4/5 participation (widened arithmetic)
if ((uint64_t)5 * count < (uint64_t)4 * denominator)
    rollback(SBUF("Insufficient participation"), 1);

int64_t roll = entropy_cr_dice(6, 3);

Return Code

Type	Description
int64_t	A non-negative packed status on success (see layout above). If negative, an error: `DOESNT_EXIST` — no consensus entropy entry is available. `INTERNAL_ERROR` — the entropy entry is malformed.