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 Community: code linter
• Prettier Plugin Solidity: code formatter

Features

1. Multi-sig minting, transfer and burn of tokens.
2. User management and giving them roles e.g. admin, User type A, User type B, User type C (they will each have access controls and permissions to view content)
3. A swap for the token against USDC (only 1 pair)

Implementation breakdown feature:

1. Multi-sig minting, transfer, and burn of tokens:
   • Define a token contract using the ERC-20 standard. You can use OpenZeppelin's implementation as a starting point.
   • Implement multi-signature functionality by utilizing a modifier that requires multiple signatures to execute specific functions like minting, transferring, and burning tokens.
   • Keep track of the authorized signers and their respective signatures in a mapping or an array.
   • When executing a multi-signature transaction, validate the required number of signatures before performing the minting, transfer, or burn operations.
2. User management and roles:
   • Define a separate contract to manage user roles and permissions.
   • Create a struct to represent user data, including their role and access controls.
   • Maintain a mapping or array to store user information.
   • Implement functions to add users, modify their roles, and manage their permissions.
   • Apply access modifiers in your token contract based on user roles to restrict access to certain functions or information.
3. Token swap against USDC:
   • Integrate a decentralized exchange (DEX) or use an existing DEX contract to enable token-swapping functionality.
   • Connect your token contract with the DEX contract to facilitate the swap.
   • Define a function in your contract that allows users to swap your token for USDC.
   • Ensure the swap function handles the necessary validations, such as verifying the user's token balance and allowing the appropriate amount for swapping.

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:

$ forge init my-project --template https://github.com/ahmedali8/foundry-hardhat-template
$ cd my-project
$ make setup

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
├── .eslintignore
├── .eslintrc.yml
├── .gitignore
├── .prettierignore
├── .prettierrc.yml
├── .solcover.js
├── .solhintignore
├── .solhint.json
├── .yarnrc.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.

Usage

Lint Solidity

Lint the Solidity code:

$ yarn lint:sol

Hardhat

Pre Requisites

Before running any command, you need to create a .env file and set all necessary environment variables. Follow the example in .env.example. You can either use mnemonic or individual private keys by setting

$ ACCOUNT_TYPE="MNEMONIC" (Default)
or
$ ACCOUNT_TYPE="PRIVATE_KEYS"

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

Then, proceed with installing dependencies:

$ yarn install

Run a Hardhat chain

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

$ yarn chain

Compile

Compile the smart contracts with Hardhat:

$ yarn compile

TypeChain

Compile the smart contracts and generate TypeChain bindings:

$ yarn typechain

Test

Run the tests with Hardhat:

$ yarn test

or

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

or

$ yarn test:trace       # shows logs + calls

or

$ yarn 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:

$ yarn lint:ts

Forking mainnet

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

$ yarn fork

Coverage

Generate the code coverage report:

$ yarn coverage

Clean

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

$ yarn clean

Deploy

Deploy the contracts to Hardhat Network:

$ yarn deploy

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

$ yarn deploy:network rinkeby

For more information on deploy check out repo hardhat-deploy

Generate Natspec Doc

Generate natspec documentation for your contracts by running

$ yarn hardhat dodoc

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

View Contracts Size

$ yarn hardhat size-contracts

or turn on for every compile

$ CONTRACT_SIZER=true

Verify Contract

Manual Verify

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

For complex arguments you can refer here

$ yarn 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

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

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 sol_script/DeployLock.s.sol:DeployLock \
  --fork-url http://localhost:8545 \
  --broadcast \
  -vvvv

For this script to work, you need to have a MNEMONIC or PRIVATE_KEY environment variable set to a valid BIP39 mnemonic or private key, respectively.

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.

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 yarn 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