VRF Consumer

A VRF Consumer operates on a two-step, asynchronous request-response pattern. The consumer contract first calls the VRF Provider's requestRandomness function, which returns a unique requestId. The provider later fulfills the request by calling the consumer's fulfillRandomWords callback function with the generated random numbers, identified by the same requestId.

• Key Flow: Request → Wait for Fulfillment → Receive Result.
• Asynchronous: The consumer must be designed to handle the delay between request and fulfillment.

The core logic of a VRF Consumer resides in its fulfillRandomWords function, which is a callback that the VRF Provider invokes. This function must:

• Be external and virtual/override.
• Accept the requestId and an array of random numbers (uint256[] memory randomWords) as parameters.
• Contain the application logic that uses the verified random numbers (e.g., selecting a winner, minting an NFT with random traits).
• Implement access control, often using the onlyVRFCoordinator modifier to ensure only the authorized provider can call it.

To manage multiple concurrent or sequential randomness requests, a VRF Consumer must track requestIds. This is critical because the fulfillment callback is asynchronous and the consumer may have multiple pending requests.

• Mapping Storage: Consumers typically use a mapping (e.g., mapping(uint256 => RequestStatus)) to store the state of each request.
• State Management: The mapping tracks if a request is PENDING, FULFILLED, or contains the resulting random words.
• Prevents Replay Attacks: The requestId ensures that a fulfillment can only be applied to the specific, original request.

Modern VRF systems (e.g., Chainlink VRF v2) use a subscription model. The consumer contract does not pay per request. Instead, it must be funded via a subscription account managed off-chain.

• Consumer Registration: The consumer's address is added to a subscription that holds LINK tokens.
• Gas Payment: The subscription owner pays for the gas used by the provider to fulfill the request.
• Consumer Responsibility: The consumer contract must ensure the subscription has sufficient balance, or the request will fail.

A key feature is that the consumer receives cryptographically verifiable randomness. The random numbers are generated off-chain with a secret key and delivered with a cryptographic proof.

• On-Chain Verification: The VRF Provider's coordinator contract verifies this proof on-chain before calling the consumer's callback.
• Tamper-Proof: The randomness is provably unpredictable and cannot be manipulated by the provider, miners/validators, or users.
• Consumer Trust: The consumer's logic executes only after the proof is verified, guaranteeing the integrity of the input.

VRF Consumers are built for specific use cases, leading to common patterns:

• NFT Random Minting: Request randomness upon mint to determine rarity traits or attributes for a new token.
• Lottery & Gaming: Select a random winner from a pool of participants or determine game outcomes.
• DAO Governance: Randomly select contributors for rewards or committee members in a verifiably fair way.
• Dynamic Asset Generation: Create in-game items, artwork, or metadata with random properties.

Powers evolving digital assets and environments where changes are triggered by unpredictable events.

• Procedural Generation: Creating unique, random landscapes or items in virtual worlds.
• NFT Evolution: Triggering state changes (e.g., leveling up) based on random external events.
• Event-Driven Updates: Modifying an asset's metadata or appearance after a random time period or oracle-reported event.

The canonical use case for creating transparent, on-chain lotteries where the winning ticket is selected verifiably at random.

• Smart Contract Lotteries: Decentralized applications where the prize pool and winner selection are fully automated and trustless.
• Airdrop Eligibility: Randomly selecting wallet addresses from a snapshot to receive tokens or NFTs.
• Contest Winners: Fairly picking winners for promotional campaigns or community events.

A VRF Consumer initiates the process by calling the requestRandomness function, which emits an event. An off-chain oracle node detects this event, generates the random number and a cryptographic proof, and delivers it back on-chain via the fulfillRandomness callback function. This two-step process ensures the consumer's logic only executes after provable randomness is securely received.

To function, a consumer contract must:

• Inherit from the VRF provider's base consumer contract (e.g., VRFConsumerBase).
• Define a fulfillRandomness function to handle the received random number.
• Fund its subscription or pay the oracle gas fee to cover the request cost.
• Manage the request ID to correctly match responses to specific on-chain actions, preventing mix-ups.

VRF Consumers are essential for any on-chain application requiring tamper-proof randomness:

• NFT Minting & Traits: Determining rare attributes for generative art collections.
• Play-to-Earn Gaming: Selecting random in-game loot, matchmaking, or critical hits.
• Lotteries & Raffles: Picking verifiably fair winners without a trusted third party.
• DAO Governance: Randomizing committee selection or proposal ordering to prevent manipulation.

The security model relies on the cryptographic proof submitted by the oracle. The VRF provider's on-chain contract verifies this proof before delivering the number to the consumer, guaranteeing it was generated unpredictably and tamper-proof. Consumers must also implement safeguards against reentrancy attacks within the fulfillRandomness callback and ensure adequate gas for the callback execution.

Consumers incur two main costs: the oracle gas fee paid to the VRF service and the gas for their own fulfillRandomness execution. Modern systems like Chainlink VRF use a subscription model, where the consumer contract pre-funds a balance used to pay for requests, simplifying cost management. Failed callbacks due to insufficient gas can leave requests unfulfilled.

solidityCopy
function mintNFT() public {
    bytes32 requestId = requestRandomness(keyHash, fee);
    requestToSender[requestId] = msg.sender;
}

function fulfillRandomness(bytes32 requestId, uint256 randomness) internal override {
    address sender = requestToSender[requestId];
    uint256 newTokenId = uint256(keccak256(abi.encode(randomness, sender)));
    _safeMint(sender, newTokenId);
}

This shows a consumer storing the requester's address with the requestId and using the delivered randomness to mint a unique NFT.

This is the standard two-transaction pattern used by most VRF Consumers.

1. Request: The consumer calls a function on the VRF provider contract, paying fees and providing a seed.
2. Fulfillment: The oracle network later calls the consumer's fulfillRandomWords callback function with the verified random numbers.

This asynchronous pattern is fundamental to on-chain/off-chain interoperability.

The seed is a critical input to the VRF that ensures unique, unpredictable results for each request. It is typically a combination of:

• User-provided seed: A value from the consumer (e.g., a user input).
• Blockhash: From a future block to prevent precomputation.
• Consumer address: To differentiate between contracts.
• Nonce: A request counter.

The consumer must construct this seed carefully to avoid predictability or collisions.

An alternative to VRFs for on-chain randomness, where a participant commits to a hidden number (its hash) and later reveals it. The final random value is derived from all reveals.

• VRF Advantage vs. Commit-Reveal: VRFs provide immediate, verifiable randomness without requiring multiple participants or waiting for a reveal phase, making them superior for many dApp use cases like NFT minting or gameplay.

The callback function (e.g., fulfillRandomWords) is where the VRF Consumer receives and uses the random numbers. A critical consideration is the gas limit for this callback.

• Gas Limit: The VRF provider sets a maximum gas it will pay for the callback execution. The consumer's logic must stay under this limit.
• Failure Risk: If the callback reverts or runs out of gas, the random words are lost, and the consumer may not be able to retry, breaking application logic.