pcaversaccio / hardhat-project-template-ts

A fully-fledged Hardhat project template based on TypeScript.

Fully-Fledged Hardhat Project Template Based on TypeScript

Installation

It is recommended to install pnpm through the npm package manager, which comes bundled with Node.js when you install it on your system. It is recommended to use a Node.js version >= 20.0.0.

Once you have npm installed, you can run the following both to install and upgrade pnpm:

npm install -g pnpm

After having installed pnpm, simply run:

pnpm install

Running Deployments

Note

The deployment script deploy.ts attempts to automatically verify the contract on the target chain after deployment. If you have not configured an API key, the verification will fail.

Example Goerli:

pnpm deploy:goerli

The deployment script deploy.ts includes the tenderly Hardhat Runtime Environment (HRE) extension with the verify method. Please consider uncommenting and configuring the Tenderly project, username, forkNetwork, privateVerification, and deploymentsDir attributes in the hardhat.config.ts file before deploying or remove this call. Also, for this plugin to function you need to create a config.yaml file at $HOME/.tenderly/config.yaml or %HOMEPATH%\.tenderly\config.yaml and add an access_key field to it. For further information, see here.

For the deployment on the zkSync Era test network, you must add your to-be-deployed contract artifact to deploy-zksync.ts, enable zksync in the hardhat.config.ts file, and then run pnpm compile. Next, fund your deployer account on zkSync Era Testnet, setup the zkSync-related configuration variables accordingly, and simply run pnpm deploy:zksynctestnet. Eventually, to verify the contract you can invoke: npx hardhat verify --network zkSyncTestnet --constructor-args arguments.js <YOUR_CONTRACT_ADDRESS>. The same approach applies if you want to deploy on the production network, except that you need to run pnpm deploy:zksyncmain and use --network zkSyncMain for the contract verification.

Running CREATE2 Deployments

pnpm xdeploy

This template uses the xdeployer Hardhat plugin. Check out the documentation for more information on the specifics of the deployments.

Configuration Variables

Run npx hardhat vars set PRIVATE_KEY to set the private key of your wallet. This allows secure access to your wallet to use with both testnet and mainnet funds during Hardhat deployments.

You can also run npx hardhat vars setup to see which other configuration variables are available.

Using a Ledger Hardware Wallet

This template implements the hardhat-ledger plugin. Run npx hardhat set LEDGER_ACCOUNT and enter the address of the Ledger account you want to use.

Using the Truffle Dashboard

Important

Truffle has been sunsetted by Consensys, but I still keep it in the template as I find it a very valuable tool. Please note that due to the lengthy loading time of Truffle Dashboard's npm package @truffle/dashboard-hardhat-plugin, the module is disabled by default in the hardhat.config.ts file. If you want to use it, you must uncomment the module import and the truffle configuration accordingly.

Truffle developed the Truffle Dashboard to provide an easy way to use your existing MetaMask wallet for your deployments and for other transactions that you need to send from a command line context. Because the Truffle Dashboard connects directly to MetaMask it is also possible to use it in combination with hardware wallets like Ledger or Trezor.

First, it is recommended that you install Truffle globally by running:

npm install -g truffle

If you have already installed Truffle, you need to ensure that you have at least version 5.11.5 installed and otherwise upgrade.

To start a Truffle Dashboard, you need to run the following command in a separate terminal window:

truffle dashboard

By default, the command above starts a Truffle Dashboard at http://localhost:24012 and opens the Dashboard in a new tab in your default browser. The Dashboard then prompts you to connect your wallet and confirm that you're connected to the right network. You should double check your connected network at this point, since switching to a different network during a deployment can have unintended consequences.

Eventually, in order to deploy with the Truffle Dashboard, you can simply run:

pnpm deploy:dashboard

Mainnet Forking

You can start an instance of the Hardhat network that forks the mainnet. This means that it will simulate having the same state as the mainnet, but it will work as a local development network. That way you can interact with deployed protocols and test complex interactions locally. To use this feature, you need to connect to an archive node.

This template is currently configured via the hardhat.config.ts as follows:

forking: {
  url: vars.get("ETH_MAINNET_URL", ethMainnetUrl),
  // The Hardhat network will by default fork from the latest mainnet block
  // To pin the block number, specify it below
  // You will need access to a node with archival data for this to work!
  // blockNumber: 14743877,
  // If you want to do some forking, set `enabled` to true
  enabled: false,
},

Contract Verification

Change the contract address to your contract after the deployment has been successful. This works for both testnet and mainnet. You will need to get an API key from etherscan, snowtrace etc.

Example:

npx hardhat verify --network fantomMain --constructor-args arguments.js <YOUR_CONTRACT_ADDRESS>

