EVM Deployer Boilerplate

Hardhat boilerplate for compiling, deploying, and testing Solidity contracts on local EVM networks and on preconfigured public RPC targets.

Current capabilities

• Solidity 0.8.9 project with optimizer enabled and artifacts stored in .data/.
• Local execution on hardhat, devnet at 127.0.0.1:8545, and docker at 127.0.0.1:9545.
• Deploy and verify scripts for local networks plus preconfigured public-network entries.
• Unit tests and external-RPC integration tests.
• Contract size reporting and file watching.
• Repository-specific AI instructions, skills, prompts, and operational docs.

Included contracts

Contract	Purpose
contracts/permissions/MAC.sol	Managed access control with an agent model built on OpenZeppelin AccessControl.
contracts/tokens/UserCreditToken.sol	ERC-20 token that inherits MAC and grants mint and pause capabilities to agents.
contracts/eips/*.sol	Example ERC contracts kept as references and experimentation fixtures.

Scope note

The repository includes network presets for public chains, but public deployments still require real RPC credentials, funded accounts, and explorer API keys. Local verification on hardhat, devnet, and docker is implemented as dry-run validation against deployed bytecode rather than explorer publication.

---

📦 Prerequisites

Before you begin, ensure you have met the following requirements:

• Node.js: Install Node.js from the official website.
• Yarn: Install Yarn using npm:

  npm install -g yarn

• Docker: Install Docker from the official website.
• Hardhat: Install Hardhat using npm:

  npm install -g hardhat

🚀 Getting Started

1. Clone the Repository:

   git clone https://github.com/netzulo/evm-deployer-boilerplate.git

2. Install Dependencies: Navigate into the project directory and install the necessary dependencies.

   cd evm-deployer-boilerplate
   yarn install

3. Configure Your Environment: Set up your private key and optional local RPC overrides in .env.

4. Deploy to a EVM Chain: Run the deployment script to initiate the VM setup process.

   yarn deploy

5. Run the validated local workflow:

   yarn lint
   yarn build
   yarn test:unit
   yarn test:integration:devnet
   yarn test:integration:docker

6. Use the local knowledge base: Detailed operational guidance lives in docs/. Start with:

   • docs/README.md
   • docs/local-development.md
   • docs/testing.md

---

🛠️ Contributing

We welcome contributions! If you want to improve the boilerplate, fix bugs, or add new features, feel free to fork the repository and submit a pull request.

How to Contribute:

• Fork the repository.
• Create a new branch (git checkout -b feature-branch).
• Make your changes and commit them.
• Execute yarn ci to ensure your code is properly formatted.
• Push to your branch (git push origin feature-branch).
• Open a pull request.

Scripts:

Script "yarn ci" will run the following commands in strict order:

---

📝 Scripts

The following table describes the available scripts in the package.json file and how to use them to manage your project:

Script	Description
clean:rm	Removes generated files such as node_modules, artifacts, and dependency lock files.
clean:hardhat	Cleans up artifacts generated by Hardhat.
clean	Runs clean:rm to fully clean the project.
configure	Copies the .env.example file to .env to set up the environment configuration.
lint	Runs Hardhat's static checks to ensure the code is properly formatted and error-free.
dev	Runs lint and starts Hardhat's compilation watcher for continuous development.
build	Compiles the project using Hardhat.
test:unit	Runs the unit tests on the in-process Hardhat network.
test:integration	Runs the integration suite against an already running devnet RPC on port 8545.
test:integration:devnet	Starts a local Hardhat node, waits for the RPC, runs integration tests, and stops the node.
test:integration:docker	Builds, starts Docker Compose, waits for the RPC, runs integration tests, and tears the stack down.
test:sizer	Measures the size of deployed contracts using Hardhat.
test	Runs the test suite with code coverage enabled.
ci	Cleans the project, installs dependencies, checks the code, and compiles it for CI pipelines.
ci:deploy	Runs ci and then deploys the smart contracts to the configured networks.
ci:verify	Runs ci and then verifies the deployed smart contracts on the respective blockchains.
chain:stress	Runs a stress test script on the local Hardhat network.
deploy	Deploys the smart contracts to the configured network.
deploy:<network>	Deploys the smart contracts to the specified network (e.g., ethereum, polygon, optimism, etc.).
deploy:docker	Deploys contracts to the Docker-exposed local RPC on port 9545.
chain:devnet	Starts a local Hardhat development network.
verify	Verifies deployed contracts on the configured network.
verify:docker	Validates local deployments on the Docker RPC and writes a verification report.
verify:<network>	Verifies deployed contracts on the specified network (e.g., ethereum, polygon, arbitrum, etc.).

Replace <network> with the appropriate blockchain network, such as ethereum, polygon, bsc, arbitrum, optimism, coinbase, or others supported in the project.

🐋 Docker

Docker is a key component of this boilerplate, enabling you to create isolated environments for your EVM deployments. By using Docker, you can ensure consistency across different development and production environments.

With Docker CLI

1. Build Docker Image: Navigate to the project directory and build the Docker image.

   docker build -t evm-deployer .

2. Run Docker Container: Start a Docker container using the built image.

   docker run -it --rm --name evm-deployer-container evm-deployer

With Docker Compose

For more complex setups, you can use Docker Compose to manage multi-container Docker applications.

1. Start Services: Use Docker Compose to start all required services.

   docker compose up -d --build

2. Stop Services: Stop the services when you are done.

   docker compose down --remove-orphans

3. Run integration tests against the local RPC:

   yarn test:integration:docker

By leveraging Docker, you can streamline your development workflow and ensure that your EVM deployments are consistent and reproducible across different environments.

---

🪙 Supported Blockchains

This boilerplate includes configuration entries for the following blockchain networks:

• Ethereum (Mainnet)
• Goerli (Ethereum Testnet)
• Polygon (Mainnet)
• Mumbai (Polygon Testnet)
• Binance Smart Chain (BSC) (Mainnet)
• BSC Testnet
• Arbitrum (Mainnet)
• Arbitrum Goerli (Testnet)
• Optimism (Mainnet)
• Optimism Goerli (Testnet)
• Coinbase (Layer 2 solution by Coinbase)
• Devnet (Local development network)
• Docker (Local development via Docker)
• Hardhat (Local testing environment)

Public-network use still requires valid RPC credentials and, for explorer verification, the corresponding API keys.

---

🔗 References

• Ethereum
• Arbitrum
• Polygon

---

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

🌍 Connect With Us

Join our community and stay updated on new features:

• Twitter
• GitHub

💸 Donate

If you find this project useful and would like to support its development, you can make a donation using ETH or ARB through Arbitrum One or Polygon.

🪙 Ethereum / Arbitrum Address: 0xe3744590376c22B9D010d3CAfee796d5EbDBA9A8

To donate, simply send ETH from ethereum, or ARB from arbitrum network to the above address.

You can send donations directly to the address using your preferred wallet or by clicking the button below:

Thank you for your support! 🙌