VRF Randomness

TRTH uses Chainlink VRF v2.5 so that Bonus multipliers and King selection are not opaque off-chain rolls. Randomness is requested on-chain, fulfilled by the VRF coordinator, and consumed by protocol logic through a narrow adapter boundary.

Why VRF matters

Bonus needs a high-entropy seed to define a random multiplier window each epoch. King needs unpredictable selection among eligible holders. A centralized server could inject bias or censor outcomes; Chainlink VRF provides verifiable randomness tied to on-chain proofs.

Contracts and adapter pattern

The typical call chain is:

EpochRewardsV1 → ChainlinkVrfWordAdapter → Chainlink VRF v2.5 Coordinator → callback → fulfillRandomness()

• EpochRewardsV1 owns epoch accounting and knows when a new random word is needed.
• ChainlinkVrfWordAdapter isolates VRF subscription, key hash, callback gas, and request ID plumbing from the rest of the rewards logic.
• The Coordinator is the Chainlink VRF v2.5 contract that validates proofs and delivers random words.

This adapter pattern keeps rewards code readable: domain rules stay in EpochRewards, while VRF-specific details stay in the adapter.

Request lifecycle

1. Trigger: The protocol (often a keeper or permissioned cron) observes that an epoch needs randomness — e.g., Bonus or King settlement for a completed window.
2. Request: EpochRewardsV1 asks the adapter to requestRandomWords (or equivalent) on the Coordinator, paying LINK (or the configured billing path) from the subscription.
3. Pending state: The request is asynchronous. Callbacks arrive in a later transaction, possibly minutes later depending on network and VRF load.

Fulfillment lifecycle

4. Fulfill: The Coordinator calls the adapter’s callback with random words and proof validation performed by Chainlink infrastructure.
5. fulfillRandomness: The adapter forwards the word(s) to EpochRewardsV1, which splits the entropy:
   • Bonus seed: derives parameters for the random multiplier window for eligible holders.
   • King selection: maps entropy to one eligible holder for the 10% King slice (subject to eligibility and lag rules described in Epochs & Rewards).

Note

Bonus and King use the same VRF trust model: if the word is honest, downstream mapping is deterministic and publicly auditable.

Operational expectations

VRF introduces latency and LINK economics: requests can fail or stall if subscriptions are underfunded or limits are misconfigured. Ops must monitor subscription balance and fulfillment events.

Tip

When reading logs, trace RandomWordsRequested → RandomWordsFulfilled (names vary by version) on the Coordinator, then watch the adapter and EpochRewards callbacks to confirm end-to-end delivery.

In short: EpochRewards orchestrates when randomness is needed; Chainlink VRF v2.5 provides verifiable words; fulfillRandomness binds those words to Bonus and King outcomes.