Contract Interaction

This template includes an example script that shows how to interact programmatically with a deployed contract. You must customise it according to your contract's specifications. The script can be simply invoked via:

npx hardhat run scripts/interact.ts --network <network_name>

Foundry

This template repository also includes the Foundry toolkit as well as the @nomicfoundation/hardhat-foundry plugin.

If you need help getting started with Foundry, I recommend reading the 📖 Foundry Book.

Dependencies

make update

or

forge update

Compilation

make build

or

forge build

Testing

To run only TypeScript tests:

pnpm test:hh

To run only Solidity tests:

pnpm test:forge

or

make test-forge

To additionally display the gas report, you can run:

make test-gasreport

Deployment and Etherscan Verification

Inside the scripts/ folder are a few preconfigured scripts that can be used to deploy and verify contracts via Foundry. These scripts are required to be executable meaning they must be made executable by running:

make scripts

hardhat-project-template-ts's Issues

♻️ The Module `@truffle/dashboard-hardhat-plugin` Heavily Impacts the `pnpm hardhat` Loading Time

Describe the desired feature:

I noticed that the loading time when running "pnpm hardhat" is quite high, so I investigated a bit.

To measure the loading time I used hyperfine.
I used this command:
hyperfine --warmup 3 --runs 10 "pnpm hardhat"

First, I removed everything from the 'hardhat.config.ts' file. The file is empty. This is the loading baseline time, which is:

Then, I kept all the "imports" but I removed all the code logic to measure the modules' loading time.
Like this:

In this scenario, the loading time is:

Finally, I just measured the loading time of the package "@truffle/dashboard-hardhat-plugin".

This package loading time, alone, takes roughly 450-500ms above the baseline mean, which is 660ms (see first screenshot).
Which is a lot considering that all the modules together take 900-950ms above the baseline mean.
Basically around 50% of the time is consumed by the module "@truffle/dashboard-hardhat-plugin".
Unfortunately, I cannot submit a PR to use slow-imports in the Truffle repo because it's deprecated.

So I was wondering, would it be possible to remove that plugin, or to put it under a conditional import, or some other solution?

Thanks!

Code example that solves the feature:

No response

Dependency Dashboard

This issue provides visibility into Renovate updates and their statuses. Learn more

This repository currently has no open or pending branches.

---

• Check this box to trigger a request for Renovate to run again on this repository

Add Further Network Configs

We should add the following networks to the template as well:

• moonbeam
• harmonyMain
• harmonyTestnet
• autobahn

Enable `@truffle/dashboard-hardhat-plugin`

Once the fix is confirmed here, enable the plugin.

Add `zkSync` Mainnet

Describe the desired feature:

I'd like to include zkSync mainnet and the default RPCs for both testnet and mainnet.
In addition, as the zkSync network uses Ethereum RPC endpoints as well, it'd be useful to use the ETH_GOERLI_TESTNET_URL and ETH_MAINNET_URL variables on the ethNetwork property.

I've created a fork with these changes in case you want to check it out 😉

Code example that solves the feature:

zkSyncTestnet: {
      chainId: 280,
      url: process.env.ZKSYNC_TESTNET_URL || "https://testnet.era.zksync.dev",
      ethNetwork: process.env.ETH_GOERLI_TESTNET_URL || "goerli",
      zksync: true,
      verifyURL:
        "https://zksync2-testnet-explorer.zksync.dev/contract_verification",
    },
    zkSyncMainnet: {
      chainId: 324,
      url: process.env.ZKSYNC_MAINNET_URL || "https://mainnet.era.zksync.io",
      ethNetwork: process.env.ETH_MAINNET_URL || "",
      zksync: true,
      verifyURL:
        "https://zksync2-mainnet-explorer.zksync.io/contract_verification",
    },

CI: Implement CodeSpell

Implement CodeSpell in the CI: https://github.com/codespell-project/actions-codespell:

  codespell:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Run CodeSpell
        uses: codespell-project/[email protected]
        with:
          check_filenames: true
          skip: yarn.lock

Use Submodules for Foundry

We should move away from using hardcoded lib imports to the usage of submodules.

Add `ShimmerEVM` Test Network

Describe the desired feature:

Shimmer launched the ShimmerEVM testnet. A L2 blockchain with a L1 DAG chain.

More information here:
https://blog.shimmer.network/shimmerevm-testnet-launch/

I would like to add the ShimmerEVM testnet support to the project

Thank you

Code example that solves the feature:

I already added the necessary information to my fork which is available here:

main...antonionardella:hardhat-project-template-ts:main

Upgrade to Solidity Version `0.8.20`

https://github.com/ethereum/solidity/releases/tag/v0.8.20