{"id":13712684,"url":"https://github.com/mattstam/solidity-template","last_synced_at":"2025-04-14T08:50:38.482Z","repository":{"id":62467541,"uuid":"559357734","full_name":"mattstam/solidity-template","owner":"mattstam","description":"A Solidity starter template for developing smart contracts.","archived":false,"fork":false,"pushed_at":"2023-07-04T17:31:26.000Z","size":452,"stargazers_count":116,"open_issues_count":0,"forks_count":17,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-27T22:22:08.645Z","etag":null,"topics":["contracts","ethereum","ethersjs","foundry","hardhat","solidity","template","typescript","web3"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mattstam.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-10-29T21:30:06.000Z","updated_at":"2024-11-24T21:22:37.000Z","dependencies_parsed_at":"2024-11-13T23:30:43.692Z","dependency_job_id":"68165547-3c87-4540-9caa-f50688a4ccd1","html_url":"https://github.com/mattstam/solidity-template","commit_stats":null,"previous_names":[],"tags_count":0,"template":true,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mattstam%2Fsolidity-template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mattstam%2Fsolidity-template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mattstam%2Fsolidity-template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mattstam%2Fsolidity-template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mattstam","download_url":"https://codeload.github.com/mattstam/solidity-template/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248852079,"owners_count":21171837,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["contracts","ethereum","ethersjs","foundry","hardhat","solidity","template","typescript","web3"],"created_at":"2024-08-02T23:01:21.371Z","updated_at":"2025-04-14T08:50:38.446Z","avatar_url":"https://github.com/mattstam.png","language":"TypeScript","funding_links":[],"categories":["Project Starter"],"sub_categories":[],"readme":"# [Solidity Template](#solidity-template)\n\n[![Unit Tests](https://github.com/mattstam/solidity-template/actions/workflows/unit-test.yaml/badge.svg)](https://github.com/mattstam/solidity-template/actions/workflows/unit-test.yaml)\n[![Integration Tests](https://github.com/mattstam/solidity-template/actions/workflows/integration-test.yaml/badge.svg)](https://github.com/mattstam/solidity-template/actions/workflows/integration-test.yaml)\n[![Slither Static Analysis](https://github.com/mattstam/solidity-template/actions/workflows/slither.yaml/badge.svg)](https://github.com/mattstam/solidity-template/actions/workflows/slither.yaml)\n[![Lint](https://github.com/mattstam/solidity-template/actions/workflows/lint.yaml/badge.svg)](https://github.com/mattstam/solidity-template/actions/workflows/lint.yaml)\n[![NPM Version](https://img.shields.io/npm/v/@mattstam/solidity-template/latest.svg)](https://www.npmjs.com/package/@mattstam/solidity-template/v/latest)\n\nThis is a modern Solidity template for Ethereum smart contracts. It combines two extremely powerful frameworks:\n\n- [Foundry](#foundry) - for Unit tests written in Solidity ([contracts/test/](./contracts/test/)).\n- [Hardhat](#hardhat) - for Integration tests written in Typescript ([integration/](./integration/)).\n\nThis template optimizes and cleans up using these frameworks together (e.g. no `remappings.txt` or `/lib` submodules, using one [foundry.toml](./foundry.toml) as a source of truth for options). Dependencies are all managed through [NPM](./package.json).\n\nUtilizing 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:\n\n- On-chain developers writing contracts that call these contracts can refer to your [Unit Test files](./contracts/test/) to see the expected usage in [Solidity](https://docs.soliditylang.org/en/latest/).\n\n- Off-chain developers writing clients that call these contracts can refer to your [Integration Test files](./integration/) to see the expected usage in [JavaScript (TypeScript)](https://www.typescriptlang.org/) and [Ethers.js](https://docs.ethers.io/v5/).\n\nThese frameworks also offer some advanced tools for contract debugging, deployment, gas measurements, etc.\n\nOther features of this template are linting rules for [Solidity](./.solhint.json) and [TypeScript](./.eslintrc.js), a [developer guide](#developer-guide) for new contributors to your project, a [LICENSE](./LICENSE) sample which can be changed, a sample [CLI](./scripts/console) for contract deployment and interactions, [documentation generation](https://github.com/primitivefinance/primitive-dodoc) from NatSpec comments, and useful [GitHub Actions](#github-actions--workflow-badges) already configured.\n\n\u0026nbsp;\n\n## [Template Usage](#template-usage)\n\nGo to the top right of [this repository](https://github.com/mattstam/solidity-template) and click the big green [\"Use this template\"](https://github.com/mattstam/solidity-template/generate) button:\n\n[![Use this template](./media/template.png)](https://github.com/mattstam/solidity-template/generate)\n\nAlternatively, you can set this template up through Foundry:\n\n```sh\nforge init --template https://github.com/mattstam/solidity-template \u003cproject-name\u003e\n```\n\nThis will create a copy of this repository for your project. A sample contract already exists, [Counter.sol](./contracts/Counter.sol), with its interface [ICounter.sol](./contracts/interfaces/ICounter.sol), Unit Test file [Counter.t.sol](./contracts/test/Counter.t.sol), and Integration Test file [counter.test.ts](./integration/counter.test.ts).\n\n\nUse this as the foundation for how to write and test your contracts. Replace these with the contracts you want to build.\n\n### [GitHub Actions \u0026 Workflow Badges](#github-actions--workflow-badges)\n\nThis repository comes with [GitHub Actions](https://github.com/features/actions) already configured. You can find them in the [./github/workflows](./.github/workflows/) directory. These will run the [Unit Tests](./.github/workflows/unit-test.yaml), [Integration Tests](./.github/workflows/integration-test.yaml), [Lint Check](./.github/workflows/lint.yaml), etc, during Pull Requests and merges to the master branch.\n\nAll that is required to get theses setup is to include your [`MNEMONIC`](https://metamask.zendesk.com/hc/en-us/articles/360015290032-How-to-reveal-your-Secret-Recovery-Phrase) environmental variable in the settings. In your GitHub repository, go to the `Settings` tab \u003e `Security`/`Secrets`/`Actions` \u003e click the big green \"New repository secret\" button:\n\n![New repository secret](./media/secret.png)\n\nThe *Name* should be `MNEMONIC` and the *Secret* should be your [BIP-39](https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki) compatible phrase. Afterward you should see:\n\n![MNEMONIC secret](./media/mnemonic.png)\n\nIf 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:\n\n![badges](./media/badges.png)\n\n### [Cleanup](#cleanup)\n\nTo 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.\n\nClear out everything in the [media](./media/) directory, as these images were just use in this README. Use this directory for your own project content instead.\n\nLastly, delete this [Template Usage](#template-usage) block in this README. You probably want to keep everything else, but customize it to your needs.\n\n\u0026nbsp;\n\n## [Developer Guide](#developer-guide)\n\n### [Directory Structure](#directory-structure)\n\n```txt\nintegration/\n|- counter.test.ts - \"Integration tests with Hardhat\"\nscripts/\n|- console.ts - \"CLI for contracts\"\n|- deploy.ts - \"Contract deployment functions\"\ncontracts/\n|- interfaces/\n|--- ICounter.sol - \"Interface contract\"\n|- test/\n|--- Counter.t.sol - \"Unit tests with Foundry\"\n|- Counter.sol - \"Implementation contract\"`\n.env - \"Real environment vars\"\n.env.example - \"Example environment vars\"\n.eslintignore - \"Ignore list for eslint\"\n.eslintrc - \"Configure eslint\"\n.gitignore - \"Ignore list for Git\"\n.solcover.js - \"Configure coverage\"\n.solhint.json - \"Configure Solidity linter\"\n.prettierignore - \"Ignore list for Prettier\"\n.prettierrc.json - \"Configure Prettier\"\nfoundry.toml - \"Configure Foundry\"\nhardhat.config.ts - \"Configure Hardhat\"\nLICENSE - \"Software license\"\npackage.json - \"Node dependencies\"\nslither.config.json - \"Configure Slither\"\ntsconfig.json - \"Configure Typescript\"\n```\n\n--- *(not an extensive list of all files)* ---\n\n\u0026nbsp;\n\n#### [Clone the repository](#clone-the-repository)\n\n```sh\ngit clone https://github.com/mattstam/solidity-template.git \u0026\u0026 cd solidity-template\n```\n\n#### [Install Node.js / NPM](#install-nodejs--npm)\n\n```sh\nnpm install -g npm\n```\n\n#### [Copy over a new `.env` file](#copy-over-a-new-env-file)\n\n```sh\ncp .env.example .env\n```\n\nFill in *at least* your [`MNEMONIC`](https://metamask.zendesk.com/hc/en-us/articles/360015290032-How-to-reveal-your-Secret-Recovery-Phrase)\n\n#### [Install Node dependencies](#install-node-dependencies)\n\n```sh\nnpm i\n```\n\n#### [Install Foundry](#install-foundry)\n\n```sh\ncurl -L https://foundry.paradigm.xyz | bash\n```\n\nThen, in a new terminal session or after reloading your `PATH`, run this to get\nthe latest [`forge`](https://book.getfoundry.sh/reference/forge/forge) and [`cast`](https://book.getfoundry.sh/reference/cast/cast) binaries:\n\n```sh\nfoundryup\n```\n\n\u0026nbsp;\n\n## [Do Things](#do-things)\n\n#### [Run the unit tests with Forge](#run-the-unit-tests-with-forge)\n\n```sh\nforge test\n```\n\nThis will run everything in [contracts/test/](./contracts/test/), which utilizes [Forge](https://book.getfoundry.sh/forge/tests) to test contract code.\n\n#### [Run the integration tests with Hardhat](#run-the-integration-tests-with-hardhat)\n\n```sh\nnpm run test\n```\n\nThis will run everything in [integration/](./integration/), which utilizes [Hardhat](https://hardhat.org/hardhat-runner/docs/getting-started#overview) to tests for full usage scenarios.\n\n#### [Deploy to Goerli test network](#deploy-to-goerli-test-network)\n\nCreate a [.env](./.env) file matching the variables seen in [.env.example](./.env.example).\n\nGetting fully prepared may involve getting a [`INFURA_API_KEY`](https://docs.infura.io/infura/getting-started) by signing up, and getting some test ETH on your target network via a [facet](https://goerlifaucet.com/).\n\nThen run:\n\n```sh\nnpm run deploy -- --network goerli\n```\n\nThis will automatically update [deployments.json](./deployments.json), which gets exported with your [NPM package](./package.json). It will also become the default address to use when interacting with your contracts with the [CLI](./scripts/console).\n\n#### [Generate documentation](#generate-documentation)\n\n```sh\nnpm run doc\n```\n\nSets up API docs from the [NatSpec](https://docs.soliditylang.org/en/latest/natspec-format.html) comments in your contract interfaces (ignoring implementations and libraries).\n\nIf 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).\n\n\u0026nbsp;\n\n## [Foundry \u0026 Hardhat Info](#foundry--hardhat-info)\n\n#### [Foundry](#foundry)\n\n[Foundry](https://book.getfoundry.sh/) is a blazing fast, portable, and modular toolkit for Ethereum application development. It consists of:\n\n- [Forge](https://book.getfoundry.sh/reference/forge/forge): Framework for [Unit / Fuzz testing](./contracts/test/) written in Solidity.\n- [Cast](https://book.getfoundry.sh/reference/cast/cast): EVM interactions for contracts, transaction handling, and reading on-chain data.\n- [Anvil](https://book.getfoundry.sh/reference/anvil/): A local testnet node with network forking capabilities.\n\nConfiguration details can be found in [foundry.toml](./foundry.toml).\n\n#### [Hardhat](#hardhat)\n\n[Hardhat](https://hardhat.org/getting-started/) is a complete Ethereum development environment. The [integration tests]((./integration/)) run on the [Hardhat network](https://hardhat.org/hardhat-network/), with each test written in [JavaScript (TypeScript)](https://www.typescriptlang.org/), utilizing the [Ethers.js](https://docs.ethers.io/v5/) library, and the [Mocha](https://mochajs.org/) testing framework.\n\nHardhat can also be extended (see the full [plugin list](https://hardhat.org/plugins/)). This project makes use of:\n\n- [Hardhat Waffle](https://github.com/NomicFoundation/hardhat/blob/5659ee220069329df4354ba7cda446daaa24ab35/packages/hardhat-waffle/README.md) - test assertions with [Chai](https://ethereum-waffle.readthedocs.io/en/latest/matchers.html) matchers.\n- [Hardhat Ethers](https://github.com/NomicFoundation/hardhat/blob/5659ee220069329df4354ba7cda446daaa24ab35/packages/hardhat-ethers/README.md) - integration with [Ethers.js](https://docs.ethers.io/v5/).\n- [Hardhat Solhint](https://github.com/NomicFoundation/hardhat/blob/5659ee220069329df4354ba7cda446daaa24ab35/packages/hardhat-solhint/README.md) - integration with the Solidity language [Solhint linter](https://github.com/protofire/solhint).\n- [Hardhat Gas Reporter](https://github.com/cgewecke/hardhat-gas-reporter) - gas cost summary of contract calls.\n- [Hardhat Tracer](https://github.com/zemse/hardhat-tracer) - contract name tag for logs and advanced debugging.\n- [Hardhat Contract Sizer](https://github.com/ItsNickBarry/hardhat-contract-sizer) - show output size of contracts.\n- [Hardhat Etherscan](https://github.com/NomicFoundation/hardhat/blob/5659ee220069329df4354ba7cda446daaa24ab35/packages/hardhat-etherscan/README.md) - verify contract source code on [Etherscan](https://etherscan.io/).\n- [Hardhat Dodoc](https://github.com/primitivefinance/primitive-dodoc) - documentation generation from [NatSpec](https://docs.soliditylang.org/en/latest/natspec-format.html).\n\nConfiguration details can be found in [hardhat.config.ts](./hardhat.config.ts), which inherits from [foundry.toml](./foundry.toml).\n\n\u0026nbsp;\n\n## [Recommended VSCode Extensions](#recommended-vscode-extensions)\n\n- [Solidity Visual Developer](https://marketplace.visualstudio.com/items?itemName=tintinweb.solidity-visual-auditor)\n- [Solidity Language \u0026 Themes (only)](https://marketplace.visualstudio.com/items?itemName=tintinweb.vscode-solidity-language)\n- [Solidity (by Hardhat authors)](https://marketplace.visualstudio.com/items?itemName=NomicFoundation.hardhat-solidity)\n- [Solidity (by Juan Blanco)](https://marketplace.visualstudio.com/items?itemName=JuanBlanco.solidity)\n- [Prettier](https://marketplace.visualstudio.com/items?itemName=SimonSiefke.prettier-vscode)\n\n\u0026nbsp;\n\n## [Deployments](#deployments)\n\nAll contract addresses for each network are stored in [deployments.json](./deployments.json).\n\n\u0026nbsp;\n\n## [License](#license)\n\nThe code in this project is licensed under the [MIT License](./LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmattstam%2Fsolidity-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmattstam%2Fsolidity-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmattstam%2Fsolidity-template/lists"}