diff --git a/foundry.toml b/foundry.toml index 9ddbb1152ba..f8a4dcbc2f4 100644 --- a/foundry.toml +++ b/foundry.toml @@ -9,6 +9,11 @@ out = ".test/artifacts" cache_path = ".test/cache" libs = ["lib", "node_modules"] +# Foundry deploy scripts (e.g. public/samples/DataFeeds/Foundry/*.s.sol) are +# meant to run inside a user's Foundry project where forge-std and a src/ layout +# are available. They cannot compile in this repo, so skip them. +skip = ["*/DataFeeds/Foundry/*"] + optimizer = true optimizer_runs = 1_000_000 diff --git a/public/images/getting-started/new_chooseFunction.png b/public/images/getting-started/new_chooseFunction.png new file mode 100644 index 00000000000..87e022b9953 Binary files /dev/null and b/public/images/getting-started/new_chooseFunction.png differ diff --git a/public/images/getting-started/new_chooseSepolia.png b/public/images/getting-started/new_chooseSepolia.png new file mode 100644 index 00000000000..6fac3b71f95 Binary files /dev/null and b/public/images/getting-started/new_chooseSepolia.png differ diff --git a/public/images/getting-started/new_compiledDataConsumerV3.png b/public/images/getting-started/new_compiledDataConsumerV3.png new file mode 100644 index 00000000000..c4a1c1c144f Binary files /dev/null and b/public/images/getting-started/new_compiledDataConsumerV3.png differ diff --git a/public/images/getting-started/new_connectRemix.png b/public/images/getting-started/new_connectRemix.png new file mode 100644 index 00000000000..d2afe1bcbcd Binary files /dev/null and b/public/images/getting-started/new_connectRemix.png differ diff --git a/public/images/getting-started/new_deployDataConsumerV3Contract.png b/public/images/getting-started/new_deployDataConsumerV3Contract.png new file mode 100644 index 00000000000..1e3ca37cfae Binary files /dev/null and b/public/images/getting-started/new_deployDataConsumerV3Contract.png differ diff --git a/public/images/getting-started/new_deployedContractDataConsumerV3.png b/public/images/getting-started/new_deployedContractDataConsumerV3.png new file mode 100644 index 00000000000..2cdf2a4337a Binary files /dev/null and b/public/images/getting-started/new_deployedContractDataConsumerV3.png differ diff --git a/public/images/getting-started/new_getLatestPrice.png b/public/images/getting-started/new_getLatestPrice.png new file mode 100644 index 00000000000..4f459e334c0 Binary files /dev/null and b/public/images/getting-started/new_getLatestPrice.png differ diff --git a/public/images/getting-started/new_metamaskDeployDataConsumerV3.png b/public/images/getting-started/new_metamaskDeployDataConsumerV3.png new file mode 100644 index 00000000000..31425bfa89a Binary files /dev/null and b/public/images/getting-started/new_metamaskDeployDataConsumerV3.png differ diff --git a/public/images/getting-started/new_navigateSolidityCompiler.png b/public/images/getting-started/new_navigateSolidityCompiler.png new file mode 100644 index 00000000000..2b5f3cb7cb4 Binary files /dev/null and b/public/images/getting-started/new_navigateSolidityCompiler.png differ diff --git a/public/images/getting-started/new_solidityCompiler.png b/public/images/getting-started/new_solidityCompiler.png new file mode 100644 index 00000000000..a3616eaa60d Binary files /dev/null and b/public/images/getting-started/new_solidityCompiler.png differ diff --git a/public/samples/DataFeeds/Foundry/DeployAndReadDataConsumerV3.s.sol b/public/samples/DataFeeds/Foundry/DeployAndReadDataConsumerV3.s.sol new file mode 100644 index 00000000000..8c4ff0ab527 --- /dev/null +++ b/public/samples/DataFeeds/Foundry/DeployAndReadDataConsumerV3.s.sol @@ -0,0 +1,59 @@ +// SPDX-License-Identifier: MIT +pragma solidity ^0.8.7; + +/* solhint-disable no-console */ + +import {DataConsumerV3} from "../../src/DataFeeds/DataConsumerV3.sol"; +import {AggregatorV3Interface} from "@chainlink/contracts/src/v0.8/shared/interfaces/AggregatorV3Interface.sol"; +import {Script} from "forge-std/Script.sol"; +import {console2} from "forge-std/console2.sol"; + +/** + * THIS IS EXAMPLE CODE THAT USES HARDCODED VALUES FOR CLARITY. + * THIS IS EXAMPLE CODE THAT USES UN-AUDITED CODE. + * DO NOT USE THIS CODE IN PRODUCTION. + * + * Deploy DataConsumerV3 and read the latest BTC/USD price on Sepolia. + * + * Usage: + * forge script script/DataFeeds/DeployAndReadDataConsumerV3.s.sol \ + * --rpc-url $SEPOLIA_RPC_URL \ + * --broadcast \ + * --private-key $PRIVATE_KEY + */ +contract DeployAndReadDataConsumerV3 is Script { + // Sepolia BTC / USD price feed proxy address + address public constant SEPOLIA_BTC_USD = 0x1b44F3514812d835EB1BDB0acB33d3fA3351Ee43; + + function run() public { + vm.startBroadcast(); + + // 1. Deploy the consumer contract + DataConsumerV3 consumer = new DataConsumerV3(); + console2.log("DataConsumerV3 deployed at:", address(consumer)); + + vm.stopBroadcast(); + + // 2. Read the latest price through the consumer + int256 answer = consumer.getChainlinkDataFeedLatestAnswer(); + console2.log("Latest answer (raw):", uint256(answer)); + + // 3. Read decimals directly from the feed to scale the answer + uint8 decimals = AggregatorV3Interface(SEPOLIA_BTC_USD).decimals(); + console2.log("Decimals:", decimals); + console2.log("Latest price (scaled): %s", _scale(answer, decimals)); + } + + function _scale( + int256 answer, + uint8 decimals + ) internal pure returns (string memory) { + // Convert the integer answer to a human-readable price string. + // For 8 decimals, 3030914000000 -> "30309.14000000" + uint256 magnitude = uint256(answer); + uint256 base = 10 ** decimals; + uint256 whole = magnitude / base; + uint256 fraction = magnitude % base; + return string.concat(vm.toString(whole), ".", vm.toString(fraction)); + } +} diff --git a/public/samples/DataFeeds/Hardhat/DeployAndReadDataConsumerV3.js b/public/samples/DataFeeds/Hardhat/DeployAndReadDataConsumerV3.js new file mode 100644 index 00000000000..d9f19406c8e --- /dev/null +++ b/public/samples/DataFeeds/Hardhat/DeployAndReadDataConsumerV3.js @@ -0,0 +1,47 @@ +import { network } from "hardhat" + +/** + * THIS IS EXAMPLE CODE THAT USES HARDCODED VALUES FOR CLARITY. + * THIS IS EXAMPLE CODE THAT USES UN-AUDITED CODE. + * DO NOT USE THIS CODE IN PRODUCTION. + */ + +const { ethers } = await network.create() + +async function main() { + // 1. Deploy the DataConsumerV3 contract + const consumer = await ethers.deployContract("DataConsumerV3") + await consumer.waitForDeployment() + + const consumerAddress = await consumer.getAddress() + console.log("DataConsumerV3 deployed at:", consumerAddress) + + // 2. Read the latest price through the consumer contract + const answer = await consumer.getChainlinkDataFeedLatestAnswer() + console.log("Latest answer (raw):", answer.toString()) + + // 3. Read decimals directly from the feed to scale the answer + // Sepolia BTC / USD price feed proxy address + const feedAddress = "0x1b44F3514812d835EB1BDB0acB33d3fA3351Ee43" + const AggregatorV3Interface = [ + { + inputs: [], + name: "decimals", + outputs: [{ internalType: "uint8", name: "", type: "uint8" }], + stateMutability: "view", + type: "function", + }, + ] + const feed = await ethers.getContractAt(AggregatorV3Interface, feedAddress) + const decimals = await feed.decimals() + console.log("Decimals:", decimals) + + // 4. Scale and print the human-readable price + const scaled = Number(answer) / 10 ** Number(decimals) + console.log("Latest price (USD):", scaled) +} + +main().catch((error) => { + console.error(error) + process.exit(1) +}) diff --git a/src/content/data-feeds/getting-started-hardhat.mdx b/src/content/data-feeds/getting-started-hardhat.mdx new file mode 100644 index 00000000000..5a35ef5996d --- /dev/null +++ b/src/content/data-feeds/getting-started-hardhat.mdx @@ -0,0 +1,488 @@ +--- +section: dataFeeds +date: Last Modified +title: "Getting Started with Data Feeds (using Hardhat)" +metadata: + title: "Getting Started with Chainlink Data Feeds — Hardhat" + description: "Read Chainlink Data Feeds in a smart contract using Hardhat. Deploy a consumer contract on Sepolia with ethers.js, read the BTC/USD price feed onchain, and read feeds offchain from a script." + excerpt: "Deploy a consumer contract with Hardhat and read Data Feeds onchain and offchain" + image: "/files/1a63254-link.png" + difficulty: "beginner" + estimatedTime: "15 minutes" +whatsnext: + { + "Read Data Feeds on other EVM chains and with other Web3 libraries": "/data-feeds/using-data-feeds", + "Retrieve Historical Price Data": "/data-feeds/historical-data", + "Read the Data Feeds API Reference": "/data-feeds/api-reference", + "Find Price Feed addresses on other networks": "/data-feeds/price-feeds/addresses", + } +--- + +import { Accordion, CodeSample, ClickToZoom, CopyText, Aside, PageTabs } from "@components" + +Chainlink Data Feeds are the fastest way to connect your smart contracts to real-world data such as asset prices, reserve balances, and L2 sequencer health. Each feed is aggregated by many independent Chainlink node operators and published onchain through a decentralized oracle network, giving your contracts a reliable, manipulation-resistant source of data. + +Each price feed has an onchain address and functions that enable contracts to read pricing data from that address. + +In this guide you will fetch the pricing data from a price feed, for example the [BTC / USD feed](https://data.chain.link/feeds/ethereum/mainnet/btc-usd). + + + +## What you'll do + +- Retrieve latest pricing data from the BTC / USD price feed offchain directly from the feed proxy. _(Offchain methods are useful for backends, bots, dashboards, and pre-trade checks)_ +- Deploy and retrieve the latest price onchain using a Solidity consumer contract that reads the BTC / USD price feed on Sepolia. _(Onchain methods are useful for when you need to apply smart contract logic in your application based on the pricing data.)_ +- Learn the key safety checks to apply before moving to production. + +**Note:** The code for reading Data Feeds on Ethereum and other EVM-compatible blockchains is the same for every chain and every feed type. You choose different feeds for different use cases, but the request and response format is always the same. The answer's decimal length and expected value range may differ depending on the feed. + +{/* prettier-ignore */} + + +## Before you begin + +If you are new to smart contract development, complete the [Deploy Your First Smart Contract](/quickstarts/deploy-your-first-contract) quickstart first. + +You will need: + +- [Node.js](https://nodejs.org/) v22.13.0 or later (required by Hardhat 3). +- A funded wallet on the **Sepolia** testnet. Get testnet ETH from a [Sepolia faucet](/resources/link-token-contracts/#sepolia-testnet). +- A Sepolia RPC URL (e.g. from a [node provider](https://ethereum.org/en/developers/docs/nodes-and-clients/nodes-as-a-service/)). +- A funded deployer private key for Sepolia. + +{/* prettier-ignore */} + + +{/* prettier-ignore */} + + +## Getting the feed address + +Before we even begin, we need to know the address of the feed we want to read. The [Price Feed Addresses](/data-feeds/price-feeds/addresses) page lists all the feeds available on each network. For this guide, we will use the BTC / USD feed on Sepolia, with the proxy address: + +## Retrieving the price data from the feed + + +You can read Data Feeds directly from the feed proxy without deploying any consumer contract. This is useful for backends, bots, dashboards, and pre-trade checks. Meaning it's as simple as just calling the feed proxy contract and reading the latest answer. + + + +Install ethers in an empty directory: + +```bash +npm install ethers +``` + +Save the following snippet below as `readFeed.js`: + +```javascript +const { ethers } = require("ethers") + +const provider = new ethers.JsonRpcProvider(process.env.SEPOLIA_RPC_URL) +const feed = new ethers.Contract( + "0x1b44F3514812d835EB1BDB0acB33d3fA3351Ee43", + [ + "function latestRoundData() view returns (uint80, int256, uint256, uint256, uint80)", + "function decimals() view returns (uint8)", + ], + provider +) + +async function main() { + const { answer } = await feed.latestRoundData() + const decimals = await feed.decimals() + console.log("Latest answer (raw):", answer.toString()) + console.log("Price (USD):", Number(answer) / 10 ** Number(decimals)) +} + +main().catch(console.error) +``` + +Run it with your Sepolia RPC URL: + +```bash +SEPOLIA_RPC_URL=your_sepolia_rpc_url node readFeed.js +``` + + + + + +```bash +npx hardhat console --network sepolia +``` + +In Hardhat 3, obtain `ethers` from `network.create()` first, then read the feed directly from the proxy: + +```javascript +const { ethers } = await network.create() +const feed = await ethers.getContractAt( + [ + "function latestRoundData() view returns (uint80 roundId, int256 answer, uint256 startedAt, uint256 updatedAt, uint80 answeredInRound)", + "function decimals() view returns (uint8)", + ], + "0x1b44F3514812d835EB1BDB0acB33d3fA3351Ee43" +) +const { answer } = await feed.latestRoundData() +const decimals = await feed.decimals() +console.log("Latest answer (raw):", answer.toString()) +console.log("Price (USD):", Number(answer) / 10 ** Number(decimals)) +``` + + + +The BTC / USD feed returns `8` for decimals. Divide the raw integer answer by `10 ** decimals` to get the human-readable price. For example, an answer of `3030914000000` with 8 decimals is `30309.14` USD. + + + + + + + +The example contract below reads the latest answer from the [BTC / USD feed](/data-feeds/price-feeds/addresses) on Sepolia. You can modify it to read any of the [Types of Data Feeds](/data-feeds#types-of-data-feeds). + +{/* */} + +```solidity filename='contracts/DataFeeds/DataConsumerV3.sol' +// SPDX-License-Identifier: MIT +pragma solidity ^0.8.7; + +import {AggregatorV3Interface} from "@chainlink/contracts/src/v0.8/shared/interfaces/AggregatorV3Interface.sol"; + +/** + * 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. + */ + +/** + * If you are reading data feeds on L2 networks, you must + * check the latest answer from the L2 Sequencer Uptime + * Feed to ensure that the data is accurate in the event + * of an L2 sequencer outage. See the + * https://docs.chain.link/data-feeds/l2-sequencer-feeds + * page for details. + */ +contract DataConsumerV3 { + AggregatorV3Interface internal dataFeed; + + /** + * Network: Sepolia + * Aggregator: BTC/USD + * Address: 0x1b44F3514812d835EB1BDB0acB33d3fA3351Ee43 + */ + constructor() { + dataFeed = AggregatorV3Interface(0x1b44F3514812d835EB1BDB0acB33d3fA3351Ee43); + } + + /** + * Returns the latest answer. + */ + function getChainlinkDataFeedLatestAnswer() public view returns (int256) { + // prettier-ignore + ( + /* uint80 roundId */ + , + int256 answer, + /*uint256 startedAt*/ + , + /*uint256 updatedAt*/ + , + /*uint80 answeredInRound*/ + ) = dataFeed.latestRoundData(); + return answer; + } +} +``` + +The contract has the following components: + +- The `import` line brings in [`AggregatorV3Interface`](https://github.com/smartcontractkit/chainlink-evm/blob/contracts-v1.5.0/contracts/src/v0.8/shared/interfaces/AggregatorV3Interface.sol) + - It exposes `latestRoundData()`, `getRoundData()`, `decimals()`, and `version()`. The sample uses `latestRoundData` to fetch the current price. +- The `constructor()` + - Initializes a `dataFeed` object that uses `AggregatorV3Interface` pointing at the proxy aggregator deployed at . + - This is the proxy address for the Sepolia `BTC / USD` feed. The proxy lets the aggregator be upgraded without breaking consumer contracts. +- The `getChainlinkDataFeedLatestAnswer()` function + - Calls your `dataFeed` object and runs the `latestRoundData()` function and returns the `answer` variable. + - When you deploy the contract, it initializes the `dataFeed` object to point to the aggregator at , 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 `getChainlinkDataFeedLatestAnswer()` returns only the `answer` variable. The full response includes `roundId`, `startedAt`, `updatedAt`, and `answeredInRound` — see the [API Reference](/data-feeds/api-reference) for details. + + + + + +1. Create a new Hardhat 3 project and initialize it with the Mocha + Ethers.js template: + + ```bash + mkdir data-feeds-quickstart + cd data-feeds-quickstart + npm init -y + npm install --save-dev hardhat + npx hardhat --init --template mocha-ethers + ``` + +1. Install the Chainlink contracts npm package: + + ```bash + npm install @chainlink/contracts + ``` + + Hardhat resolves `@chainlink/contracts` from `node_modules` automatically — no remapping file needed (unlike Foundry). + +1. Create the directories for the sample consumer contract and deploy script: + + ```bash + mkdir -p contracts/DataFeeds scripts/DataFeeds + ``` + +1. Create the following files and paste in the code from the rendered code blocks on this page: + + - Create `contracts/DataFeeds/DataConsumerV3.sol` and paste in the contract from [Step 2.1: Examine the sample contract](#examine-the-sample-contract). + - Create `scripts/DataFeeds/DeployAndReadDataConsumerV3.js` and paste in the script from [Step 2.3: Deploy the contract with a Hardhat script](#deploy-with-hardhat-script). + + Make sure the filenames match exactly — Hardhat looks for the contract in `contracts/` and the script in `scripts/`. + +1. Configure your `hardhat.config.ts` to compile the Chainlink contracts and use Sepolia. Replace its contents with: + + ```typescript filename='hardhat.config.ts' + import hardhatToolboxMochaEthersPlugin from "@nomicfoundation/hardhat-toolbox-mocha-ethers" + import { configVariable, defineConfig } from "hardhat/config" + + export default defineConfig({ + plugins: [hardhatToolboxMochaEthersPlugin], + solidity: { + profiles: { + default: { + version: "0.8.28", + }, + production: { + version: "0.8.28", + settings: { + optimizer: { enabled: true, runs: 200 }, + }, + }, + }, + }, + networks: { + hardhatMainnet: { + type: "edr-simulated", + chainType: "l1", + }, + hardhatOp: { + type: "edr-simulated", + chainType: "op", + }, + sepolia: { + type: "http", + chainType: "l1", + url: configVariable("SEPOLIA_RPC_URL"), + accounts: [configVariable("SEPOLIA_PRIVATE_KEY")], + }, + }, + }) + ``` + +1. Set your Sepolia RPC URL and deployer private key as environment variables (or store them in the Hardhat keystore as noted above): + + ```bash + export SEPOLIA_RPC_URL=your_sepolia_rpc_url + export SEPOLIA_PRIVATE_KEY=your_deployer_private_key + ``` + +1. Verify the project compiles: + + ```bash + npx hardhat compile + ``` + + You should see `Compiled 2 Solidity files with solc 0.8.28`. If you see an import error, check that `@chainlink/contracts` is installed (step 2) and that the contract is under `contracts/`. + + + + + +The deploy script (`scripts/DataFeeds/DeployAndReadDataConsumerV3.js`) deploys `DataConsumerV3` and immediately reads the latest price through it. For reference, here is the script: + +{/* */} + +```javascript filename='scripts/DataFeeds/DeployAndReadDataConsumerV3.js' +import { network } from "hardhat" + +/** + * THIS IS EXAMPLE CODE THAT USES HARDCODED VALUES FOR CLARITY. + * THIS IS EXAMPLE CODE THAT USES UN-AUDITED CODE. + * DO NOT USE THIS CODE IN PRODUCTION. + */ + +const { ethers } = await network.create() + +async function main() { + // 1. Deploy the DataConsumerV3 contract + const consumer = await ethers.deployContract("DataConsumerV3") + await consumer.waitForDeployment() + + const consumerAddress = await consumer.getAddress() + console.log("DataConsumerV3 deployed at:", consumerAddress) + + // 2. Read the latest price through the consumer contract + const answer = await consumer.getChainlinkDataFeedLatestAnswer() + console.log("Latest answer (raw):", answer.toString()) + + // 3. Read decimals directly from the feed to scale the answer + // Sepolia BTC / USD price feed proxy address + const feedAddress = "0x1b44F3514812d835EB1BDB0acB33d3fA3351Ee43" + const AggregatorV3Interface = [ + { + inputs: [], + name: "decimals", + outputs: [{ internalType: "uint8", name: "", type: "uint8" }], + stateMutability: "view", + type: "function", + }, + ] + const feed = await ethers.getContractAt(AggregatorV3Interface, feedAddress) + const decimals = await feed.decimals() + console.log("Decimals:", decimals) + + // 4. Scale and print the human-readable price + const scaled = Number(answer) / 10 ** Number(decimals) + console.log("Latest price (USD):", scaled) +} + +main().catch((error) => { + console.error(error) + process.exit(1) +}) +``` + +Run it against Sepolia: + +```bash +npx hardhat run scripts/DataFeeds/DeployAndReadDataConsumerV3.js --network sepolia +``` + +The script logs the deployed contract address, the raw integer answer, the feed's decimals, and the human-readable price. + +Save the deployed contract address for the next step. + + + + + +Open a Hardhat console against Sepolia: + +```bash +npx hardhat console --network sepolia +``` + +In Hardhat 3, obtain `ethers` from `network.create()` at the prompt, then read through your consumer. Replace `0xYOUR_CONSUMER_ADDRESS` with the address the deploy script logged in the previous step: + +```javascript +const { ethers } = await network.create() +const consumer = await ethers.getContractAt("DataConsumerV3", "0xYOUR_CONSUMER_ADDRESS") +const answer = await consumer.getChainlinkDataFeedLatestAnswer() +console.log("Latest answer (raw):", answer.toString()) +``` + +Read the feed's decimals directly to scale the answer yourself: + +```javascript +const feed = await ethers.getContractAt( + ["function decimals() view returns (uint8)"], + "0x1b44F3514812d835EB1BDB0acB33d3fA3351Ee43" +) +const decimals = await feed.decimals() +console.log("Decimals:", decimals) +``` + +The BTC / USD feed returns `8` for decimals. To convert the raw integer answer to a human-readable price, divide by `10 ** decimals`. For example, an answer of `3030914000000` with 8 decimals is `30309.14` USD. + +{/* prettier-ignore */} + + + + + + +## Before you go to production + +The example intentionally omits the safety checks a production integration needs. Before shipping, review the following points and the [Developer Responsibilities](/data-feeds/developer-responsibilities) page. + +### Check `updatedAt` and staleness + +`latestRoundData()` returns `updatedAt` (the timestamp of the latest round) and `answeredInRound` (the round in which the answer was finalized). Always verify the feed is fresh: + +```solidity +(uint80 roundId, int256 answer, , uint256 updatedAt, uint80 answeredInRound) = dataFeed.latestRoundData(); + +require(answeredInRound >= roundId, "Stale price"); +require(block.timestamp - updatedAt < TIMEOUT, "Stale price"); +``` + +Choose a `TIMEOUT` that matches your application's risk tolerance — shorter for trading, longer for less time-sensitive use cases. + +### Use the right feed for your asset + +Not all feeds are equal. Low-liquidity assets are more exposed to market manipulation. Review [Selecting Quality Data Feeds](/data-feeds/selecting-data-feeds) and the [Data Feed Categories](/data-feeds/selecting-data-feeds#data-feed-categories) before choosing a feed. + +### Handle L2 sequencer risk + +On L2s, a sequencer outage can cause stale or incorrect prices. Always pair L2 price feeds with a check on the [L2 Sequencer Uptime Feed](/data-feeds/l2-sequencer-feeds). The `DataConsumerWithSequencerCheck` sample shows the pattern. Try it out in Remix below: + + + +### Audit your integration + +The sample code is unaudited and hardcodes values for clarity. Before production, complete your own audit, review your dependencies, and apply the risk-mitigation practices described in [Developer Responsibilities](/data-feeds/developer-responsibilities). + +## FAQ + +### Do I need a consumer contract to read a Data Feed? + +**Only if another smart contract needs the price onchain.** A consumer contract exists to wrap a feed read in your own contract's logic so that _your other contracts_ can use the price onchain — for collateral checks, settlements, circuit breakers, and so on. The read is atomic with your onchain action and verifiable on the blockchain. + +If you only need the price in an offchain system (a backend, bot, dashboard, or pre-trade check), you do **not** need a consumer contract. The feed proxy is a public contract and `latestRoundData()` is a `view` function — anyone can call it directly from a script using ethers.js, viem, or `cast`. See [Step 1: Fetching price data offchain](#read-offchain) on this page. + +| | Consumer contract (onchain) | Direct read (offchain) | +| ------------------------------- | ------------------------------------- | ------------------------------------ | +| **Who needs the price?** | Another smart contract | A script, backend, bot, or dashboard | +| **Gas cost?** | Pay to deploy + gas for onchain reads | Free (view calls from a script) | +| **Deployment required?** | Yes | No | +| **Atomic with onchain action?** | Yes | No | diff --git a/src/content/data-feeds/getting-started-remix.mdx b/src/content/data-feeds/getting-started-remix.mdx new file mode 100644 index 00000000000..3f4f96dee0c --- /dev/null +++ b/src/content/data-feeds/getting-started-remix.mdx @@ -0,0 +1,270 @@ +--- +section: dataFeeds +date: Last Modified +title: "Getting Started with Data Feeds (using Remix)" +metadata: + title: "Getting Started with Chainlink Data Feeds — Low code (Remix)" + description: "Read Chainlink Data Feeds in a smart contract using the Remix IDE. Deploy a consumer contract on Sepolia and read the BTC/USD price feed — no local installation required." + excerpt: "Deploy a consumer contract and read Data Feeds onchain using Remix" + image: "/files/1a63254-link.png" + difficulty: "beginner" + estimatedTime: "15 minutes" + datePublished: "2026-07-22" + lastModified: "2026-07-22" +whatsnext: + { + "Read Data Feeds on other EVM chains and with other Web3 libraries": "/data-feeds/using-data-feeds", + "Retrieve Historical Price Data": "/data-feeds/historical-data", + "Read the Data Feeds API Reference": "/data-feeds/api-reference", + "Find Price Feed addresses on other networks": "/data-feeds/price-feeds/addresses", + } +--- + +import { Accordion, Aside, CodeSample, CopyText, ClickToZoom, PageTabs } from "@components" + +Chainlink Data Feeds are the fastest way to connect your smart contracts to real-world data such as asset prices, reserve balances, and L2 sequencer health. Each feed is aggregated by many independent Chainlink node operators and published onchain through a decentralized oracle network, giving your contracts a reliable, manipulation-resistant source of data. + +Each price feed has an onchain address and functions that enable contracts to read pricing data from that address. + +In this guide you will fetch the pricing data from a price feed, for example the [BTC / USD feed](https://data.chain.link/feeds/ethereum/mainnet/btc-usd), using the [Remix IDE](https://remix.ethereum.org/) — no local installation required. + +## What you'll do + +- Deploy and retrieve the latest price onchain using a Solidity consumer contract that reads the BTC / USD price feed on Sepolia. _(Onchain methods are useful for when you need to apply smart contract logic in your application based on the pricing data.)_ +- Learn the key safety checks to apply before moving to production. + +**Note:** The code for reading Data Feeds on Ethereum and other EVM-compatible blockchains is the same for every chain and every feed type. You choose different feeds for different use cases, but the request and response format is always the same. The answer's decimal length and expected value range may differ depending on the feed. + + + +{/* prettier-ignore */} + + +## Before you begin + +If you are new to smart contract development, complete the [Deploy Your First Smart Contract](/quickstarts/deploy-your-first-contract) quickstart first. It walks you through installing and funding a MetaMask wallet and using Remix, which this guide assumes you already know. + +You will need: + +- A funded wallet on the **Sepolia** testnet (chain ID `11155111`). Get testnet ETH from a [Sepolia faucet](/resources/link-token-contracts/#sepolia-testnet). +- The [Remix IDE](https://remix.ethereum.org/) open in your browser. No local installation required. +- MetaMask configured for Sepolia. + +{/* prettier-ignore */} + + +## Getting the feed address + +Before we even begin, we need to know the address of the feed we want to read. The [Price Feed Addresses](/data-feeds/price-feeds/addresses) page lists all the feeds available on each network. For this guide, we will use the BTC / USD feed on Sepolia, with the proxy address: + +## Retrieving the price data from the feed + + +You can read Data Feeds directly from the feed proxy without deploying any consumer contract. This is useful for backends, bots, dashboards, and pre-trade checks. No consumer contract is required — the feed proxy is a public contract and `latestRoundData()` is a `view` function, so anyone can call it directly from a script or CLI. + +You can check our [Foundry](/data-feeds/getting-started) or [Hardhat](/data-feeds/getting-started-hardhat) getting started guides to learn how to read Data Feeds offchain. + + + + + + + +The example contract below reads the latest answer from the [BTC / USD feed](/data-feeds/price-feeds/addresses) on Sepolia. It targets Solidity `^0.8.7`. You can modify it to read any of the [Types of Data Feeds](/data-feeds#types-of-data-feeds). + + + +The contract has the following components: + +- The `import` line brings in [`AggregatorV3Interface`](https://github.com/smartcontractkit/chainlink-evm/blob/contracts-v1.5.0/contracts/src/v0.8/shared/interfaces/AggregatorV3Interface.sol) + - It exposes `latestRoundData()`, `getRoundData()`, `decimals()`, and `version()`. The sample uses `latestRoundData` to fetch the current price. +- The `constructor()` + - Initializes a `dataFeed` object that uses `AggregatorV3Interface` pointing at the proxy aggregator deployed at . + - This is the proxy address for the Sepolia `BTC / USD` feed. The proxy lets the aggregator be upgraded without breaking consumer contracts. +- The `getChainlinkDataFeedLatestAnswer()` function + - Calls your `dataFeed` object and runs the `latestRoundData()` function and returns the `answer` variable. + - When you deploy the contract, it initializes the `dataFeed` object to point to the aggregator at , 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 `getChainlinkDataFeedLatestAnswer()` returns only the `answer` variable. The full response includes `roundId`, `startedAt`, `updatedAt`, and `answeredInRound` — see the [API Reference](/data-feeds/api-reference) for details. + + + + + +1. [Open the example contract](https://remix.ethereum.org/#url=https://docs.chain.link/samples/DataFeeds/DataConsumerV3.sol) in Remix. Remix loads the file and its imports automatically. + + {/* prettier-ignore */} +
+ Open the contract in Remix +
+ +1. Navigate to the **Solidity Compiler** tab on Remix left sidebar. + + + +1. Keep the default compiler settings and click **Compile DataConsumerV3.sol**. Remix auto-detects the compiler version from the `pragma` statement. You can ignore warnings about unused local variables — the example destructures `latestRoundData()` but only uses `answer`. + + + + + + + +1. Open MetaMask and switch to the **Sepolia** network. If you don't have it configured, you can find the chain ID and RPC details on the [LINK Token Contracts](/resources/link-token-contracts#sepolia-testnet) page. + +1. Open the **Deploy & Run Transactions** tab on Remix and set the **Environment** to **Browser Extension** and then select **Sepolia Testnet - MetaMask**. We do this becuase the contract must run in a Web3 context because it reads from another onchain contract (the price feed). Running in the "Remix VM" will not work. + + + + +1. In the **Contract** dropdown, explicitly select `DataConsumerV3`. This is the contract we want to deploy. Ensure you have this selected. Finally, click **Deploy** to deploy the contract to Sepolia. + + + +1. MetaMask opens and asks confirmation for the deployment transaction. In the MetaMask prompt, click **Confirm** to approve the transaction. This will result in an actual onchain transaction that deploys the contract to Sepolia. + +_Note: You will pay gas for this transaction, so ensure your wallet has enough Sepolia ETH._ + + + +1. After a few seconds, the transaction completes and your contract appears under **Deployed Contracts** in Remix. Click the contract dropdown to expand its available variables and functions. + + + + + + + +1. Find the function **getChainlinkDataFeedLatestAnswer** in the function selector and then click it to call the function. The latest answer from the aggregator appears just above the button. + + + + +1. The returned answer is an integer with no decimal point. The BTC / USD feed uses **8 decimals**, so an answer of `7836308000000` represents a BTC / USD price of `78363.08`. Each feed uses a different number of decimals — you can find the exact value on the [Price Feed Addresses](/data-feeds/price-feeds/addresses) and checking the **More Details** checkbox. You can also call the `decimals()` function on the feed to get the decimal count programmatically. + +{/* prettier-ignore */} + + + + + + +## Before you go to production + +The example intentionally omits the safety checks a production integration needs. Before shipping, review the following points and the [Developer Responsibilities](/data-feeds/developer-responsibilities) page. + +### Check `updatedAt` and staleness + +`latestRoundData()` returns `updatedAt` (the timestamp of the latest round) and `answeredInRound` (the round in which the answer was finalized). Always verify the feed is fresh: + +```solidity +(uint80 roundId, int256 answer, , uint256 updatedAt, uint80 answeredInRound) = dataFeed.latestRoundData(); + +require(answeredInRound >= roundId, "Stale price"); +require(block.timestamp - updatedAt < TIMEOUT, "Stale price"); +``` + +Choose a `TIMEOUT` that matches your application's risk tolerance — shorter for trading, longer for less time-sensitive use cases. + +### Use the right feed for your asset + +Not all feeds are equal. Low-liquidity assets are more exposed to market manipulation. Review [Selecting Quality Data Feeds](/data-feeds/selecting-data-feeds) and the [Data Feed Categories](/data-feeds/selecting-data-feeds#data-feed-categories) before choosing a feed. + +### Handle L2 sequencer risk + +On L2s, a sequencer outage can cause stale or incorrect prices. Always pair L2 price feeds with a check on the [L2 Sequencer Uptime Feed](/data-feeds/l2-sequencer-feeds). The `DataConsumerWithSequencerCheck` sample shows the pattern. Try it out in Remix below: + + + +### Audit your integration + +The sample code is unaudited and hardcodes values for clarity. Before production, complete your own audit, review your dependencies, and apply the risk-mitigation practices described in [Developer Responsibilities](/data-feeds/developer-responsibilities). + +## FAQ + +### Do I need a consumer contract to read a Data Feed? + +**Only if another smart contract needs the price onchain.** A consumer contract exists to wrap a feed read in your own contract's logic so that _your other contracts_ can use the price onchain — for collateral checks, settlements, circuit breakers, and so on. The read is atomic with your onchain action and verifiable on the blockchain. + +If you only need the price in an offchain system (a backend, bot, dashboard, or pre-trade check), you do **not** need a consumer contract. The feed proxy is a public contract and `latestRoundData()` is a `view` function — anyone can call it directly from a script using `cast`, ethers.js, or viem. See [Step 1: Fetching price data offchain](#read-offchain) on this page, or the [Foundry](/data-feeds/getting-started#read-offchain) and [Hardhat](/data-feeds/getting-started-hardhat#read-offchain) offchain read sections. + +| | Consumer contract (onchain) | Direct read (offchain) | +| ------------------------------- | ------------------------------------- | ------------------------------------ | +| **Who needs the price?** | Another smart contract | A script, backend, bot, or dashboard | +| **Gas cost?** | Pay to deploy + gas for onchain reads | Free (view calls from a script) | +| **Deployment required?** | Yes | No | +| **Atomic with onchain action?** | Yes | No | + +### Remix says "contract not found" when deploying + +In the **Contract** dropdown on the Deploy & Run Transactions tab, explicitly select `DataConsumerV3`. When a file has multiple imports, Remix defaults to the first contract alphabetically, which may not be the one you want to deploy. + +### The MetaMask transaction reverted on deployment + +Make sure MetaMask is set to the **Sepolia** network (chain ID `11155111`) before confirming. If you're on another network, the deployment will revert or land on the wrong chain. Also confirm your wallet has enough testnet ETH to cover gas — check a [Sepolia faucet](/resources/link-token-contracts/#sepolia-testnet) if needed. diff --git a/src/content/data-feeds/getting-started.mdx b/src/content/data-feeds/getting-started.mdx index b16bb304e4b..14d055897e5 100644 --- a/src/content/data-feeds/getting-started.mdx +++ b/src/content/data-feeds/getting-started.mdx @@ -1,28 +1,60 @@ --- section: dataFeeds date: Last Modified -title: "Consuming Data Feeds" +title: "Getting Started with Data Feeds" +metadata: + title: "Getting Started with Chainlink Data Feeds — Foundry" + description: "Read Chainlink Data Feeds using the Foundry CLI. Deploy a consumer contract on Sepolia with forge, read the BTC/USD price feed onchain, and read feeds offchain with cast call." + excerpt: "Deploy a consumer contract with forge and read Data Feeds with cast" + image: "/files/1a63254-link.png" + difficulty: "beginner" + estimatedTime: "15 minutes" whatsnext: { - "See examples for how to read feeds onchain and offchain": "/data-feeds/using-data-feeds", - "Learn how to retrieve Historical Price Data": "/data-feeds/historical-data", + "Read Data Feeds on other EVM chains and with other Web3 libraries": "/data-feeds/using-data-feeds", + "Retrieve Historical Price Data": "/data-feeds/historical-data", "Read the Data Feeds API Reference": "/data-feeds/api-reference", + "Find Price Feed addresses on other networks": "/data-feeds/price-feeds/addresses", } -metadata: - title: "Consuming Data Feeds" - description: "Learn how to consume Chainlink Data Feeds in your smart contracts." - excerpt: "Smart Contracts and Chainlink" - image: "/files/1a63254-link.png" --- -import { Aside, CodeSample } from "@components" +import { Accordion, CodeSample, ClickToZoom, CopyText, Aside, PageTabs } from "@components" + +Chainlink Data Feeds are the fastest way to connect your smart contracts to real-world data such as asset prices, reserve balances, and L2 sequencer health. Each feed is aggregated by many independent Chainlink node operators and published onchain through a decentralized oracle network, giving your contracts a reliable, manipulation-resistant source of data. -You can use Chainlink Data Feeds to connect your smart contracts to asset pricing data like the [ETH / USD feed](https://data.chain.link/feeds/ethereum/mainnet/eth-usd). These data feeds use data aggregated from many independent Chainlink node operators. Each price feed has an onchain address and functions that enable contracts to read pricing data from that address. +Each price feed has an onchain address and functions that enable contracts to read pricing data from that address. -This guide shows you how to read Data Feeds and store the value onchain using Solidity. To learn how to read feeds offchain or use different languages, see the [Using Data Feeds on EVM Chains](/data-feeds/using-data-feeds) guide. Alternatively, you can also learn how to use Data Feeds on [Solana](/data-feeds/solana) or [StarkNet](/data-feeds/starknet). +In this guide you will fetch the pricing data from a price feed, for example the [BTC / USD feed](https://data.chain.link/feeds/ethereum/mainnet/btc-usd). -The code for reading Data Feeds on Ethereum or other EVM-compatible blockchains is the same for each chain and each Data Feed types. You choose different types of feeds for different uses, but the request and response format are the same. The answer decimal length and expected value ranges might change depending on what feed you use. + +## What you'll do + +- Retrieve latest pricing data from the BTC / USD price feed offchain directly from the feed proxy. _(Offchain methods are useful for backends, bots, dashboards, and pre-trade checks)_ +- Deploy and retrieve the latest price onchain using a Solidity consumer contract that reads the BTC / USD price feed on Sepolia. _(Onchain methods are useful for when you need to apply smart contract logic in your application based on the pricing data.)_ +- Learn the key safety checks to apply before moving to production. + +**Note:** The code for reading Data Feeds on Ethereum and other EVM-compatible blockchains is the same for every chain and every feed type. You choose different feeds for different use cases, but the request and response format is always the same. The answer's decimal length and expected value range may differ depending on the feed. + +{/* prettier-ignore */}