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.
Final execution sees the current ledger’s successfully applied ConsensusEntropy pseudo-transaction. Open-ledger previews, including simulate, see the previous ledger’s. See Speculative Execution.
Advisory metadata only: a status result is not a freshness guarantee or proof that a later draw will be admitted.
Takes no arguments and writes nothing to hook memory.
Performs no draw and does not depend on any draw’s flags.
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);

Then apply one participation policy before drawing. These are alternatives, not a sequence; pick the one your application needs:

// Policy A: tolerate a single absent validator
if (denominator - count > 1)
    rollback(SBUF("Too many absentees"), 1);
int64_t roll = entropy_cr_dice(6, 3, 0);

// Policy B: 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, 0);

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 input is visible to this execution. `INTERNAL_ERROR` — the entropy input is malformed.