Foundry + Hardhat Template

A Foundry + Hardhat based template for developing Solidity smart contracts, with sensible defaults.

Inspiration - Hardhat Template and Foundry Template

• Hardhat: compile, run and test smart contracts
• TypeChain: generate TypeScript bindings for smart contracts
• Ethers: renowned Ethereum library and wallet implementation
• Solcover: code coverage
• Forge: compile, test, fuzz, debug and deploy smart contracts
• Forge Std: collection of helpful contracts and cheatcodes for testing
• Solhint: linter for Solidity code

Table of Contents

• Getting Started
• Features
  • Sensible Defaults
  • GitHub Actions
• Usage
  • Pre Requisites
  • Lint Solidity
  • Foundry
    • Build or Compile
    • Coverage
    • Clean
    • Deploy
    • Gas Usage
    • Test
    • Notes
  • Hardhat
    • Run a Hardhat chain
    • Compile
    • TypeChain
    • Test
    • Lint TypeScript
    • Forking Mainnet
    • Coverage
    • Clean
    • Deploy
    • Generate NATSPEC Doc
    • View Contracts Size
    • Verify Contract
      • Manual Verify
      • Verify Contract Programmatically
• Syntax Highlighting
• Using GitPod
• Contributing
• Resources

Getting Started

Click the Use this template button at the top of the page to create a new repository with this repo as the initial state.

Or, if you prefer to install the template manually:

$ mkdir my-project
$ cd my-project
$ forge init --template ahmedali8/foundry-hardhat-template

Recommended node version is v20.x

If you have nvm then run:

$ nvm use

Then, install dependencies

$ just setup # install Forge and Node.js deps

or

$ bun install
$ forge install

If this is your first time with Foundry, check out the installation instructions.

Features

This template builds upon the frameworks and libraries mentioned above, so for details about their specific features, please consult their respective documentations.

For example, for Hardhat, you can refer to the Hardhat Tutorial and the Hardhat Docs. You might be in particular interested in reading the Testing Contracts section.

For example, for Foundry, you can refer to the Foundry Book. You might be in particular interested in reading the Writing Tests guide.

Sensible Defaults

This template comes with sensible default configurations in the following files:

├── .editorconfig
├── .biome.jsonc
├── .gitignore
├── .prettierignore
├── .prettierrc.yml
├── .solcover.js
├── .solhintignore
├── .solhint.json
├── .bunrc.yml
├── foundry.toml
├── hardhat.config.ts
└── remappings.txt

GitHub Actions

This template comes with GitHub Actions pre-configured. Your contracts will be linted and tested on every push and pull request made to the main branch.

Note though that by default it injects .env.example env variables into github action's $GITHUB_ENV.

You can edit the CI script in .github/workflows/ci.yml.

Installing Dependencies

Foundry typically uses git submodules to manage dependencies, but this template uses Node.js packages because submodules don't scale.

This is how to install dependencies:

1. Install the dependency using your preferred package manager, e.g. bun add dependency-name:dependency-url
   • Use this syntax to install from GitHub: bun add repo-name@github:username/repo-name#tag-name
2. Add a remapping for the dependency in remappings.txt, e.g. dependency-name=node_modules/dependency-name

Note that OpenZeppelin Contracts is pre-installed, so you can follow that as an example.

Usage

Pre Requisites

You don't have to create a .env file, but filling in the environment variables may be useful when deploying to testnet or mainnet or debugging and testing against a mainnet fork.

Follow the example in .env.example. You can choose to use either a mnemonic or individual private key by setting MNEMONIC or PRIVATE_KEY in your .env file.

If you don't already have a mnemonic, use this bip39 to generate one Or if you don't already have a private key, use this vanity-eth to generate one.

Lint Solidity

Lint the Solidity code:

$ bun lint:sol

Foundry

Here's a list of the most frequently needed commands.

Build or Compile

Build the contracts:

$ forge build

Coverage

Get a test coverage report:

$ forge coverage

To get local HTMl reports:

$ just foundry-report

For this to work, you need to have lcov installed.

Clean

Delete the build artifacts and cache directories:

$ forge clean

Deploy

Deploy to Anvil:

# Spin up an anvil local node
$ anvil

# On another terminal
$ forge script scripts/foundry/DeployLock.s.sol:DeployLock \
  --fork-url localhost \
  --broadcast \
  -vvvv

For this script to work for testnet or mainnet, refer to Pre Requisites.

For instructions on how to deploy to a testnet or mainnet, check out the Solidity Scripting tutorial.

Gas Usage

Get a gas report:

$ forge test --gas-report

Test

Run the tests:

$ forge test

You can also use console.log, whose logs you can see in the terminal output by adding the -vvvv flag.

Notes

1. Foundry piggybacks off git submodules to manage dependencies. There's a guide about how to work with dependencies in the book.
2. You don't have to create a .env file, but filling in the environment variables may be useful when debugging and testing against a mainnet fork.

Hardhat

Run a Hardhat chain

To run a local network with all your contracts in it, run the following:

$ bun chain

Compile

Compile the smart contracts with Hardhat:

$ bun compile

TypeChain

Compile the smart contracts and generate TypeChain bindings:

$ bun typechain

Test

Run the tests with Hardhat:

$ bun test

or

$ bun test:gas         # shows gas report and contract size

or

$ bun test:trace       # shows logs + calls

or

$ bun test:fulltrace   # shows logs + calls + sloads + sstores

Optional:

• See the actual fiat currency rates by setting your coingecko api key from here in .env file or command.

• Set custom gas price (gwei) in .env file or command or let it automatically fetched by ethgasstationapi.

$ GAS_PRICE=20
$ COIN_MARKET_CAP_API_KEY="your_api_key"

Lint TypeScript

Lint the TypeScript code:

$ bun lint:ts

Forking mainnet

Starts a local hardhat chain with the state of the last mainnet block

$ bun fork

Coverage

Generate the code coverage report:

$ bun coverage

Clean

Delete the smart contract artifacts, the coverage reports and the Hardhat cache:

$ bun clean

Deploy

Deploy the contracts to Hardhat Network:

$ bun deploy

Deploy the contracts to a specific network, such as the Goerli testnet:

$ bun deploy:network goerli

For more information on deploy check out repo hardhat-deploy

Generate Natspec Doc

Generate natspec documentation for your contracts by running

$ bun hardhat dodoc

For more information on Natspec click here and for dodoc repo click here

View Contracts Size

$ bun hardhat size-contracts

or turn on for every compile

$ CONTRACT_SIZER=true

Verify Contract

Manual Verify

$ bun hardhat verify --network <network> DEPLOYED_CONTRACT_ADDRESS "Constructor argument 1" "Constructor argument 2"

For complex arguments you can refer here

$ bun hardhat verify --contract contracts/CONTRACT_NAME.sol:CONTRACT_NAME --network <network> --constructor-args arguments.js DEPLOYED_CONTRACT_ADDRESS

Verify Contract Programmatically

Verify the contract using verifyContract function in verify.ts

Set block explorer api key in .env file or using command, refer to .env.example for more insight.

Example deploy script with verifyContract function is 00_deploy_lock_contract.ts

Syntax Highlighting

If you use VSCode, you can enjoy syntax highlighting for your Solidity code via the vscode-solidity extension.

Using GitPod

GitPod is an open-source developer platform for remote development.

To view the coverage report generated by bun coverage, just click Go Live from the status bar to turn the server on/off.

Contributing

Contributions are always welcome! Open a PR or an issue!

Thank You!

Resources

• Hardhat Documentation
• Foundry Book