ConsensusEntropy

[Source]

(Added by the ConsensusEntropy amendment.)

ConsensusEntropy is a pseudo-transaction that carries a ledger’s entropy digest and the participation metadata produced by the validator commit/reveal scheme. When a ledger is built, it is applied before every other transaction, so it is the entropy input for draws in that ledger’s final execution, subject to each call’s min_tier and flags.

The entropy is not stored in ledger state. The pseudo-transaction in the ledger’s transaction set is its only record. A ledger contains at most one successful ConsensusEntropy pseudo-transaction; a second one in the same ledger fails.

Hooks consume this entropy through the entropy_cr_dice() and entropy_cr_random() hook API functions, and read the participation metadata (tier, reveal count, denominator) through entropy_cr_status(). Hooks cannot load the pseudo-transaction itself: slot_set with its transaction ID returns NOT_AUTHORIZED. Its contents are public once the ledger is published.

Example

{
  "TransactionType": "ConsensusEntropy",
  "Account": "rrrrrrrrrrrrrrrrrrrrrhoLvTp",
  "Fee": "0",
  "Sequence": 0,
  "SigningPubKey": "",
  "LedgerSequence": 12345678,
  "Digest": "[ENTROPY_DIGEST]",
  "EntropyCount": 20,
  "EntropyDenominator": 20,
  "EntropyContributors": "FFFF0F",
  "EntropyTier": 4
}

Fields

In addition to the special values for pseudo-transaction common fields, ConsensusEntropy uses the following fields:

Field	JSON Type	Internal Type	Description
LedgerSequence	Number	UInt32	The ledger this entropy was produced for. The pseudo-transaction only applies in that ledger.
Digest	String	Hash256	The entropy digest for this ledger.
EntropyCount	Number	UInt16	Number of validator reveals used to derive the digest. 0 for consensus fallback.
EntropyDenominator	Number	UInt16	Number of active validators in the parent-ledger view (after Negative UNL) that the reveals were drawn from — the denominator for the EntropyCount participation fraction (EntropyCount / EntropyDenominator). 0 for consensus fallback.
EntropyContributors	String	VL	Byte bitmask of active validators whose reveals contributed to the digest. Bits are ordered by the canonical parent-ledger active validator view after Negative UNL, least significant bit first within each byte. Empty for consensus fallback.
EntropyTier	Number	UInt8	The entropy tier (see below).

Entropy Tiers

Every RNG-enabled ledger carries a tiered entropy input. The tier indicates the strength of the randomness source:

Tier	Value	Description
validator_full	4	Reveals from every active validator in the ledger-anchored view (EntropyCount == EntropyDenominator, with a non-empty view). Any missing active validator downgrades the tier, so requiring it fails closed on selective withholding — at the cost of availability (a single offline validator prevents it).
validator_quorum	3	The accepted reveal count reaches 80% (rounded up) of the effective validator view.
participant_aligned	2	The accepted reveal count reaches the participant floor over the original (pre-NegativeUNL) view, floor((n + floor(n / 5)) / 2) + 1, but not the 80% quorum.
consensus_fallback	1	Deterministic public-input fallback derived from sha512Half(HashPrefix::entropyFallback, parentLedgerHash, buildTxSetHash, seq), where buildTxSetHash is the sanitized pre-injection live-build set hash. Grindable.

Caution

Tier 1 (consensus_fallback) entropy is deterministic and derivable from public inputs. It is grindable by transaction submitters, especially on quiet ledgers. Hooks handling high-value outcomes (lotteries, games) should require at least min_tier=3 (validator quorum) in their entropy_cr_dice() / entropy_cr_random() calls — or min_tier=4 (validator_full) to additionally reject any round in which an active validator withheld its reveal.

How Entropy is Produced

Each consensus round follows a three-phase pipeline:

1. Commit: proposing validators generate a secret and broadcast sha512Half(secret, pubKey, seq) as a commitment on their first proposal
2. Reveal: after the transaction set converges, validators broadcast their secret
3. Inject: pairs are sorted by signing-key bytes and then reveal digest. Each signing key is encoded in canonical variable-length form (including its length prefix), followed by the 256-bit reveal; sha512Half of the concatenated pairs becomes the Digest. EntropyTier, EntropyCount, EntropyDenominator, and EntropyContributors label the accepted result.

EntropyTier labels the accepted reveal count. It is not a separate certificate of how many validators advertised the same entropy set: that alignment is the round’s proceed gate, which requires the lower of the 80% quorum and the participant floor. If the accepted count passes none of the tier tests, below both the quorum and the participant floor, a consensus_fallback digest is injected instead, with count and denominator 0 and an empty bitmap. Under NegativeUNL the quorum can be lower than the participant floor, so a count under the floor can still be validator_quorum. RNG-enabled ledgers always receive either validator-derived entropy or a consensus-fallback digest.

Validator tiers require the round’s validator view to come from the parent ledger’s UNLReport. A non-standalone node whose parent ledger has no UNLReport always produces consensus_fallback, even if its locally configured trust set and reveal count would otherwise qualify.

EntropyContributors is accountability metadata. It records who contributed to the accepted result, but entropy_cr_dice() and entropy_cr_random() derive per-call randomness from the digest and their own domain-separated call inputs.

Which Executions See It

• Final execution of a ledger sees only that ledger’s successfully applied ConsensusEntropy pseudo-transaction. Every normally built RNG-enabled ledger has one, carrying validator entropy or a fallback derived for that ledger. Only if it is exceptionally missing, for example because it failed to apply, does entropy_cr_status() return DOESNT_EXIST and an otherwise admissible draw return TOO_LITTLE_ENTROPY; argument and composition errors are reported first, and no earlier ledger’s entropy is used. A present fallback can still fail a draw whose min_tier is above 1.
• Open-ledger previews, including simulate, see the previous ledger’s pseudo-transaction, so preview results can differ from final results. See Speculative Execution.
• A server that restarts, or loads a ledger from storage, recovers the entropy from the ledger’s transaction set, accepting only a successfully applied pseudo-transaction for that ledger’s sequence.

Standalone Mode

In standalone mode (single-node testing), synthetic deterministic entropy is injected:

sha512Half("standalone-entropy", seq)

This allows hooks using entropy_cr_dice() / entropy_cr_random() to function during development without a validator network.

Standalone mode labels this synthetic entropy as tier 4 (validator_full) with count 20, denominator 20, and a contributor bitmap with the first 20 validators marked. This lets min_tier=4 hooks pass locally. Use it for local development only; real network ledgers can fall back to tier 1 when validator entropy is unavailable.

Related

• Consensus Entropy overview
• entropy_cr_dice()
• entropy_cr_random()
• entropy_cr_status()