{"id":13511867,"url":"https://github.com/smartcontractkit/hardhat-starter-kit","last_synced_at":"2025-05-15T12:05:50.617Z","repository":{"id":37551870,"uuid":"350740340","full_name":"smartcontractkit/hardhat-starter-kit","owner":"smartcontractkit","description":"A repo for boilerplate code for testing, deploying, and shipping chainlink solidity code. ","archived":false,"fork":false,"pushed_at":"2025-05-08T18:07:37.000Z","size":67827,"stargazers_count":1254,"open_issues_count":24,"forks_count":496,"subscribers_count":25,"default_branch":"main","last_synced_at":"2025-05-08T19:25:08.330Z","etag":null,"topics":["chainlink","hardhat","javascript"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/smartcontractkit.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-03-23T14:20:56.000Z","updated_at":"2025-05-08T18:07:38.000Z","dependencies_parsed_at":"2024-05-09T04:30:02.014Z","dependency_job_id":"03e2534f-5ba2-4db0-a9e5-ac3d49105654","html_url":"https://github.com/smartcontractkit/hardhat-starter-kit","commit_stats":null,"previous_names":[],"tags_count":3,"template":true,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smartcontractkit%2Fhardhat-starter-kit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smartcontractkit%2Fhardhat-starter-kit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smartcontractkit%2Fhardhat-starter-kit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smartcontractkit%2Fhardhat-starter-kit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/smartcontractkit","download_url":"https://codeload.github.com/smartcontractkit/hardhat-starter-kit/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254337613,"owners_count":22054253,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["chainlink","hardhat","javascript"],"created_at":"2024-08-01T03:01:14.622Z","updated_at":"2025-05-15T12:05:45.607Z","avatar_url":"https://github.com/smartcontractkit.png","language":"JavaScript","funding_links":[],"categories":["JavaScript","Web 3.0"],"sub_categories":[],"readme":"\u003cbr/\u003e\n\u003cp align=\"center\"\u003e\n\u003ca href=\"https://chain.link\" target=\"_blank\"\u003e\n\u003cimg src=\"./box-img-lg.png\" width=\"225\" alt=\"Chainlink Hardhat logo\"\u003e\n\u003c/a\u003e\n\u003c/p\u003e\n\u003cbr/\u003e\n \n ## Tip\n\u003e Please be attention that Chainlink Any API is removed from this starter kit because Chainlink Any API is currently replaced by [Chainlink Functions](https://docs.chain.link/chainlink-functions). Please find the starter kit for Chainlink Functions [here](https://github.com/smartcontractkit/functions-hardhat-starter-kit)\n\n[![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/smartcontractkit/hardhat-starter-kit)\n\n[![GitPOAP Badge](https://public-api.gitpoap.io/v1/repo/smartcontractkit/hardhat-starter-kit/badge)](https://www.gitpoap.io/gp/649)\n\n- [Chainlink Hardhat Starter Kit](#chainlink-hardhat-starter-kit)\n- [Getting Started](#getting-started)\n  - [Requirements](#requirements)\n  - [Quickstart](#quickstart)\n    - [Typescript](#typescript)\n- [Usage](#usage)\n  - [Deploying Contracts](#deploying-contracts)\n  - [Run a Local Network](#run-a-local-network)\n  - [Using a Testnet or Live Network (like Mainnet or Polygon)](#using-a-testnet-or-live-network-like-mainnet-or-polygon)\n    - [Sepolia Ethereum Testnet Setup](#sepolia-ethereum-testnet-setup)\n  - [Forking](#forking)\n  - [Auto-Funding](#auto-funding)\n- [Test](#test)\n- [Interacting with Deployed Contracts](#interacting-with-deployed-contracts)\n  - [Chainlink Price Feeds](#chainlink-price-feeds)\n  - [Request \u0026 Receive Data](#request--receive-data)\n  - [VRF Get a random number](#vrf-get-a-random-number)\n  - [Automation](#automation)\n  - [Verify on Etherscan](#verify-on-etherscan)\n- [Linting](#linting)\n- [Code Formatting](#code-formatting)\n- [Estimating Gas](#estimating-gas)\n- [Code Coverage](#code-coverage)\n- [Fuzzing](#fuzzing)\n- [Contributing](#contributing)\n- [Thank You!](#thank-you)\n  - [Resources](#resources)\n\n# Chainlink Hardhat Starter Kit\n Implementation of the following 3 Chainlink features using the [Hardhat](https://hardhat.org/) development environment:\n - [Chainlink Price Feeds](https://docs.chain.link/docs/using-chainlink-reference-contracts)\n - [Chainlink VRF](https://docs.chain.link/docs/chainlink-vrf)\n - [Chainlink Automation](https://docs.chain.link/chainlink-automation/introduction)\n \n\n For [Chainlink Functions](https://docs.chain.link/chainlink-functions) please go to these tarter kits: [Hardhat](https://github.com/smartcontractkit/functions-hardhat-starter-kit)  |  [Foundry (coming soon)](https://github.com/smartcontractkit/functions-foundry-starter-kit)\n\nFor [Chainlink CCIP (Cross Chain Interoperability Prototocol)](https://docs.chain.link/ccip) please go to these starter kits: [Hardhat](https://github.com/smartcontractkit/ccip-starter-kit-hardhat) | [Foundry](https://github.com/smartcontractkit/ccip-starter-kit-foundry)\n\n# Getting Started \n\nIt's recommended that you've gone through the [hardhat getting started documentation](https://hardhat.org/getting-started/) before proceeding here. \n\n## Requirements\n\n- [git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)\n  - You'll know you did it right if you can run `git --version` and see a response like `git version x.x.x`\n- [Nodejs](https://nodejs.org/en/)\n  - You'll know you've installed nodejs right if you can run:\n    - `node --version` and get an output like: `vx.x.x`\n- [Yarn](https://classic.yarnpkg.com/lang/en/docs/install/) instead of `npm`\n  - You'll know you've installed yarn right if you can run:\n    - `yarn --version` And get an output like: `x.x.x`\n    - You might need to install it with npm\n\n\u003e If you're familiar with `npx` and `npm` instead of `yarn`, you can use `npx` for execution and `npm` for installing dependencies. \n\n## Quickstart\n\n1. Clone and install dependencies\n\nAfter installing all the requirements, run the following:\n\n```bash\ngit clone https://github.com/smartcontractkit/hardhat-starter-kit/\ncd hardhat-starter-kit\n```\nThen:\n```\nnpm install\n```\n\nThe recommendation is to use npm 7 or later. If you are using an older version of npm, you'll also need to install all the packages used by the toolbox.\n```\nnpm install --save-dev @nomicfoundation/hardhat-toolbox @nomicfoundation/hardhat-network-helpers @nomicfoundation/hardhat-chai-matchers @nomiclabs/hardhat-ethers @nomiclabs/hardhat-etherscan chai ethers hardhat-gas-reporter solidity-coverage @typechain/hardhat typechain @typechain/ethers-v5 @ethersproject/abi @ethersproject/providers\n```\n\nThat's also the case if you are using yarn.\n```\nyarn add --dev @nomicfoundation/hardhat-toolbox @nomicfoundation/hardhat-network-helpers @nomicfoundation/hardhat-chai-matchers @nomiclabs/hardhat-ethers @nomiclabs/hardhat-etherscan chai ethers hardhat-gas-reporter solidity-coverage @typechain/hardhat typechain @typechain/ethers-v5 @ethersproject/abi @ethersproject/providers\n```\n\n2. You can now do stuff!\n\n```\nnpx hardhat test\n```\n\nor\n\n```\nnpm run test\n```\n\nor\n\n```\nyarn test\n```\n\n### Typescript\n\nTo use typescript, run:\n\n```\ngit checkout typescript\nnpm install\n```\n\n# Usage\n\nIf you run `npx hardhat --help` you'll get an output of all the tasks you can run. \n\n## Deploying Contracts\n\n```\nnpm run deploy\n```\n\nThis will deploy your contracts to a local network. Additionally, if on a local network, it will deploy mock Chainlink contracts for you to interact with. If you'd like to interact with your deployed contracts, skip down to [Interacting with Deployed Contracts](#interacting-with-deployed-contracts).\n\n## Run a Local Network\n\nOne of the best ways to test and interact with smart contracts is by using a local network. To run a local network with all your contracts in it, execute the following command:\n\n```\nnpx hardhat node\n```\n\nYou'll get a local blockchain, private keys, contracts deployed (from the `deployment` folder scripts), and an endpoint to potentially add to an EVM wallet. \n\n## Using a Testnet or Live Network (like Mainnet or Polygon)\n\nIn your `hardhat.config.js` you'll see section like:\n\n```\nmodule.exports = {\n  defaultNetwork: \"hardhat\",\n  networks: {\n```\n\nThis section of the file is where you define which networks you want to interact with. You can read more about that whole file in the [hardhat documentation.](https://hardhat.org/config/)\n\nTo interact with a live or test network, you'll need:\n\n1. An rpc URL \n2. A Private Key\n3. ETH \u0026 LINK token (either testnet or real)\n\nLet's look at an example of setting these up using the Sepolia testnet. \n\n### Sepolia Ethereum Testnet Setup\n\nFirst, we will need to set environment variables. We can do so by setting them in our `.env` file (create it if it's not there). You can also read more about [environment variables](https://www.twilio.com/blog/2017/01/how-to-set-environment-variables.html) from the linked twilio blog. You'll find a sample of what this file will look like in `.env.example`\n\n\u003e IMPORTANT: MAKE SURE YOU'D DON'T EXPOSE THE KEYS YOU PUT IN THIS `.env` FILE. By that, I mean don't push them to a public repo, and please try to keep them keys you use in development not associated with any real funds. \n\n1. Set your `SEPOLIA_RPC_URL` [environment variable.](https://www.twilio.com/blog/2017/01/how-to-set-environment-variables.html)\n\nYou can get one for free from [Alchemy](https://www.alchemy.com/), [Infura](https://infura.io/), or [Moralis](https://moralis.io/speedy-nodes/). This is your connection to the blockchain. \n\n2. Set your `PRIVATE_KEY` environment variable. \n\nThis is your private key from your wallet, ie [MetaMask](https://metamask.io/). This is needed for deploying contracts to public networks. You can optionally set your `MNEMONIC` environment variable instead with some changes to the `hardhat.config.js`.\n\n![WARNING](https://via.placeholder.com/15/f03c15/000000?text=+) **WARNING** ![WARNING](https://via.placeholder.com/15/f03c15/000000?text=+)\n\nWhen developing, it's best practice to use a Metamask that isn't associated with any real money. A good way to do this is to make a new browser profile (on Chrome, Brave, Firefox, etc) and install Metamask on that browser, and never send this wallet money.  \n\nDon't commit and push any changes to .env files that may contain sensitive information, such as a private key! If this information reaches a public GitHub repository, someone can use it to check if you have any Mainnet funds in that wallet address, and steal them!\n\n`.env` example:\n```\nSEPOLIA_RPC_URL='https://sepolia.infura.io/v3/asdfadsfafdadf'\nPRIVATE_KEY='abcdef'\n```\n`bash` example:\n```\nexport SEPOLIA_RPC_URL='https://sepolia.infura.io/v3/asdfadsfafdadf'\nexport PRIVATE_KEY='abcdef'\n```\n\n\u003e You can also use a `MNEMONIC` instead of a `PRIVATE_KEY` environment variable by uncommenting the section in the `hardhat.config.js`, and commenting out the `PRIVATE_KEY` line. However this is not recommended. \n\nFor other networks like mainnet and polygon, you can use different environment variables for your RPC URL and your private key. See the `hardhat.config.js` to learn more. \n\n3. Get some Sepolia Testnet ETH and LINK \n\nHead over to the [Chainlink faucets](https://faucets.chain.link/) and get some ETH and LINK. Please follow [the chainlink documentation](https://docs.chain.link/docs/acquire-link/) if unfamiliar. \n\n4. Create VRF V2 subscription\n\nHead over to [VRF Subscription Page](https://vrf.chain.link/sepolia) and create the new subscription. Save your subscription ID and put it in `helper-hardhat-config.js` file as `subscriptionId`\n\n5. Running commands\n\nYou should now be all setup! You can run any command and just pass the `--network sepolia` now!\n\nTo deploy contracts:\n\n```\nnpm run deploy --network sepolia\n```\n\nTo run staging testnet tests\n```\nnpm run test-staging\n```\n\n## Forking \n \nIf you would like to run tests on a [forked network](https://hardhat.org/hardhat-network/guides/mainnet-forking.html), follow these steps: \n\n1. Set a `MAINNET_RPC_URL` environment variable that connects to the mainnet.\n2. Choose a block number to select a state of the network you are forking and set it as `FORKING_BLOCK_NUMBER` environment variable. If ignored, it will use the latest block each time which can lead to test inconsistency.\n3. Set `enabled` flag to `true`/`false` to enable/disable forking feature\n```\n      forking: {\n        url: MAINNET_RPC_URL,\n        blockNumber: FORKING_BLOCK_NUMBER,\n        enabled: false,\n      }\n```\n\n\n# Test\nTests are located in the [test](./test/) directory, and are split between unit tests and staging/testnet tests. Unit tests should only be run on local environments, and staging tests should only run on live environments.\n\nTo run unit tests:\n\n```\nnpx hardhat test\n```\n\nor\n\n```\nnpm run test\n```\n\nor\n\n```\nyarn test\n```\n\nTo run staging tests on Sepolia network:\n\n```\nnpx hardhat test --network sepolia\n```\nor\n```bash\nnpm run test-staging\n```\n\n## Performance optimizations\n\nSince all tests are written in a way to be independent from each other, you can save time by running them in parallel. Make sure that `AUTO_FUND=false` inside `.env` file. There are some limitations with parallel testing, read more about them [here](https://hardhat.org/guides/parallel-tests.html)\n\nTo run tests in parallel:\n```\nnpx hardhat test --parallel\n```\nor\n```\nnpm run test --parallel\n```\n\n# Interacting with Deployed Contracts\n\nAfter deploying your contracts, the deployment output will give you the contract addresses as they are deployed. You can then use these contract addresses in conjunction with Hardhat tasks to perform operations on each contract.\n\n\n## Chainlink Price Feeds\nThe Price Feeds consumer contract has one task, to read the latest price of a specified price feed contract\n\n```bash\nnpx hardhat read-price-feed --contract insert-contract-address-here --network network\n```\n\n\n## VRF Get a random number\nThe VRFConsumer contract has two tasks, one to request a random number, and one to read the result of the random number request. \nAs explained in the [developer documentation](https://docs.chain.link/vrf/v2/introduction), there are two methods:\n- The [Subscription method](https://docs.chain.link/vrf/v2/subscription)\n- The [Direct Funding method](https://docs.chain.link/vrf/v2/direct-funding)\n\nRead the docs first to understand which method is the most suitable for your use case.\n\n### VRF Subscription method\nTo start, go to [VRF Subscription Page](https://vrf.chain.link/sepolia) and create the new subscription. Save your subscription ID and put it in `helper-hardhat-config.js` file as `subscriptionId`:\n\n```javascript\n5: {\n    // rest of the config\n    subscriptionId: \"777\"\n}\n```\n\nThen, deploy your VRF V2 contract consumer to the network of your recent subscription using subscription id as constructor argument.\n\n```bash\nnpm run deploy --network network   \n```\n\nFinally, you need to go to your subscription page one more time and add the address of deployed contract as a new consumer. Once that's done, you can perform a VRF request with the request-random-number task:\n\n```bash\nnpx hardhat request-random-number --contract insert-contract-address-here --network network\n```\n\nOnce you have successfully made a request for a random number, you can see the result via the read-random-number task:\n\n```bash\nnpx hardhat read-random-number --contract insert-contract-address-here --network network\n```\n\n### VRF Direct Funding method\nDeploy your VRF V2 contract consumer to the network.\n\n```bash\nnpm run deploy --network network   \n```\n\nor (if you are using yarn)\n\n```bash\nyarn deploy --network network   \n```\n\nNow you have to fund your consumer contract with LINK tokens:\n\n```bash\nnpx hardhat transfer-link --recipient insert-contract-address-here --amount insert-amount-in-juels-here --network network\n```\n\nOnce that's done, you can perform a VRF request with the request-random-number task:\n\n```bash\nnpx hardhat request-random-number-direct-funding --callbackgaslimit insert-callback-gas-limit-here --requestconfirmations insert-request-confirmations-here --numwords insert-number-words-here --contract insert-contract-address-here --network network\n```\n\nOnce you have successfully made a request for a random number, you can see the result via the read-random-number task:\n\n```bash\nnpx hardhat read-random-number-direct-funding --contract insert-contract-address-here --network network\n```\n\n## Automation\nThe AutomationCounter contract is a simple Chainlink Automation enabled contract that simply maintains a counter variable that gets incremented each time the performUpkeep task is performed by a Chainlink Automation. Once the contract is deployed, you should head to [https://automation.chain.link/](https://automation.chain.link/) to register it for upkeeps, then you can use the task below to view the counter variable that gets incremented by Chainlink Automation\n\n\n```bash\nnpx hardhat read-automation-counter --contract insert-contract-address-here --network network\n```\n\n## Verify on Etherscan\n\nYou'll need an `ETHERSCAN_API_KEY` environment variable. You can get one from the [Etherscan API site.](https://etherscan.io/apis). If you have it set, your deploy script will try to verify them by default, but if you want to verify any manually, you can run: \n\n```\nnpx hardhat verify --network \u003cNETWORK\u003e \u003cCONTRACT_ADDRESS\u003e \u003cCONSTRUCTOR_PARAMETERS\u003e\n```\nexample:\n\n```\nnpx hardhat verify --network sepolia 0x9279791897f112a41FfDa267ff7DbBC46b96c296 \"0x694AA1769357215DE4FAC081bf1f309aDC325306\"\n```\n\n# Linting\n\nThis will [lint](https://stackoverflow.com/questions/8503559/what-is-linting) your smart contracts.  \n\n```\nnpm run lint:fix\n```\n\n# Code Formatting\n\nThis will format both your javascript and solidity to look nicer. \n\n```\nnpm run format\n```\n\n# Estimating Gas\n\nTo estimate gas, just set a `REPORT_GAS` environment variable to true, and then run:\n\n```\nnpx hardhat test\n```\n\nIf you'd like to see the gas prices in USD or other currency, add a `COINMARKETCAP_API_KEY` from [Coinmarketcap](https://coinmarketcap.com/api/documentation/v1/).\n\n# Code coverage\n\nTo see a measure in percent of the degree to which the smart contract source code is executed when a particular test suite is run, type\n```\nnpm run coverage\n```\n\n# Fuzzing\n\nWe are going to use Echidna as a Fuzz testing tool. You need to have [Docker](https://www.docker.com/) installed with at least 8GB virtual memory allocated (To update this parameter go to _Settings-\u003eResources-\u003eAdvanced-\u003eMemory_). \n\nTo start Echidna instance run\n\n```\nnpm run fuzzing\n```\n\nIf you are using it for the first time, you will need to wait for Docker to download [eth-security-toolbox](https://hub.docker.com/r/trailofbits/eth-security-toolbox) image for us.\n\nTo start Fuzzing run\n```\nechidna-test /src/contracts/test/fuzzing/AutomationCounterEchidnaTest.sol --contract AutomationCounterEchidnaTest --config /src/contracts/test/fuzzing/config.yaml\n```\n\nTo exit Echidna type\n```bash\nexit\n```\n\n# Contributing\n\nContributions are always welcome! Open a PR or an issue!\n\n# Thank You!\n\n## Resources\n\n- [Chainlink Documentation](https://docs.chain.link/)\n- [Hardhat Documentation](https://hardhat.org/getting-started/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmartcontractkit%2Fhardhat-starter-kit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsmartcontractkit%2Fhardhat-starter-kit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmartcontractkit%2Fhardhat-starter-kit/lists"}