foundry-template/README.md

188 lines
5.7 KiB
Markdown
Raw Normal View History

# Foundry Template [![Open in Gitpod][gitpod-badge]][gitpod] [![Github Actions][gha-badge]][gha] [![Foundry][foundry-badge]][foundry] [![License: MIT][license-badge]][license]
2022-07-16 11:36:29 +00:00
2023-01-16 11:40:22 +00:00
[gitpod]: https://gitpod.io/#https://github.com/PaulRBerg/foundry-template
[gitpod-badge]: https://img.shields.io/badge/Gitpod-Open%20in%20Gitpod-FFB45B?logo=gitpod
2023-01-16 11:40:22 +00:00
[gha]: https://github.com/PaulRBerg/foundry-template/actions
[gha-badge]: https://github.com/PaulRBerg/foundry-template/actions/workflows/ci.yml/badge.svg
2022-07-16 11:36:29 +00:00
[foundry]: https://getfoundry.sh/
[foundry-badge]: https://img.shields.io/badge/Built%20with-Foundry-FFDB1C.svg
[license]: https://opensource.org/licenses/MIT
[license-badge]: https://img.shields.io/badge/License-MIT-blue.svg
A Foundry-based template for developing Solidity smart contracts, with sensible defaults.
## What's Inside
- [Forge](https://github.com/foundry-rs/foundry/blob/master/forge): compile, test, fuzz, format, and deploy smart
contracts
2023-01-16 11:40:22 +00:00
- [PRBTest](https://github.com/PaulRBerg/prb-test): modern collection of testing assertions and logging utilities
2022-07-16 11:36:29 +00:00
- [Forge Std](https://github.com/foundry-rs/forge-std): collection of helpful contracts and cheatcodes for testing
- [Solhint](https://github.com/protofire/solhint): linter for Solidity code
- [Prettier Plugin Solidity](https://github.com/prettier-solidity/prettier-plugin-solidity): code formatter for
non-Solidity files
2022-07-16 11:36:29 +00:00
## Getting Started
2023-01-16 11:40:22 +00:00
Click the [`Use this template`](https://github.com/PaulRBerg/foundry-template/generate) button at the top of the page to
create a new repository with this repo as the initial state.
2022-07-16 11:36:29 +00:00
Or, if you prefer to install the template manually:
```sh
2023-01-16 11:40:22 +00:00
forge init my-project --template https://github.com/PaulRBerg/foundry-template
2022-07-16 11:36:29 +00:00
cd my-project
2023-03-10 11:45:41 +00:00
pnpm install # install Solhint, Prettier, and other Node.js deps
2022-07-16 11:36:29 +00:00
```
If this is your first time with Foundry, check out the
[installation](https://github.com/foundry-rs/foundry#installation) instructions.
2022-07-16 11:36:29 +00:00
## Features
This template builds upon the frameworks and libraries mentioned above, so for details about their specific features,
please consult their respective documentation.
2022-07-16 11:36:29 +00:00
2023-02-25 10:57:06 +00:00
For example, if you're interested in exploring Foundry in more detail, you should look at the
[Foundry Book](https://book.getfoundry.sh/). In particular, you may be interested in reading the
[Writing Tests](https://book.getfoundry.sh/forge/writing-tests.html) tutorial.
2022-07-16 11:36:29 +00:00
### Sensible Defaults
2023-02-25 10:57:06 +00:00
This template comes with a set of sensible default configurations for you to use. These defaults can be found in the
following files:
2022-07-16 11:36:29 +00:00
```text
├── .editorconfig
├── .gitignore
├── .prettierignore
├── .prettierrc.yml
├── .solhint.json
├── foundry.toml
└── remappings.txt
```
### VSCode Integration
This template is IDE agnostic, but for the best user experience, you may want to use it in VSCode alongside Nomic
Foundation's [Solidity extension](https://marketplace.visualstudio.com/items?itemName=NomicFoundation.hardhat-solidity).
For guidance on how to integrate a Foundry project in VSCode, please refer to this
[guide](https://book.getfoundry.sh/config/vscode).
2022-07-16 11:36:29 +00:00
### 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.
You can edit the CI script in [.github/workflows/ci.yml](./.github/workflows/ci.yml).
## Writing Tests
2023-01-16 11:40:22 +00:00
To write a new test contract, you start by importing [PRBTest](https://github.com/PaulRBerg/prb-test) and inherit from
it in your test contract. PRBTest comes with a pre-instantiated [cheatcodes](https://book.getfoundry.sh/cheatcodes/)
2023-02-25 10:57:06 +00:00
environment accessible via the `vm` property. If you would like to view the logs in the terminal output you can add the
`-vvv` flag and use [console.log](https://book.getfoundry.sh/faq?highlight=console.log#how-do-i-use-consolelog).
2022-07-16 11:36:29 +00:00
This template comes with an example test contract [Foo.t.sol](./test/Foo.t.sol)
2022-07-16 11:36:29 +00:00
## Usage
2023-02-25 10:57:06 +00:00
This is a list of the most frequently needed commands.
2022-07-16 11:36:29 +00:00
### Build
Build the contracts:
```sh
$ forge build
```
### Clean
Delete the build artifacts and cache directories:
```sh
$ forge clean
```
### Compile
Compile the contracts:
```sh
$ forge build
```
### Coverage
Get a test coverage report:
```sh
$ forge coverage
```
2022-07-16 11:36:29 +00:00
### Deploy
Deploy to Anvil:
```sh
2023-02-05 11:09:47 +00:00
$ forge script script/DeployFoo.s.sol --broadcast --fork-url http://localhost:8545
2022-07-16 11:36:29 +00:00
```
For this script to work, you need to have a `MNEMONIC` environment variable set to a valid
[BIP39 mnemonic](https://iancoleman.io/bip39/).
For instructions on how to deploy to a testnet or mainnet, check out the
2023-02-25 10:57:06 +00:00
[Solidity Scripting](https://book.getfoundry.sh/tutorials/solidity-scripting.html) tutorial.
2022-07-16 11:36:29 +00:00
### Format
Format the contracts:
2022-07-16 11:36:29 +00:00
```sh
$ forge fmt
2022-07-16 11:36:29 +00:00
```
### Gas Usage
Get a gas report:
```sh
$ forge test --gas-report
```
### Lint
Lint the contracts:
```sh
2023-03-10 11:45:41 +00:00
$ pnpm lint
2022-07-16 11:36:29 +00:00
```
### Test
Run the tests:
```sh
$ forge test
```
## Notes
2023-02-25 10:57:06 +00:00
1. Foundry uses [git submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules) to manage dependencies. For
detailed instructions on working with dependencies, please refer to the
[guide](https://book.getfoundry.sh/projects/dependencies.html) 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
2023-02-25 10:57:06 +00:00
testing against a fork.
2022-07-16 11:36:29 +00:00
## Related Efforts
- [abigger87/femplate](https://github.com/abigger87/femplate)
- [cleanunicorn/ethereum-smartcontract-template](https://github.com/cleanunicorn/ethereum-smartcontract-template)
- [foundry-rs/forge-template](https://github.com/foundry-rs/forge-template)
- [FrankieIsLost/forge-template](https://github.com/FrankieIsLost/forge-template)
## License
2023-03-16 16:50:47 +00:00
This project is licensed under MIT.