Another Foundry Boilerplate _{^{but this time, as a web3 monorepo}}

This monorepo draws inspiration from Scaffold-Eth to jump into experimenting with smart contract and Web3 development.

Though this repository will encompass code for both the frontend and smart contract backend for you to develop quickly on the fly, you should generally opt to split the work into two separate repositories for projects.

Installation

To install the dependencies provided in this boilerplate, you can run:

make install

The following dependencies will be installed:

• lib/
  • solmate - Gas optimised smart contracts to build upon
  • ds-test - Helpers for testing your smart contracts in Solidity
• app/node_modules/
  • blitz - A simple, fast, and powerful JavaScript framework for building web applications
  • ethers - A JavaScript library for interacting with the Ethereum blockchain
  • typechain - Generate TypeScript interfaces from built Solidity contracts
  • @typechain/ethers-v5 - Helper package for Typechain to generate TypeScript interfaces for Ethers.js v5
  • wagmi - React Hooks library for Ethereum, built on Ethers.js
  • siwe - Helpers to conform to EIP-4361 (SIWE) authentication standard
  • iron-session - Session management for authentication using encrypted cookies

Installing your own Dependencies

You may wish to install your own dependencies for usage in your frontend or your smart contracts.

Frontend Dependencies

The node ecosystem provides many packages for frontend development. The repository uses Yarn for managing dependencies due to its ease of use and speed over the native npm command.

You can install any Node dependencies you need by running:

yarn add --cwd app <package> # same as `cd app && yarn add <package>`

The Node package will be installed in the app/node_modules directory and recorded in app/package.json.

Smart Contract Dependencies

You may need to import a smart contract to avoid having to copy and paste code. These imports generally take on the form of other Github repositories. Installing them as Git submodules allows you to pull in any updates. DappTools or Foundry will help you with this.

To install with DappTools:

dapp install [user]/[repo]

To install with Foundry:

forge install [user]/[repo]

The Git submodule will be installed under lib.

Configuration

To configure the project, you will need to set a few environment variables. These are found in app/.env.sample.

Make a copy of .env.sample and rename it to .env. Then, edit the file to set the values you need.

Note: The .env file is hidden from Git via .gitignore as to ensure that you don't accidentally commit it.

Commands

To simplify the commands there are available, the makefile provides a subset of the commands that would be commonly used.

To install any dependencies for either the frontend or smart contract backend, run:

make install # installs all dependencies for the frontend and smart contract backend

To run the frontend in a prototyping development environment, run:

make dev # runs the frontend in development mode

To run the frontend in a production environment, run:

make app # build the frontend blitz files
make prod # run the built files in production mode

To build the smart contracts and then test them, run:

make contracts # builds the smart contracts
make forge-test # tests the smart contracts

To test both the frontend and smart contract backend, run:

make test # tests the frontend and smart contract backend

Further commands can be found within the makefile.

Folder Structure

To help with understanding the structure of this repository, here is a diagram of the folder structure:

.github/workflows - Workflows for Github Actions

• contracts.yml - Automated CI/CD for your smart contracts
• webapp.yml - Automated CI/CD for your frontend

.husky - Bash scripts to run on Git hooks with Husky

.vscode - Configuration for use in VSCode IDE

app - Your frontend code

• package.json - Your frontend dependencies
• components - Any shared React components
• hooks - React Hooks
• pages - React pages for your app go here
• public - Any static files go here
• test - Any app tests go here e.g React Component testing, E2E testing etc.
• .eslintrc.js - ESLint configuration
• .gitignore - Ignore any files you don't want to push to Git
• .prettierrc - Prettier configuration
• blitz.config.ts - Blitz configuration
• jest.config.ts - Jest configuration
• tsconfig.json - TypeScript configuration
• types - TypeScript types used around your app
• yarn.lock - Yarn lock file

contracts - Your smart contracts

• *.sol - Your smart contracts
• test/*.t.sol - Tests for smart contracts
• test/base - BaseTest contract to inherit for utils
• test/utils - Test utils

lib - Your smart contract dependencies, see preinstalled ones here.

. -Top level files e.g the Makefile

• .gitignore - Ignore any files you don't want to push to Git
• .gitmodules - Git submodules configuration
• .lintstagedrc - Configuration for lint-staged in Husky scripts
• .solhint.json - Solhint configuration
• .solhintignore - Ignore any files you don't want Solhint to lint
• foundry.toml - Foundry configuration
• Makefile - Various commands, see here.
• README.md - This file!
• remappings.txt - Configure import paths for Solidity dependencies for Forge

Resources

Below are several resources that may be helpful for getting started with this boilerplate and extending it for your use cases.

Frontend

• adrianmcli/web3-vs-ethers: Web3.js vs Ethers.js
• Standardising login UX with web3modal
• spruceid/siwe: a sign-in authentication protocol (EIP-4361) for Web3
• The original EIP-4361: Sign-In with Ethereum proposal
• bytesbay/web3-token: authenticate users without JWTs
• Impersonate as any wallet address into a Dapp

Smart Contract Testing

• The Solcurity Standard
• Utilities provided in ds-test
• Examples using ds-test to write smart contract tests in Solidity
• Fuzzing smart contract tests with Foundry
• Increasing verbosity of logs from forge test
• Static Analysis with Slither
• Symbolic Execution with Manticore
• Contract-level Property-based Testing with Echidna
• Function-level Property-based Testing with Scribble
• crytic/building-secure-contracts: Guide to using Slither, Echidna, and Manticore for testing

Miscellaneous

• Utilising pre- and post- npm hooks
• Installing Dependencies using DappTools
• Installing Dependencies using Foundry and Forge
• libevm/forge-example: Using custom deploy scripts
• paulrberg/solidity-template: Developer Tooling for Solidity