# Getting Started ## Overview ### What is a LINK token? **The LINK token** is an ERC677 token that inherits functionality from the [ERC20 token standard](https://ethereum.org/en/developers/docs/standards/tokens/erc-20/) and allows token transfers to contain a data payload. It is used to pay node operators for retrieving data for smart contracts and also for deposits placed by node operators as required by contract creators. **Any wallet that handles ERC20 tokens can store LINK tokens. The ERC677 token standard that the LINK token implements still retains all functionality of ERC20 tokens.** ### What are oracles? **Oracles** provide a bridge between the real-world and on-chain smart contracts by being a source of data that smart contracts can rely on, and act upon. Oracles play a critical role in facilitating the full potential of smart contract utility. Without a reliable connection to real-world conditions, smart contracts cannot effectively serve the real-world. ### How do smart contracts use oracles? Oracles are most popularly used with [*Data Feeds*](https://docs.chain.link/data-feeds/). DeFi platforms like [AAVE](https://aave.com/) and [Synthetix](https://www.synthetix.io/) use Chainlink data feed oracles to obtain accurate real-time asset prices in their smart contracts. Chainlink data feeds are sources of data [aggregated from many independent Chainlink node operators](https://docs.chain.link/architecture-overview/architecture-decentralized-model/). Each data feed has an on-chain address and functions that enable contracts to read from that address. For example, the [ETH / USD feed](https://data.chain.link/eth-usd/).
Smart contracts also use oracles to get other capabilities on-chain: * [Generate Verifiable Random Numbers (VRF)](https://docs.chain.link/vrf/v2/introduction/): Use Chainlink VRF to consume randomness in your smart contracts. * [Call External APIs (Any API)](https://docs.chain.link/any-api/introduction/): Request & Receive data from any API using the Chainlink contract library. * [Automate Smart Contract Functions (Automation)](https://docs.chain.link/chainlink-automation/introduction/): Automating smart contract functions and regular contract maintenance. ## Consuming Data Feeds When you connect a smart contract to real-world services or off-chain data, you create a **hybrid smart contract**. For example, you can use Chainlink Data Feeds to connect your smart contracts to asset pricing data like the [ETH / USD feed](https://data.chain.link/eth-usd). These data feeds use the data aggregated from many independent Chainlink node operators. **Each price feed has an on-chain address and functions that enable contracts to read pricing data from that address.** The code for reading Data Feeds is the same across all EVM-compatible blockchains and Data Feed types. You choose different types of feeds for different uses, but the request and response format are the same. ### Examine the sample contract This example contract obtains the latest price answer from the [BTC / USD feed](https://docs.chain.link/data-feeds/price-feeds/addresses) on the Sepolia testnet, but you can modify it to read any of the different [Types of Data Feeds](https://docs.chain.link/data-feeds#types-of-data-feeds). ```solidity // SPDX-License-Identifier: MIT pragma solidity ^0.8.7; import "@chainlink/contracts/src/v0.8/interfaces/AggregatorV3Interface.sol"; contract PriceConsumerV3 { AggregatorV3Interface internal priceFeed; /** * Network: Sepolia * Aggregator: BTC/USD * Address: 0x1b44F3514812d835EB1BDB0acB33d3fA3351Ee43 */ constructor() { priceFeed = AggregatorV3Interface( 0x1b44F3514812d835EB1BDB0acB33d3fA3351Ee43 ); } /** * Returns the latest price. */ function getLatestPrice() public view returns (int) { // prettier-ignore ( /* uint80 roundID */, int price, /*uint startedAt*/, /*uint timeStamp*/, /*uint80 answeredInRound*/ ) = priceFeed.latestRoundData(); return price; } } ``` The contract has the following components: * The `import` line imports an interface named `AggregatorV3Interface`. Interfaces define functions without their implementation, which leaves inheriting contracts to define the actual implementation themselves. In this case, `AggregatorV3Interface` defines that all v3 Aggregators have the function `latestRoundData`. You can [see the complete code](https://github.com/smartcontractkit/chainlink/blob/develop/contracts/src/v0.8/interfaces/AggregatorV3Interface.sol) for the `AggregatorV3Interface` on GitHub. * The `constructor() {}` initializes an interface object named `priceFeed` that uses `AggregatorV3Interface` and connects specifically to a proxy aggregator contract that is already deployed at `0x1b44F3514812d835EB1BDB0acB33d3fA3351Ee43`. The interface allows your contract to run functions on that deployed aggregator contract. * The `getLatestPrice()` function calls your `priceFeed` object and runs the `latestRoundData()` function. When you deploy the contract, it initializes the `priceFeed` object to point to the aggregator at `0x1b44F3514812d835EB1BDB0acB33d3fA3351Ee43`, which is the proxy address for the Sepolia BTC / USD data feed. Your contract connects to that address and executes the function. The aggregator connects with several oracle nodes and aggregates the pricing data from those nodes. The response from the aggregator includes several variables, but `getLatestPrice()` returns only the `price` variable. ## Get Random Numbers In this guide, you will learn about generating randomness on blockchains. This includes learning how to implement a Request and Receive cycle with Chainlink oracles and how to consume random numbers with Chainlink VRF in smart contracts. ### How is randomness generated on blockchains? What is Chainlink VRF? Randomness is very difficult to generate on blockchains. This is because every node on the blockchain must come to the same conclusion and form a consensus. Even though random numbers are versatile and useful in a variety of blockchain applications, they cannot be generated natively in smart contracts. The solution to this issue is [**Chainlink VRF**](https://docs.chain.link/vrf/v2/introduction/), also known as Chainlink Verifiable Random Function. ### What is the Request and Receive cycle? The [previous guide](https://docs.chain.link/getting-started/consuming-data-feeds/) explained how to consume Chainlink Data Feeds, which consist of reference data posted on-chain by oracles. This data is stored in a contract and can be referenced by consumers until the oracle updates the data again. Randomness, on the other hand, cannot be reference data. If the result of randomness is stored on-chain, any actor could retrieve the value and predict the outcome. **Instead, randomness must be requested from an oracle, which generates a number and a cryptographic proof.** Then, the oracle returns that result to the contract that requested it. This sequence is known as the [**Request and Receive cycle**](https://docs.chain.link/architecture-overview/architecture-request-model/). ### What is the payment process for generating a random number? VRF requests receive funding from subscription accounts. The [Subscription Manager](https://vrf.chain.link/) lets you create an account and pre-pay for VRF requests, so that funding of all your application requests are managed in a single location. To learn more about VRF requests funding, see [Subscriptions limits](https://docs.chain.link/vrf/v2/subscription#subscription-limits). ### How can I use Chainlink VRF? To see a basic implementation of Chainlink VRF, see [Get a Random Number](https://docs.chain.link/vrf/v2/subscription/examples/get-a-random-number/). In this section, you will create an application that uses Chainlink VRF to generate randomness. The contract used in this application will have a [*Game of Thrones*](https://en.wikipedia.org/wiki/Game_of_Thrones) theme. The contract will request randomness from Chainlink VRF. The result of the randomness will transform into a number between 1 and 20, mimicking the rolling of a 20 sided die. Each number represents a *Game of Thrones* house. If the dice land on the value 1, the user is assigned house Targaryan, 2 for Lannister, and so on. A full list of houses can be found [here](https://gameofthrones.fandom.com/wiki/Great_House). When rolling the dice, it will accept an `address` variable to track which address is assigned to each house. The contract will have the following functions: * `rollDice`: This submits a randomness request to Chainlink VRF * `fulfillRandomWords`: The function that the Oracle uses to send the result back * `house`: To see the assigned house of an address **Note**: to jump straight to the entire implementation, you can [open the VRFD20.sol contract](https://remix.ethereum.org/#url=https://docs.chain.link/samples/VRF/VRFD20.sol) in remix. #### Create and fund a subscription **Chainlink VRF requests receive funding from subscription accounts.** The [Subscription Manager](https://vrf.chain.link/) lets you create an account and pre-pay your use of Chainlink VRF requests. For this example, create a new subscription on the Sepolia testnet as explained [here](https://docs.chain.link/vrf/v2/subscription/examples/get-a-random-number/#create-and-fund-a-subscription). #### Importing `VRFConsumerBaseV2` and `VRFCoordinatorV2Interface` Chainlink maintains a [library of contracts](https://github.com/smartcontractkit/chainlink/tree/master/contracts) that make consuming data from oracles easier. For Chainlink VRF, you will use: * [`VRFConsumerBaseV2`](https://github.com/smartcontractkit/chainlink/blob/master/contracts/src/v0.8/VRFConsumerBaseV2.sol) that must be imported and extended from the contract that you create. * [`VRFCoordinatorV2Interface`](https://github.com/smartcontractkit/chainlink/blob/master/contracts/src/v0.8/interfaces/VRFCoordinatorV2Interface.sol) that must be imported to communicate with the VRF coordinator. ```solidity // SPDX-License-Identifier: MIT pragma solidity ^0.8.7; import "@chainlink/contracts/src/v0.8/interfaces/VRFCoordinatorV2Interface.sol"; import "@chainlink/contracts/src/v0.8/VRFConsumerBaseV2.sol"; contract VRFD20 is VRFConsumerBaseV2 { } ``` #### Contract variables This example is adapted for [Sepolia testnet](https://docs.chain.link/vrf/v2/subscription/supported-networks/#sepolia-testnet) but you can change the configuration and make it run for any [supported network](https://docs.chain.link/vrf/v2/subscription/supported-networks/#configurations). ```solidity uint64 s_subscriptionId; address vrfCoordinator = 0x2Ca8E0C643bDe4C2E08ab1fA0da3401AdAD7734D; bytes32 s_keyHash = 0x79d3d8832d904592c0bf9818b621522c988bb8b0c05cdc3b15aea1b6e8db0c15; uint32 callbackGasLimit = 40000; uint16 requestConfirmations = 3; uint32 numWords = 1; ``` * `uint64 s_subscriptionId`: The subscription ID that this contract uses for funding requests. Initialized in the `constructor`. * `address vrfCoordinator`: The address of the Chainlink VRF Coordinator contract. * `bytes32 s_keyHash`: The gas lane key hash value, which is the maximum gas price you are willing to pay for a request in wei. It functions as an ID of the off-chain VRF job that runs in response to requests. * `uint32 callbackGasLimit`: The limit for how much gas to use for the callback request to your contract’s `fulfillRandomWords` function. It must be less than the `maxGasLimit` on the coordinator contract. Adjust this value for larger requests depending on how your `fulfillRandomWords` function processes and stores the received random values. If your `callbackGasLimit` is not sufficient, the callback will fail and your subscription is still charged for the work done to generate your requested random values. * `uint16 requestConfirmations`: How many confirmations the Chainlink node should wait before responding. The longer the node waits, the more secure the random value is. It must be greater than the `minimumRequestBlockConfirmations` limit on the coordinator contract. * `uint32 numWords`: How many random values to request. If you can use several random values in a single callback, you can reduce the amount of gas that you spend per random value. In this example, each transaction requests one random value. To keep track of addresses that roll the dice, the contract uses mappings. [Mappings](https://medium.com/upstate-interactive/mappings-in-solidity-explained-in-under-two-minutes-ecba88aff96e) are unique key-value pair data structures similar to hash tables in Java. ```solidity mapping(uint256 => address) private s_rollers; mapping(address => uint256) private s_results; ``` * `s_rollers` stores a mapping between the `requestID` (returned when a request is made), and the address of the roller. This is so the contract can keep track of who to assign the result to when it comes back. * `s_results` stores the roller and the result of the dice roll. #### Initializing the contract The coordinator and subscription id must be initialized in the `constructor` of the contract. To use `VRFConsumerBaseV2` properly, you must also pass the VRF coordinator address into its constructor. The address that creates the smart contract is the owner of the contract. the modifier `onlyOwner()` checks that only the owner is allowed to do some tasks. ```solidity // SPDX-License-Identifier: MIT pragma solidity ^0.8.7; import "@chainlink/contracts/src/v0.8/interfaces/VRFCoordinatorV2Interface.sol"; import "@chainlink/contracts/src/v0.8/VRFConsumerBaseV2.sol"; contract VRFD20 is VRFConsumerBaseV2 { // variables // ... // constructor constructor(uint64 subscriptionId) VRFConsumerBaseV2(vrfCoordinator) { COORDINATOR = VRFCoordinatorV2Interface(vrfCoordinator); s_owner = msg.sender; s_subscriptionId = subscriptionId; } //... modifier onlyOwner() { require(msg.sender == s_owner); _; } } ``` #### `rollDice` function The `rollDice` function will complete the following tasks: 1. Check if the roller has already rolled since each roller can only ever be assigned to a single house. 2. Request randomness by calling the VRF coordinator. 3. Store the `requestId` and roller address. 4. Emit an event to signal that the dice is rolling. **You must add a** `ROLL_IN_PROGRESS` **constant to signify that the dice has been rolled but the result is not yet returned.** Also add a `DiceRolled` event to the contract. Only the owner of the contract can execute the `rollDice` function. ```solidity // SPDX-License-Identifier: MIT pragma solidity ^0.8.7; import "@chainlink/contracts/src/v0.8/interfaces/VRFCoordinatorV2Interface.sol"; import "@chainlink/contracts/src/v0.8/VRFConsumerBaseV2.sol"; contract VRFD20 is VRFConsumerBaseV2 { // variables uint256 private constant ROLL_IN_PROGRESS = 42; // ... // events event DiceRolled(uint256 indexed requestId, address indexed roller); // ... // ... // { constructor } // ... // rollDice function 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 = COORDINATOR.requestRandomWords( s_keyHash, s_subscriptionId, requestConfirmations, callbackGasLimit, numWords ); s_rollers[requestId] = roller; s_results[roller] = ROLL_IN_PROGRESS; emit DiceRolled(requestId, roller); } } ``` #### `fulfillRandomWords` function `fulfillRandomWords` is a special function defined within the `VRFConsumerBaseV2` contract that our contract extends from. The coordinator sends the result of our generated `randomWords` back to `fulfillRandomWords`. You will implement some functionality here to deal with the result: 1. Change the result to a number between 1 and 20 inclusively. Note that `randomWords` is an array that could contain several random values. In this example, request 1 random value. 2. Assign the transformed value to the address in the `s_results` mapping variable. 3. Emit a `DiceLanded` event. ```solidity // SPDX-License-Identifier: MIT pragma solidity ^0.8.7; import "@chainlink/contracts/src/v0.8/interfaces/VRFCoordinatorV2Interface.sol"; import "@chainlink/contracts/src/v0.8/VRFConsumerBaseV2.sol"; contract VRFD20 is VRFConsumerBaseV2 { // ... // { variables } // ... // events // ... event DiceLanded(uint256 indexed requestId, uint256 indexed result); // ... // { constructor } // ... // ... // { rollDice function } // ... // fulfillRandomWords function function fulfillRandomWords(uint256 requestId, uint256[] memory randomWords) internal override { // transform the result to a number between 1 and 20 inclusively uint256 d20Value = (randomWords[0] % 20) + 1; // assign the transformed value to the address in the s_results mapping variable s_results[s_rollers[requestId]] = d20Value; // emitting event to signal that dice landed emit DiceLanded(requestId, d20Value); } } ``` #### `house` function Finally, the `house` function returns the house of an address. To have a list of the house's names, create the `getHouseName` function that is called in the `house` function. ```solidity // SPDX-License-Identifier: MIT pragma solidity ^0.8.7; import "@chainlink/contracts/src/v0.8/interfaces/VRFCoordinatorV2Interface.sol"; import "@chainlink/contracts/src/v0.8/VRFConsumerBaseV2.sol"; contract VRFD20 is VRFConsumerBaseV2 { // ... // { variables } // ... // ... // { events } // ... // ... // { constructor } // ... // ... // { rollDice function } // ... // ... // { fulfillRandomWords function } // ... // house function function house(address player) public view returns (string memory) { // dice has not yet been rolled to this address require(s_results[player] != 0, "Dice not rolled"); // not waiting for the result of a thrown dice require(s_results[player] != ROLL_IN_PROGRESS, "Roll in progress"); // returns the house name from the name list function return getHouseName(s_results[player]); } // getHouseName function function getHouseName(uint256 id) private pure returns (string memory) { // array storing the list of house's names string[20] memory houseNames = [ "Targaryen", "Lannister", "Stark", "Tyrell", "Baratheon", "Martell", "Tully", "Bolton", "Greyjoy", "Arryn", "Frey", "Mormont", "Tarley", "Dayne", "Umber", "Valeryon", "Manderly", "Clegane", "Glover", "Karstark" ]; // returns the house name given an index return houseNames[id - 1]; } } ``` You have now completed all necessary functions to generate randomness and assign the user a *Game of Thrones* house. We’ve added a few helper functions in there to make using the contract easier and more flexible. You can deploy and interact with the complete contract in Remix. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://ret2basic.gitbook.io/ctfnote/web3-security-research/defi/chainlink/getting-started.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.