Hardhat Developer Workflow¶
January 16, 2023 | by Kevin Neilson & Erin Shaben
Introduction¶
In this tutorial, we'll walk through the Hardhat development environment in the context of launching a pooled staking DAO contract. We'll walk through the typical developer workflow in detail from start to finish.
We'll assemble the components of the staking DAO and compile the necessary contracts. Then, we'll build a test suite with a variety of test cases relevant to our staking DAO, and run it against a local development node. Finally, we'll deploy the staking DAO to both Moonbase Alpha and Moonbeam and verify the contracts via the Hardhat Etherscan plugin. If this is your first time exploring Hardhat, you may wish to start with the introduction to Hardhat guide.
The information presented herein is for informational purposes only and has been provided by third parties. Moonbeam does not endorse any project listed and described on the Moonbeam docs website (https://docs.moonbeam.network/).
Checking Prerequisites¶
To get started, you will need the following:
- A Moonbase Alpha account funded with DEV. You can get DEV tokens for testing on Moonbase Alpha once every 24 hours from the Moonbase Alpha Faucet
- A Moonscan API Key
- For the Testing section you'll need to have a local Moonbeam node up and running
- To test out the examples in this guide on Moonbeam or Moonriver, you will need to have your own endpoint and API key which you can get from one of the supported Endpoint Providers.
Creating a Hardhat Project¶
You will need to create a Hardhat project if you don't already have one. You can create one by completing the following steps:
- Create a directory for your project
mkdir stakingDAO && cd stakingDAO
- Initialize the project which will create a
package.json
filenpm init -y
- Install Hardhat
npm install hardhat
-
Create a project
npx hardhat
Note
npx
is used to run executables installed locally in your project. Although Hardhat can be installed globally, it is recommended to install it locally in each project so that you can control the version on a project by project basis. -
A menu will appear which will allow you to create a new project or use a sample project. For this example, you can choose Create an empty hardhat.config.js
This will create a Hardhat config file (hardhat.config.js
) in your project directory.
Add Smart Contracts¶
The smart contract featured in this tutorial is more complex than the one in the Introduction to Hardhat but the nature of the contract means it's perfect to demonstrate some of the advanced capabilities of Hardhat. DelegationDAO.sol
is a pooled staking DAO that uses StakingInterface.sol
to autonomously delegate to a collator when it reaches a determined threshold. Pooled staking contracts such as DelegationDAO.sol
allow delegators with less than the protocol minimum bond to join together to delegate their pooled funds and earn a share of staking rewards.
Note
DelegationDAO.sol
is unreviewed and unaudited. It is designed only for demonstration purposes and not intended for production use. It may contain bugs or logic errors that could result in loss of funds.
To get started, take the following steps:
- Create a
contracts
directory to hold your project's smart contractsmkdir contracts
- Create a new file called
DelegationDAO.sol
touch contracts/DelegationDAO.sol
- Copy and paste the contents of DelegationDAO.sol into
DelegationDAO.sol
- Create a new file called
StakingInterface.sol
in thecontracts
directorytouch contracts/StakingInterface.sol
- Copy and paste the contents of StakingInterface.sol into
StakingInterface.sol
DelegationDAO.sol
relies on a couple of standard OpenZeppelin contracts. Add the library with the following command:npm install @openzeppelin/contracts
Hardhat Configuration File¶
Before you can deploy the contract to Moonbase Alpha, you'll need to modify the Hardhat configuration file and create a secure file to store your private keys and your Moonscan API key in.
You can create a secrets.json
file to store your private keys by running:
touch secrets.json
Then add your private keys for your two accounts on Moonbase Alpha. Since some of the testing will be done on a development node, you'll also need to add the private keys of two of the prefunded development node accounts, which for this example, we can use Alice and Bob. In addition, you'll add your Moonscan API key, which can be used for both Moonbase Alpha and Moonbeam.
Note
Any real funds sent to the Alice and Bob development accounts will be lost immediately. Take precautions to never send MainNet funds to exposed development accounts.
{
"privateKey": "YOUR-PRIVATE-KEY-HERE",
"privateKey2": "YOUR-SECOND-PRIVATE-KEY-HERE",
"alicePrivateKey": "0x5fb92d6e98884f76de468fa3f6278f8807c48bebc13595d45af5bdc4da702133",
"bobPrivateKey": "0x8075991ce870b93a8870eca0c0f91913d12f47948ca0fd25b49c6fa7cdbeee8b",
"moonbeamMoonscanAPIKey": "YOUR-MOONSCAN-API-KEY-HERE"
}
If you have separate accounts for Moonbeam MainNet, you can add them as separate variables or update the privateKey
and privateKey2
variables once you're ready to deploy to MainNet.
Your secrets.json
should resemble the following:
Make sure to add the file to your project's .gitignore
, and to never reveal your private key.
Remember
Please always manage your private keys with a designated secret manager or similar service. Never save or commit your private keys inside your repositories.
When setting up the hardhat.config.js
file, we'll need to import a few plugins that we'll use throughout this guide. So to get started, we'll need the Hardhat Toolbox plugin, which conveniently bundles together the packages that we'll need later on for testing. We'll also need the Hardhat Etherscan plugin, which we'll use to verify our contracts. Both of these plugins can be installed with the following command:
npm install --save-dev @nomicfoundation/hardhat-toolbox @nomiclabs/hardhat-etherscan
If you're curious about additional Hardhat plugins, here is a complete list of official Hardhat plugins.
Next you can take the following steps to modify the hardhat.config.js
file and add Moonbase Alpha as a network:
- Import plugins. The Hardhat Ethers plugin comes out of the box with Hardhat, so you don't need to worry about installing it yourself
- Import the
secrets.json
file - Inside the
module.exports
, you need to provide the Solidity version - Add the Moonbase Alpha network configuration
- Import your Moonscan API key, which is required for the verification steps we'll be taking later in this tutorial
// 1. Import the Ethers, Hardhat Toolbox, and Etherscan plugins
// required to interact with our contracts
require("@nomicfoundation/hardhat-toolbox");
require("@nomiclabs/hardhat-etherscan");
require('@nomiclabs/hardhat-ethers');
// 2. Import your private key from your pre-funded Moonbase Alpha testing
// account and your Moonscan API key
const { privateKey, privateKey2, moonbeamMoonscanAPIKey, alicePrivateKey, bobPrivateKey } = require('./secrets.json');
module.exports = {
// 3. Specify the Solidity version
solidity: "0.8.17",
networks: {
// 4. Add the Moonbase Alpha network specification
moonbase: {
url: 'https://rpc.api.moonbase.moonbeam.network',
chainId: 1287, // 0x507 in hex
accounts: [privateKey, privateKey2]
},
dev: {
url: 'http://127.0.0.1:9933',
chainId: 1281, // 0x501 in hex
accounts: [alicePrivateKey, bobPrivateKey]
},
moonbeam: {
url: 'https://rpc.api.moonbeam.network', // Or insert your own RPC URL here
chainId: 1284, // 0x504 in hex
accounts: [privateKey, privateKey2]
},
},
// 5. Set up your Moonscan API key for contract verification
// Moonbeam and Moonbase Alpha Moonscan use the same API key
etherscan: {
apiKey: {
moonbaseAlpha: moonbeamMoonscanAPIKey, // Moonbase Moonscan API Key
moonbeam: moonbeamMoonscanAPIKey, // Moonbeam Moonscan API Key
}
}
};
You can modify the hardhat.config.js
file to use any of the Moonbeam networks:
moonbeam: {
url: 'RPC-API-ENDPOINT-HERE', // Insert your RPC URL here
chainId: 1284, // (hex: 0x504)
accounts: [privateKey]
},
moonriver: {
url: 'RPC-API-ENDPOINT-HERE', // Insert your RPC URL here
chainId: 1285, // (hex: 0x505)
accounts: [privateKey]
},
moonbase: {
url: 'https://rpc.api.moonbase.moonbeam.network',
chainId: 1287, // (hex: 0x507)
accounts: [privateKey]
},
dev: {
url: 'http://127.0.0.1:9944',
chainId: 1281, // (hex: 0x501)
accounts: [privateKey]
},
You're now ready to move on to compilation and testing.
Compiling the Contract¶
To compile the contract you can simply run:
npx hardhat compile
After compilation, an artifacts
directory is created: it holds the bytecode and metadata of the contract, which are .json
files. It’s a good idea to add this directory to your .gitignore
.
Testing¶
A robust smart contract development workflow is incomplete without a testing suite. Hardhat has a number of tools that make it easy to write and run tests. In this section, you'll learn the basics of testing your smart contracts and some more advanced techniques.
Hardhat tests are typically written with Mocha and Chai. Mocha is a JavaScript testing framework and Chai is a BDD/TDD JavaScript assertion library. BDD/TDD stands for behavior and test driven development respectively. Effective BDD/TDD necessitates writing your tests before writing your smart contract code. The structure of this tutorial doesn't strictly follow these guidelines, but you may wish to adopt these principles in your development workflow. Hardhat recommends using Hardhat Toolbox, a plugin that bundles everything you need to get started with Hardhat, including Mocha and Chai.
Because we will initially be running our tests on a local Moonbeam node, we need to specify Alice's address as the address of our target collator (Alice's account is the only collator for a local development node):
0xf24FF3a9CF04c71Dbc94D0b566f7A27B94566cac
If instead you prefer to run your tests against Moonbase Alpha, you can choose the below collator, or any other collator on Moonbase Alpha you would like the DAO to delegate to:
0x4c5A56ed5A4FF7B09aA86560AfD7d383F4831Cce
Configuring the Test File¶
To set up your test file, take the following steps:
- Create a
tests
directorymkdir tests
- Create a new file called
Dao.js
touch tests/Dao.js
- Then copy and paste the contents below to set up the initial structure of your test file. Be sure to read the comments as they can clarify the purpose of each line
// Import Hardhat and Hardhat Toolbox const { ethers } = require("hardhat"); require("@nomicfoundation/hardhat-toolbox"); // Import Chai to use its assertion functions here const { expect } = require("chai"); // Indicate Alice's address as the target collator on local development node const targetCollator = "0xf24FF3a9CF04c71Dbc94D0b566f7A27B94566cac";
Deploying a Staking DAO for Testing¶
Before we can run any test cases we'll need to launch a staking DAO with an initial configuration. Our setup here is relatively simple - we'll be deploying a staking DAO with a single administrator (the deployer) and then adding a new member to the DAO. This simple setup is perfect for demonstration purposes, but it's easy to imagine more complex configurations you'd like to test, such as a scenario with 100 DAO members or one with multiple admins of the DAO.
Mocha's describe
function enables you to organize your tests. Multiple describe
functions can be nested together. It's entirely optional but can be useful especially in complex projects with a large number of test cases. You can read more about constructing tests and getting started with Mocha on the Mocha docs site.
We'll define a function called deployDao
that will contain the setup steps for our staking DAO. To configure your test file, add the following snippet:
// The describe function receives the name of a section of your test suite, and a
// callback. The callback must define the tests of that section. This callback
// can't be an async function
describe("Dao contract", function () {
async function deployDao() {
// Get the contract factory and signers here
const [deployer, member1] = await ethers.getSigners();
const delegationDao = await ethers.getContractFactory("DelegationDAO");
// Deploy the staking DAO and wait for the deployment transaction to be confirmed
const deployedDao = await delegationDao.deploy(targetCollator, deployer.address);
await deployedDao.deployed();
// Add a new member to the DAO
await deployedDao.grant_member(member1.address);
// Return the deployed DAO to allow the tests to access and interact with it
return { deployedDao };
}
// The test cases should be added here
});
Writing your First Test Cases¶
First, you'll create a subsection called Deployment
to keep the test file organized. This will be nested within the Dao contract
describe function. Next you'll define your first test case by using the it
Mocha function. This first test is simply checking to see that the staking DAO is correctly storing the address of the target collator.
Go ahead and add the below snippet to the end of your Dao contract
function.
// You can nest calls to create subsections
describe("Deployment", function () {
// Mocha's it function is used to define each of your tests.
// It receives the test name, and a callback function.
// If the callback function is async, Mocha will await it
it("should store the correct target collator in the DAO", async function () {
// Set up our test environment by calling deployDao
const { deployedDao } = await deployDao();
// The expect function receives a value and wraps it in an assertion object.
// This test will pass if the DAO stored the correct target collator
expect(await deployedDao.target()).to.equal(targetCollator);
});
// The following test cases should be added here
});
Now, add another test case. When a staking DAO is launched, it shouldn't have any funds. This test verifies that is indeed the case. Go ahead and add the following test case to your Dao.js
file:
it("should initially have 0 funds in the DAO", async function () {
const { deployedDao } = await deployDao();
// This test will pass if the DAO has no funds as expected before any contributions
expect(await deployedDao.totalStake()).to.equal(0);
});
Function Reverts¶
Now, you'll implement a more complex test case with a slightly different architecture. In prior examples, you've verified that a function returns an expected value. In this one, you'll be verifying that a function reverts. You'll also change the address of the caller to test an admin-only function.
In the staking DAO contract, only admins are authorized to add new members to the DAO. One could write a test that checks to see if the admin is authorized to add new members but perhaps a more important test is to ensure that non-admins can't add new members. To run this test case under a different account, you're going to ask for another address when you call ethers.getSigners()
and specify the caller in the assertion with connect(member1)
. Finally, after the function call you'll append .to.be.reverted
to indicate that the test case is successful if the function reverts. And if it doesn't revert it's a failed test!
it("should not allow non-admins to grant membership", async function () {
const { deployedDao } = await deployDao();
// We ask ethers for two accounts back this time
const [deployer, member1] = await ethers.getSigners();
// We use connect to call grant_member from member1's account instead of admin.
// This test will succeed if the function call reverts and fails if the call succeeds
await expect(deployedDao.connect(member1).grant_member("0x0000000000000000000000000000000000000000")).to.be.reverted;
});
Signing Transactions from Other Accounts¶
For this example, you'll check to verify whether the newly added DAO member can call the check_free_balance()
function of staking DAO, which has an access modifier such that only members can access it.
it("should only allow members to access member-only functions", async function () {
const { deployedDao } = await deployDao();
// We ask ethers for two accounts back this time
const [deployer, member1] = await ethers.getSigners();
// This test will succeed if the DAO member can call the member-only function.
// We use connect here to call the function from the account of the new member
expect(await deployedDao.connect(member1).check_free_balance()).to.equal(0);
});
And that's it! You're now ready to run your tests!
Running your Tests¶
If you've followed all of the prior sections, your Dao.js
test file should be all set to go. Otherwise, you can copy the complete snippet from GitHub into your Dao.js
test file.
Since our test cases encompass mostly configuration and setup of the staking DAO and don't involve actual delegation actions, we'll be running our tests on a Moonbeam development node (local node). Remember that Alice (0xf24FF3a9CF04c71Dbc94D0b566f7A27B94566cac
) is the only collator on a local development node. You can use the flag --network moonbase
to run the tests using Moonbase Alpha. In that case, be sure that your deployer address is sufficiently funded with DEV tokens.
Challenge
Try to create an additional test case that verifies the staking DAO successfully delegates to a collator once minDelegationStk
is met. You'll need to test this on Moonbase Alpha rather than a local development node.
First, make sure that your local Moonbeam node is running by following the instructions for launching a local development node. Take precautions if you import the Alice and Bob private keys into your secrets.json
file because you could inadvertently send real funds to those accounts, which would result in a loss of those funds.
You can run your tests with the following command:
npx hardhat test --network dev tests/Dao.js
If everything was set up correctly, you should see output like the following:
Deploying to Moonbase Alpha¶
In the following steps, we'll be deploying the DelegationDAO
to the Moonbase Alpha TestNet. Before deploying to Moonbase Alpha or Moonbeam, double check you're not using the Alice and Bob accounts, which should only be used on a local development node.
As a side note, DelegationDAO
relies on StakingInterface.sol
, which is a Substrate-based offering unique to Moonbeam networks. The Hardhat Network and forked networks are simulated EVM environments which do not include the Substrate-based precompiles like StakingInterface.sol
. Therefore, DelegationDAO
will not work properly if deployed to the local default Hardhat Network or a forked network.
To deploy DelegationDAO.sol
, you can write a simple script. You can create a new directory for the script and name it scripts
:
mkdir scripts
Then add a new file to it called deploy.js
:
touch scripts/deploy.js
Next, you need to write your deployment script which can be done using ethers
. Because you'll be running it with Hardhat, you don't need to import any libraries.
To get started, take the following steps:
- Specify the address of the active collator the DAO intends to delegate to. In this case, we've specified the address of the PS-1 Collator (note: this is different from the address of the Alice collator on a local development node)
- Specify the deployer address as the admin of the DAO. It's important that the deployer be the admin of the DAO to ensure later tests work as expected
- Create a local instance of the contract with the
getContractFactory
method - Use the
deploy
method that exists within this instance to instantiate the smart contract - Once deployed, you can fetch the address of the contract using the contract instance
When all is said and done your deployment script should look similar to the following:
// 1. The PS-1 collator on Moonbase Alpha is chosen as the DAO's target
const targetCollator = "0x4c5A56ed5A4FF7B09aA86560AfD7d383F4831Cce"
async function main() {
// 2. Get the address of the deployer to later be set as the admin of the DAO
const [deployer] = await ethers.getSigners();
console.log("Deploying contracts with the account:", deployer.address);
// 3. Get an instance of DelegationDAO
const delegationDao = await ethers.getContractFactory("DelegationDAO");
// 4. Deploy the contract specifying two params: the desired collator to
// delegate to and the address of the deployer (the initial DAO admin)
const deployedDao = await delegationDao.deploy(targetCollator, deployer.address);
// 5. Print out the address of the deployed staking DAO contract
console.log("DAO address:", deployedDao.address);
}
main()
.then(() => process.exit(0))
.catch((error) => {
console.error(error);
process.exit(1);
});
Make sure you've funded your accounts with Moonbase Alpha DEV tokens. You can now deploy DelegationDAO.sol
using the run
command and specifying moonbase
as the network (as configured in the hardhat.config.js
file):
npx hardhat run --network moonbase scripts/deploy.js
After a few seconds, the contract is deployed, and you should see the address in the terminal.
Congratulations, your contract is live on Moonbase Alpha! Save the address, as you will use it to interact with this contract instance in the next step.
Verifying Contracts on Moonbase Alpha¶
Contract verification is an essential step of any developer's workflow, particularly in the theoretical example of this staking DAO. Potential participants in the DAO need to be assured that the smart contract works as intended - and verifying the contract allows anyone to observe and analyze the deployed smart contract.
While it's possible to verify smart contracts on the Moonscan website, the Hardhat Etherscan plugin enables us to verify our staking DAO in a faster and easier manner. It's not an exaggeration to say that the plugin dramatically simplifies the contract verification process, especially for projects that include multiple Solidity files or libraries.
Before beginning the contract verification process, you'll need to acquire a Moonscan API Key. Note that Moonbeam and Moonbase Alpha use the same Moonbeam Moonscan API key, whereas you'll need a distinct API key for Moonriver.
Double check that your secrets.json
file includes your API key for Moonbeam Moonscan.
To verify the contract, you will run the verify
command and pass in the network where the DelegationDao
contract is deployed, the address of the contract, and the two constructor arguments that you specified in your deploy.js
file, namely, the address of the target collator and the address you deployed the smart contract with (sourced from your secrets.json
file).
npx hardhat verify --network moonbase <CONTRACT-ADDRESS> "0x4c5A56ed5A4FF7B09aA86560AfD7d383F4831Cce" "DEPLOYER-ADDRESS"
Note
If you're deploying DelegationDAO.sol
verbatim without any changes, you may get an Already Verified
error because Moonscan automatically recognizes and verifies smart contracts that have matching bytecode. Your contract will still show as verified, so there is nothing else you need to do. However, if you'd prefer to verify your own DelegationDAO.sol
, you can make a small change to the contract (such as changing a comment) and repeating the compilation, deployment and verification steps.
In your terminal you should see the source code for your contract was successfully submitted for verification. If the verification was successful, you should see Successfully verified contract and there will be a link to the contract code on Moonscan for Moonbase Alpha. If the plugin returns an error, double check that your API key is configured correctly and that you have specified all necessary parameters in the verification command. You can refer to the guide to the Hardhat Etherscan plugin for more information.
Deploying to Production on Moonbeam Mainnet¶
Note
DelegationDAO.sol
is unreviewed and unaudited. It is designed only for demonstration purposes and not intended for production use. It may contain bugs or logic errors that could result in loss of funds.
In the following steps, we'll be deploying the DelegationDAO
contract to the Moonbeam MainNet network. Remember to add the Moonbeam network to your hardhat.config.js
and update your secrets.json
file with the private keys of your accounts on Moonbeam if you haven't done so already. Before deploying DelegationDAO
to Moonbeam, we need to change the address of the target collator, since our target collator on Moonbase Alpha does not exist on Moonbeam. Head to your deploy script and change the target collator to 0x1C86E56007FCBF759348dcF0479596a9857Ba105
or another Moonbeam collator of your choice. Your deploy.js
script should thus look like the following:
// 1. The PureStake-03 collator on Moonbeam is chosen as the DAO's target
const targetCollator = "0x1C86E56007FCBF759348dcF0479596a9857Ba105"
async function main() {
// 2. Get the address of the deployer to later be set as the admin of the DAO
const [deployer] = await ethers.getSigners();
console.log("Deploying contracts with the account:", deployer.address);
// 3. Get an instance of DelegationDAO
const delegationDao = await ethers.getContractFactory("DelegationDAO");
// 4. Deploy the contract specifying two params: the desired collator to delegate
// to and the address of the deployer (synonymous with initial DAO admin)
const deployedDao = await delegationDao.deploy(targetCollator, deployer.address);
console.log("DAO address:", deployedDao.address);
}
main()
.then(() => process.exit(0))
.catch((error) => {
console.error(error);
process.exit(1);
});
You can now deploy DelegationDAO.sol
using the run
command and specifying moonbeam
as the network:
npx hardhat run --network moonbeam scripts/deploy.js
If you're using another Moonbeam network, make sure that you specify the correct network. The network name needs to match how it's defined in the hardhat.config.js
.
After a few seconds, the contract is deployed, and you should see the address in the terminal.
Congratulations, your contract is live on Moonbeam! Save the address, as you will use it to interact with this contract instance in the next step.
Verifying Contracts on Moonbeam¶
In this section, we'll be verifying the contract that was just deployed on Moonbeam. Before beginning the contract verification process, you'll need to acquire a Moonscan API Key. Note that Moonbeam and Moonbase Alpha use the same Moonbeam Moonscan API key, whereas you'll need a distinct API key for Moonriver.
Double check that your secrets.json
file includes your API key for Moonbeam Moonscan.
To verify the contract, you will run the verify
command and pass in the network where the DelegationDao
contract is deployed, the address of the contract, and the two constructor arguments that you specified in your deploy.js
file, namely, the address of the target collator and the address you deployed the smart contract with (sourced from your secrets.json
file). Remember that the target collator of the staking DAO on Moonbeam is different from the target collator of the staking DAO on Moonbase Alpha.
npx hardhat verify --network moonbeam <CONTRACT-ADDRESS> "0x1C86E56007FCBF759348dcF0479596a9857Ba105" "DEPLOYER-ADDRESS"
Note
If you're deploying DelegationDAO.sol
verbatim without any changes, you may get an Already Verified
error because Moonscan automatically recognizes and verifies smart contracts that have matching bytecode. Your contract will still show as verified, so there is nothing else you need to do. However, if you'd prefer to verify your own DelegationDAO.sol
, you can make a small change to the contract (such as changing a comment) and repeating the compilation, deployment, and verification steps.
In your terminal you should see the source code for your contract was successfully submitted for verification. If the verification was successful, you should see Successfully verified contract and there will be a link to the contract code on Moonbeam Moonscan. If the plugin returns an error, double check that your API key is configured correctly and that you have specified all necessary parameters in the verification command. You can refer to the guide to the Hardhat Etherscan plugin for more information.
And that's it! We covered a lot of ground in this tutorial but there's more resources available if you'd like to go deeper, including the following:
| Created: March 29, 2023