VRF 2.5 - Getting started (#1931)

* baseline copy of v2 getting started * getting started updates * small change * Update fulfillRandomWords, code comments, minor error * remove onlyOwner modifier? * Update to 1.1.1-beta * remove interface import * resolve a few solc warnings * Remove interface import, add native payment option in explanation * reduce solc warnings * Back to 1.1.0 * Back to calldata * Calldata --> memory in more files * Add to sidebar * Cleanup and new images --------- Co-authored-by: Dwight Lyle <dwightjl@gmail.com>
smartcontractkit · May 17, 2024 · fd0b4f5 · fd0b4f5
1 parent 34cc77c
commit fd0b4f5
Show file tree

Hide file tree

Showing 10 changed files with 581 additions and 24 deletions.
diff --git a/package-lock.json b/package-lock.json
diff --git a/public/images/vrf/v2-5/copy-contract-address.png b/public/images/vrf/v2-5/copy-contract-address.png
diff --git a/public/images/vrf/v2-5/deploy-with-sub-id.png b/public/images/vrf/v2-5/deploy-with-sub-id.png
diff --git a/public/images/vrf/v2-5/select-vrfd20-contract.png b/public/images/vrf/v2-5/select-vrfd20-contract.png
diff --git a/public/images/vrf/v2-5/ui-add-consumer.png b/public/images/vrf/v2-5/ui-add-consumer.png
diff --git a/public/samples/VRF/v2-5/SubscriptionConsumer.sol b/public/samples/VRF/v2-5/SubscriptionConsumer.sol
@@ -2,7 +2,6 @@
 // An example of a consumer contract that relies on a subscription for funding.
 pragma solidity 0.8.19;
 
-import {IVRFCoordinatorV2Plus} from "@chainlink/contracts/src/v0.8/vrf/dev/interfaces/IVRFCoordinatorV2Plus.sol";
 import {VRFConsumerBaseV2Plus} from "@chainlink/contracts/src/v0.8/vrf/dev/VRFConsumerBaseV2Plus.sol";
 import {VRFV2PlusClient} from "@chainlink/contracts/src/v0.8/vrf/dev/libraries/VRFV2PlusClient.sol";
 
@@ -28,19 +27,18 @@ contract SubscriptionConsumer is VRFConsumerBaseV2Plus {
     }
     mapping(uint256 => RequestStatus)
         public s_requests; /* requestId --> requestStatus */
-    IVRFCoordinatorV2Plus COORDINATOR;
 
     // Your subscription ID.
-    uint256 s_subscriptionId;
+    uint256 public s_subscriptionId;
 
-    // past requests Id.
+    // Past request IDs.
     uint256[] public requestIds;
     uint256 public lastRequestId;
 
     // The gas lane to use, which specifies the maximum gas price to bump to.
     // For a list of available gas lanes on each network,
     // see https://docs.chain.link/docs/vrf/v2-5/supported-networks
-    bytes32 keyHash =
+    bytes32 public keyHash =
         0x787d74caea10b2b357790d5b5247c2f63d1d91572a9846f780606e4d953677ae;
 
     // Depends on the number of requested values that you want sent to the
@@ -49,14 +47,14 @@ contract SubscriptionConsumer is VRFConsumerBaseV2Plus {
     // this limit based on the network that you select, the size of the request,
     // and the processing of the callback request in the fulfillRandomWords()
     // function.
-    uint32 callbackGasLimit = 100000;
+    uint32 public callbackGasLimit = 100000;
 
     // The default is 3, but you can set this higher.
-    uint16 requestConfirmations = 3;
+    uint16 public requestConfirmations = 3;
 
     // For this example, retrieve 2 random values in one request.
     // Cannot exceed VRFCoordinatorV2_5.MAX_NUM_WORDS.
-    uint32 numWords = 2;
+    uint32 public numWords = 2;
 
     /**
      * HARDCODED FOR SEPOLIA
@@ -65,9 +63,6 @@ contract SubscriptionConsumer is VRFConsumerBaseV2Plus {
     constructor(
         uint256 subscriptionId
     ) VRFConsumerBaseV2Plus(0x9DdfaCa8183c41ad55329BdeeD9F6A8d53168B1B) {
-        COORDINATOR = IVRFCoordinatorV2Plus(
-            0x9DdfaCa8183c41ad55329BdeeD9F6A8d53168B1B
-        );
         s_subscriptionId = subscriptionId;
     }
 
@@ -79,7 +74,7 @@ contract SubscriptionConsumer is VRFConsumerBaseV2Plus {
     {
         // Will revert if subscription is not set and funded.
         // To enable payment in native tokens, set nativePayment to true.
-        requestId = COORDINATOR.requestRandomWords(
+        requestId = s_vrfCoordinator.requestRandomWords(
             VRFV2PlusClient.RandomWordsRequest({
                 keyHash: keyHash,
                 subId: s_subscriptionId,

diff --git a/public/samples/VRF/v2-5/SubscriptionManager.sol b/public/samples/VRF/v2-5/SubscriptionManager.sol
@@ -23,28 +23,30 @@ contract VRFv2PlusSubscriptionManager is VRFConsumerBaseV2Plus {
 
     // Sepolia coordinator. For other networks,
     // see https://docs.chain.link/docs/vrf/v2-5/subscription-supported-networks#configurations
-    address vrfCoordinatorV2Plus = 0x9DdfaCa8183c41ad55329BdeeD9F6A8d53168B1B;
+    address public vrfCoordinatorV2Plus =
+        0x9DdfaCa8183c41ad55329BdeeD9F6A8d53168B1B;
 
     // Sepolia LINK token contract. For other networks, see
     // https://docs.chain.link/docs/vrf-contracts/#configurations
-    address link_token_contract = 0x779877A7B0D9E8603169DdbD7836e478b4624789;
+    address public link_token_contract =
+        0x779877A7B0D9E8603169DdbD7836e478b4624789;
 
     // The gas lane to use, which specifies the maximum gas price to bump to.
     // For a list of available gas lanes on each network,
     // see https://docs.chain.link/docs/vrf/v2-5/subscription-supported-networks#configurations
-    bytes32 keyHash =
+    bytes32 public keyHash =
         0x787d74caea10b2b357790d5b5247c2f63d1d91572a9846f780606e4d953677ae;
 
     // A reasonable default is 100000, but this value could be different
     // on other networks.
-    uint32 callbackGasLimit = 100000;
+    uint32 public callbackGasLimit = 100000;
 
     // The default is 3, but you can set this higher.
-    uint16 requestConfirmations = 3;
+    uint16 public requestConfirmations = 3;
 
     // For this example, retrieve 2 random values in one request.
     // Cannot exceed VRFCoordinatorV2.MAX_NUM_WORDS.
-    uint32 numWords = 2;
+    uint32 public numWords = 2;
 
     // Storage parameters
     uint256[] public s_randomWords;
@@ -55,7 +57,7 @@ contract VRFv2PlusSubscriptionManager is VRFConsumerBaseV2Plus {
         s_vrfCoordinator = IVRFCoordinatorV2Plus(vrfCoordinatorV2Plus);
         LINKTOKEN = LinkTokenInterface(link_token_contract);
         //Create a new subscription when you deploy the contract.
-        createNewSubscription();
+        _createNewSubscription();
     }
 
     // Assumes the subscription is funded sufficiently.
@@ -83,7 +85,7 @@ contract VRFv2PlusSubscriptionManager is VRFConsumerBaseV2Plus {
     }
 
     // Create a new subscription when the contract is initially deployed.
-    function createNewSubscription() private onlyOwner {
+    function _createNewSubscription() private onlyOwner {
         s_subscriptionId = s_vrfCoordinator.createSubscription();
         // Add this contract as a consumer of its own subscription.
         s_vrfCoordinator.addConsumer(s_subscriptionId, address(this));

diff --git a/public/samples/VRF/v2-5/VRFD20.sol b/public/samples/VRF/v2-5/VRFD20.sol
@@ -0,0 +1,168 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.19;
+
+import {VRFConsumerBaseV2Plus} from "@chainlink/contracts/src/v0.8/vrf/dev/VRFConsumerBaseV2Plus.sol";
+import {VRFV2PlusClient} from "@chainlink/contracts/src/v0.8/vrf/dev/libraries/VRFV2PlusClient.sol";
+
+/**
+ * @notice A Chainlink VRF consumer which uses randomness to mimic the rolling
+ * of a 20 sided dice
+ */
+
+/**
+ * Request testnet LINK and ETH here: https://faucets.chain.link/
+ * Find information on LINK Token Contracts and get the latest ETH and LINK faucets here: https://docs.chain.link/docs/link-token-contracts/
+ */
+
+/**
+ * THIS IS AN EXAMPLE CONTRACT THAT USES HARDCODED VALUES FOR CLARITY.
+ * THIS IS AN EXAMPLE CONTRACT THAT USES UN-AUDITED CODE.
+ * DO NOT USE THIS CODE IN PRODUCTION.
+ */
+
+contract VRFD20 is VRFConsumerBaseV2Plus {
+    uint256 private constant ROLL_IN_PROGRESS = 42;
+
+    // Your subscription ID.
+    uint256 public s_subscriptionId;
+
+    // Sepolia coordinator. For other networks,
+    // see https://docs.chain.link/vrf/v2-5/supported-networks#configurations
+    address public vrfCoordinator = 0x9DdfaCa8183c41ad55329BdeeD9F6A8d53168B1B;
+
+    // The gas lane to use, which specifies the maximum gas price to bump to.
+    // For a list of available gas lanes on each network,
+    // see https://docs.chain.link/vrf/v2-5/supported-networks#configurations
+    bytes32 public s_keyHash =
+        0x787d74caea10b2b357790d5b5247c2f63d1d91572a9846f780606e4d953677ae;
+
+    // Depends on the number of requested values that you want sent to the
+    // fulfillRandomWords() function. Storing each word costs about 20,000 gas,
+    // so 40,000 is a safe default for this example contract. Test and adjust
+    // this limit based on the network that you select, the size of the request,
+    // and the processing of the callback request in the fulfillRandomWords()
+    // function.
+    uint32 public callbackGasLimit = 40000;
+
+    // The default is 3, but you can set this higher.
+    uint16 public requestConfirmations = 3;
+
+    // For this example, retrieve 1 random value in one request.
+    // Cannot exceed VRFCoordinatorV2_5.MAX_NUM_WORDS.
+    uint32 public numWords = 1;
+
+    // map rollers to requestIds
+    mapping(uint256 => address) private s_rollers;
+    // map vrf results to rollers
+    mapping(address => uint256) private s_results;
+
+    event DiceRolled(uint256 indexed requestId, address indexed roller);
+    event DiceLanded(uint256 indexed requestId, uint256 indexed result);
+
+    /**
+     * @notice Constructor inherits VRFConsumerBaseV2Plus
+     *
+     * @dev NETWORK: Sepolia
+     *
+     * @param subscriptionId subscription ID that this consumer contract can use
+     */
+    constructor(uint256 subscriptionId) VRFConsumerBaseV2Plus(vrfCoordinator) {
+        s_subscriptionId = subscriptionId;
+    }
+
+    /**
+     * @notice Requests randomness
+     * @dev Warning: if the VRF response is delayed, avoid calling requestRandomness repeatedly
+     * as that would give miners/VRF operators latitude about which VRF response arrives first.
+     * @dev You must review your implementation details with extreme care.
+     *
+     * @param roller address of the roller
+     */
+    function rollDice(
+        address roller
+    ) public onlyOwner returns (uint256 requestId) {
+        require(s_results[roller] == 0, "Already rolled");
+        // Will revert if subscription is not set and funded.
+        requestId = s_vrfCoordinator.requestRandomWords(
+            VRFV2PlusClient.RandomWordsRequest({
+                keyHash: s_keyHash,
+                subId: s_subscriptionId,
+                requestConfirmations: requestConfirmations,
+                callbackGasLimit: callbackGasLimit,
+                numWords: numWords,
+                extraArgs: VRFV2PlusClient._argsToBytes(
+                    // Set nativePayment to true to pay for VRF requests with Sepolia ETH instead of LINK
+                    VRFV2PlusClient.ExtraArgsV1({nativePayment: false})
+                )
+            })
+        );
+
+        s_rollers[requestId] = roller;
+        s_results[roller] = ROLL_IN_PROGRESS;
+        emit DiceRolled(requestId, roller);
+    }
+
+    /**
+     * @notice Callback function used by VRF Coordinator to return the random number to this contract.
+     *
+     * @dev Some action on the contract state should be taken here, like storing the result.
+     * @dev WARNING: take care to avoid having multiple VRF requests in flight if their order of arrival would result
+     * in contract states with different outcomes. Otherwise miners or the VRF operator would could take advantage
+     * by controlling the order.
+     * @dev The VRF Coordinator will only send this function verified responses, and the parent VRFConsumerBaseV2
+     * contract ensures that this method only receives randomness from the designated VRFCoordinator.
+     *
+     * @param requestId uint256
+     * @param randomWords  uint256[] The random result returned by the oracle.
+     */
+    function fulfillRandomWords(
+        uint256 requestId,
+        uint256[] memory randomWords
+    ) internal override {
+        uint256 d20Value = (randomWords[0] % 20) + 1;
+        s_results[s_rollers[requestId]] = d20Value;
+        emit DiceLanded(requestId, d20Value);
+    }
+
+    /**
+     * @notice Get the house assigned to the player once the address has rolled
+     * @param player address
+     * @return house as a string
+     */
+    function house(address player) public view returns (string memory) {
+        require(s_results[player] != 0, "Dice not rolled");
+        require(s_results[player] != ROLL_IN_PROGRESS, "Roll in progress");
+        return _getHouseName(s_results[player]);
+    }
+
+    /**
+     * @notice Get the house name from the id
+     * @param id uint256
+     * @return house name string
+     */
+    function _getHouseName(uint256 id) private pure returns (string memory) {
+        string[20] memory houseNames = [
+            "Targaryen",
+            "Lannister",
+            "Stark",
+            "Tyrell",
+            "Baratheon",
+            "Martell",
+            "Tully",
+            "Bolton",
+            "Greyjoy",
+            "Arryn",
+            "Frey",
+            "Mormont",
+            "Tarley",
+            "Dayne",
+            "Umber",
+            "Valeryon",
+            "Manderly",
+            "Clegane",
+            "Glover",
+            "Karstark"
+        ];
+        return houseNames[id - 1];
+    }
+}
diff --git a/src/config/sidebar.ts b/src/config/sidebar.ts
@@ -764,6 +764,10 @@ export const SIDEBAR: Partial<Record<Sections, SectionEntry[]>> = {
             },
           ],
         },
+        {
+          title: "Getting Started with Chainlink VRF V2.5",
+          url: "vrf/v2-5/getting-started",
+        },
         {
           title: "Migration from V2",
           url: "vrf/v2-5/migration-from-v2",