Skip to content

Latest commit

 

History

History
242 lines (155 loc) · 12.7 KB

README.md

File metadata and controls

242 lines (155 loc) · 12.7 KB

Unit Tests Integration Tests Slither Static Analysis Lint NPM Version

This is a modern Solidity template for Ethereum smart contracts. It combines two extremely powerful frameworks:

This template optimizes and cleans up using these frameworks together (e.g. no remappings.txt or /lib submodules, using one foundry.toml as a source of truth for options). Dependencies are all managed through NPM.

Utilizing both frameworks allows you to comprehensively test every scenario, which should always be the case when planning to deploy immutable code. Both layers of testing also gives other developers a reference for how they should interact with your contracts:

These frameworks also offer some advanced tools for contract debugging, deployment, gas measurements, etc.

Other features of this template are linting rules for Solidity and TypeScript, a developer guide for new contributors to your project, a LICENSE sample which can be changed, a sample CLI for contract deployment and interactions, documentation generation from NatSpec comments, and useful GitHub Actions already configured.

 

Go to the top right of this repository and click the big green "Use this template" button:

Use this template

Alternatively, you can set this template up through Foundry:

forge init --template https://github.com/mattstam/solidity-template <project-name>

This will create a copy of this repository for your project. A sample contract already exists, Counter.sol, with its interface ICounter.sol, Unit Test file Counter.t.sol, and Integration Test file counter.test.ts.

Use this as the foundation for how to write and test your contracts. Replace these with the contracts you want to build.

This repository comes with GitHub Actions already configured. You can find them in the ./github/workflows directory. These will run the Unit Tests, Integration Tests, Lint Check, etc, during Pull Requests and merges to the master branch.

All that is required to get theses setup is to include your MNEMONIC environmental variable in the settings. In your GitHub repository, go to the Settings tab > Security/Secrets/Actions > click the big green "New repository secret" button:

New repository secret

The Name should be MNEMONIC and the Secret should be your BIP-39 compatible phrase. Afterward you should see:

MNEMONIC secret

If you would like to also get badges for your workflows shown on this README, just uncomment out the lines at the top of this README:

badges

To make this specific to your project, just Find And Replace all the mentions of mattstam/solidity-template, solidity-template, and Solidity Template with the name of your project name.

Clear out everything in the media directory, as these images were just use in this README. Use this directory for your own project content instead.

Lastly, delete this Template Usage block in this README. You probably want to keep everything else, but customize it to your needs.

 

integration/
|- counter.test.ts - "Integration tests with Hardhat"
scripts/
|- console.ts - "CLI for contracts"
|- deploy.ts - "Contract deployment functions"
contracts/
|- interfaces/
|--- ICounter.sol - "Interface contract"
|- test/
|--- Counter.t.sol - "Unit tests with Foundry"
|- Counter.sol - "Implementation contract"`
.env - "Real environment vars"
.env.example - "Example environment vars"
.eslintignore - "Ignore list for eslint"
.eslintrc - "Configure eslint"
.gitignore - "Ignore list for Git"
.solcover.js - "Configure coverage"
.solhint.json - "Configure Solidity linter"
.prettierignore - "Ignore list for Prettier"
.prettierrc.json - "Configure Prettier"
foundry.toml - "Configure Foundry"
hardhat.config.ts - "Configure Hardhat"
LICENSE - "Software license"
package.json - "Node dependencies"
slither.config.json - "Configure Slither"
tsconfig.json - "Configure Typescript"

--- (not an extensive list of all files) ---

 

git clone https://github.com/mattstam/solidity-template.git && cd solidity-template
npm install -g npm
cp .env.example .env

Fill in at least your MNEMONIC

npm i
curl -L https://foundry.paradigm.xyz | bash

Then, in a new terminal session or after reloading your PATH, run this to get the latest forge and cast binaries:

foundryup

 

forge test

This will run everything in contracts/test/, which utilizes Forge to test contract code.

npm run test

This will run everything in integration/, which utilizes Hardhat to tests for full usage scenarios.

Create a .env file matching the variables seen in .env.example.

Getting fully prepared may involve getting a INFURA_API_KEY by signing up, and getting some test ETH on your target network via a facet.

Then run:

npm run deploy -- --network goerli

This will automatically update deployments.json, which gets exported with your NPM package. It will also become the default address to use when interacting with your contracts with the CLI.

npm run doc

Sets up API docs from the NatSpec comments in your contract interfaces (ignoring implementations and libraries).

If desired, this can be updated to included all contract comments, and the path can be updated to a different location (such as if you want a seperate docs repository for your project).

 

Foundry is a blazing fast, portable, and modular toolkit for Ethereum application development. It consists of:

  • Forge: Framework for Unit / Fuzz testing written in Solidity.
  • Cast: EVM interactions for contracts, transaction handling, and reading on-chain data.
  • Anvil: A local testnet node with network forking capabilities.

Configuration details can be found in foundry.toml.

Hardhat is a complete Ethereum development environment. The integration tests run on the Hardhat network, with each test written in JavaScript (TypeScript), utilizing the Ethers.js library, and the Mocha testing framework.

Hardhat can also be extended (see the full plugin list). This project makes use of:

Configuration details can be found in hardhat.config.ts, which inherits from foundry.toml.

 

 

All contract addresses for each network are stored in deployments.json.

 

The code in this project is licensed under the MIT License.