Skip to content

entropy_cr_random

Behaviour

Section titled “Behaviour”
  • Writes random bytes to the buffer pointed to by write_ptr, derived from the consensus entropy visible to this Hook execution.
  • Writes exactly write_len bytes and returns write_len on success. Internally, entropy is generated in 32-byte blocks and rounded up as needed.
  • write_len must be between 1 and 512 bytes.
  • The hook must specify a minimum entropy tier (min_tier). If the visible entropy is missing, stale, or below it, the call fails with TOO_LITTLE_ENTROPY.
  • The hook must specify which later strong Hooks may run after the draw (flags), exactly as for entropy_cr_dice(). With flags = 0, a strong Hook can only draw if no other strong Hook can run after it in the transaction; otherwise the call fails with LATER_STRONG_HOOK.
  • A failed call leaves the buffer unchanged.

Definition

Section titled “Definition”
int64_t entropy_cr_random (
    uint32_t write_ptr,
    uint32_t write_len,
    uint32_t min_tier,
    uint32_t flags
);

Hooks compiled against the earlier three-argument entropy_cr_random(write_ptr, write_len, min_tier) must be recompiled and reinstalled. The runtime supplies no default for the missing flags argument; the strict policy is an explicit final 0.

Example

Section titled “Example”

32 random bytes with validator-quorum entropy that no later strong Hook can veto:

uint8_t buf[32];
int64_t result = entropy_cr_random(SBUF(buf), 3, 0);
if (result == LATER_STRONG_HOOK)
    rollback(SBUF("A later Hook could veto this draw"), 1);
if (result < 0)
    rollback(SBUF("No entropy available"), 1);

Alternatively, 64 bytes for a cosmetic shuffle that later Hooks on the same account may veto:

uint8_t seed[64];
int64_t seed_written = entropy_cr_random(
    SBUF(seed), 1, ENTROPY_ALLOW_SAME_ACCOUNT_STRONG_VETO);
if (seed_written != sizeof(seed))
    rollback(SBUF("No entropy available"), 1);

These are alternative policies, not a fallback sequence. Choose the policy the application needs for each draw.

Parameters

Section titled “Parameters”
NameTypeDescription
write_ptruint32_tPointer to the output buffer.
write_lenuint32_tLength of the output buffer. Must be between 1 and 512 bytes.
min_tieruint32_tMinimum entropy tier required: 1 = consensus fallback, 2 = participant aligned, 3 = validator quorum, 4 = validator full (reveals from every active validator).
flagsuint32_tWhich strong Hooks may run after this draw: 0 = none; ENTROPY_ALLOW_SAME_ACCOUNT_STRONG_VETO (2) = Hooks installed on this Hook’s own account; ENTROPY_ALLOW_ANY_STRONG_VETO (1) = any. Setting both bits means any. Other bits are invalid. See Later strong Hooks.

Return Code

Section titled “Return Code”
TypeDescription
int64_tThe number of bytes written on success, equal to write_len. If negative, one of the errors below, checked in the order listed.
ErrorMeaning
TOO_SMALLwrite_len is 0.
TOO_BIGwrite_len is greater than 512.
OUT_OF_BOUNDSPointers/lengths specified outside of hook memory.
INVALID_ARGUMENTmin_tier is outside 1..4, or flags has an undefined bit set.
LATER_STRONG_HOOKA strong Hook that flags does not allow can run later in this transaction.
TOO_LITTLE_ENTROPYEntropy is unavailable, stale, or below min_tier.

Determinism

Section titled “Determinism”

Each successful call to entropy_cr_random() uses different derivation input, even within the same hook execution. The per-call input includes the entropy digest, ledger sequence, transaction ID, originating account, hook account, hook hash, chain position, strong/weak execution flag, callback/direct dispatch flag, and a call counter that advances on each successful draw. Internally, 32-byte blocks are generated via sha512Half and then chained (sha512Half(previous_block)) for additional blocks. This ensures deterministic replay.

Section titled “Related”