� Hardhat Boilerplate

A production-ready Hardhat boilerplate for deploying ERC721 NFT smart contracts to MACTestnet with full TypeScript support, comprehensive testing, and automated deployment scripts.

📋 Table of Contents

• Overview
• Supported Networks
• Quick Start
• Project Structure
• Available Commands
• Configuration
• Deployment
• Testing
• Development

🎯 Overview

This boilerplate provides a complete setup for developing and deploying NFT contracts to the MAC blockchain ecosystem. It includes:

• Two pre-built NFT contract implementations (basic and meta-transaction enabled)
• Ready-to-use deployment scripts
• Comprehensive test suite with gas reporting
• TypeScript type generation with TypeChain
• Development tools and utilities

Perfect for quickly launching NFT projects without starting from scratch.

🌐 Supported Networks

MACTestnet (Recommended for Development)

• Chain ID: 20017
• RPC URL: https://collator1.baliola.dev
• Status: ✅ Full support
• Use Case: Ideal for testing and development before mainnet deployment

📦 Quick Start

Prerequisites

• Node.js >= 20.10.x
• pnpm (or npm)

Installation

# Install dependencies
pnpm install

# Compile contracts
pnpm compile

# Run tests
pnpm test

First Deployment (Local)

# Terminal 1: Start local Hardhat node
pnpm local-node

# Terminal 2: Deploy to localhost
pnpm deploy:nft-project

📁 Project Structure

/artifacts

Compiled contract artifacts and build information.

• Contains ABI files and bytecode
• Organized by contract name
• Used by TypeChain for type generation
• Purpose: Bridge between Solidity and JavaScript/TypeScript

/config

Deployment configuration and arguments.

• NftConfig.ts - Main configuration file with network settings and contract addresses
• NftProjectArguments.ts - Constructor arguments for basic NFT contract
• NftProjectWithMetaTxArguments.ts - Constructor arguments for meta-transaction enabled contract
• Purpose: Centralize deployment parameters and contract addresses for all networks

/contracts

Solidity smart contract source files.

• NftProject.sol - Basic ERC721 NFT implementation
• NftProjectWithMetaTx.sol - ERC721 with EIP-712 meta-transaction support
• utils/MetaTransaction.sol - Utility for meta-transaction handling
• Purpose: Smart contract logic and business rules

/lib

TypeScript utility libraries and interfaces.

• Networks.ts - Network configuration definitions
• NftConfigInterface.ts - Configuration type definitions
• NftProvider.ts - Contract interaction utilities
• NftMetaTxProvider.ts - Meta-transaction utilities
• Purpose: Shared code and type definitions for TypeScript development

/scripts

Deployment and automation scripts.

• 1.deploy_nft_project.ts - Deploy basic NFT contract
• 2.deploy_nft_with_metaTx.ts - Deploy NFT with meta-transaction support
• utils/helpers.ts - Shared deployment utilities
• utils/verify-contract.ts - Contract verification helpers
• Purpose: Automate deployment and verification processes

/test

Test suite for smart contracts.

• NftProject.test.ts - Comprehensive test cases for contract NftProject.sol
• NftProjectWithMetaTx.test.ts - Comprehensive test cases for contract NftProjectWithMetaTx.sol that implementing EIP712 for gas less transaction
• Purpose: Validate contract functionality and security

/typechain-types

Auto-generated TypeScript type definitions.

• Generated by TypeChain from contract ABIs
• Provides full type safety for contract interactions
• Organized by contract and factory classes
• Purpose: IDE autocomplete and type checking for smart contract interactions

🔧 Available Commands

Development

# List available accounts
pnpm accounts

# Start local Hardhat node
pnpm local-node

# Compile contracts
pnpm compile

# Run all tests
pnpm test

# Run tests with gas reporting
pnpm test-gas

Deployment

# Deploy basic NFT contract
pnpm deploy:nft-project --network <Blockchain Network>

# Deploy NFT with meta-transaction support
pnpm deploy:nft-with-meta-tx --network <Blockchain Network>

# Verify basic NFT contract on block explorer
pnpm verify:nft-project <CONTRACT_ADDRESS> --network <Blockchain Network>

# Verify meta-transaction NFT contract on block explorer
pnpm verify:nft-with-meta-tx <CONTRACT_ADDRESS> --network <Blockchain Network>

⚙️ Configuration

Edit config/NftConfig.ts to customize your deployment:

const NftConfig: NftConfigInterface = {
  // Network settings
  mainnet: Networks.MacTestnet,      // Primary network
  testnet: Networks.MacTestnet,      // Test network

  // Contract metadata
  name: 'MyNFT',                     // Token name
  symbol: 'NFT',                     // Token symbol
  version: '1',                      // EIP-712 version
  baseURI: 'https://api.example.com/metadata/',

  // Deployed contract addresses (update after deployment)
  nftContractAddress: '0x...',           // MACTestnet
  nftContractAddressTestnet: '0x...',    // Testnet fallback
  nftContractAddressLocal: '0x...',      // Local testing
};

Environment Variables

Create a .env file in the root directory:

# Network RPC URLs (optional - defaults are provided)
NETWORK_TESTNET_URL=https://collator1.baliola.dev
NETWORK_MAINNET_URL=your_mainnet_rpc_url

# Private Keys (NEVER commit these!)
NETWORK_TESTNET_PRIVATE_KEY=your_private_key
NETWORK_MAINNET_PRIVATE_KEY=your_mainnet_private_key

# Optional: Gas reporting
REPORT_GAS=true

🚀 Deployment

Deploy to MACTestnet

# 1. Set your private key in .env
NETWORK_TESTNET_PRIVATE_KEY=your_key

# 2. Compiling contracts
pnpm compile

# 3. Deploy the contract
pnpm deploy:nft-project --network <Blockchain Network>

# 4. Verify on block explorer (optional)
pnpm verify:nft-project <CONTRACT_ADDRESS> --network <Blockchain Network>

The deployment script will:

• Deploy to MACTestnet
• Display contract address and transaction details
• Save deployment information for future reference in config file

🧪 Testing

Run Tests

# Run all tests
pnpm test

# Run with detailed gas reporting
pnpm test-gas

Test Coverage

The test suite validates:

• ✅ Contract deployment and initialization
• ✅ NFT minting and token transfers
• ✅ Metadata and URI management
• ✅ Access control and permissions
• ✅ Edge cases and error conditions
• ✅ Gas efficiency

🛠 Development Workflow

1. Local Development

# Start local node
pnpm local-node

# In another terminal, run tests
pnpm test

# Or deploy to local node
pnpm deploy:nft-project --network localhost

2. Modify Contracts

Edit files in /contracts directory. Changes are automatically detected.

3. Recompile

pnpm compile

4. Test Changes

pnpm test

5. Deploy to Testnet

pnpm deploy:nft-project --network <Blockchain Network>

🔒 Security Notes

• Always test thoroughly on testnet before mainnet deployment
• Use environment variables for private keys - never commit them
• Keep dependencies updated: pnpm update
• Review contract code and deployment arguments before mainnet

📄 License

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

---

⚠️ Disclaimer: This is a development boilerplate. Always conduct thorough testing before deploying to production. The creators are not responsible for any loss or damage resulting from contract deployment or use.