Token Factory - ERC20 Token Deployment Platform

This project is a Token Factory smart contract system that enables users to deploy custom ERC20 tokens on-demand with advanced features. Built with Hardhat 3 Beta, it provides a flexible and secure platform for creating tokens with configurable minting, burning, pause, and blacklist capabilities.

To learn more about the Hardhat 3 Beta, please visit the Getting Started guide. To share your feedback, join our Hardhat 3 Beta Telegram group or open an issue in our GitHub issue tracker.

Features

TokenFactory Contract

• On-Demand Token Creation: Deploy custom ERC20 tokens with a single transaction
• Fee Management: Configurable creation fees with automatic refunding of excess ETH
• Token Tracking: Track all tokens created by address and globally
• Admin Controls: Owner can update creation fees and fee recipient

ERC20Token Features

Each token created through the factory includes:

• Standard ERC20: Full compliance with ERC20 standard
• Custom Decimals: Support for 0-18 decimal places
• Optional Minting: Enable/disable minting with max supply enforcement
• Optional Burning: Enable/disable token burning
• Pause/Unpause: Owner can pause all transfers
• Blacklist Management: Block specific addresses from sending/receiving tokens
• Max Supply Control: Enforce maximum token supply limits

Project Structure

contracts/
├── TokenFactory.sol      # Factory contract for deploying tokens
├── ERC20Token.sol       # Custom ERC20 implementation with advanced features
├── Ownable.sol          # Custom ownership management
└── test/
    ├── TokenFactory.t.sol   # Factory unit tests (Forge)
    └── ERC20Token.t.sol     # Token unit tests (Node.js)

ignition/
└── modules/
    └── TokenFactory.ts   # Hardhat Ignition deployment module

Installation

Ensure you have Node.js installed, then install dependencies:

npm install
# or
yarn install

Usage

Running Tests

Run all tests in the project:

npx hardhat test

Run only Solidity tests (Forge-style):

npx hardhat test solidity

Run only Node.js integration tests:

npx hardhat test nodejs

Deployment

Deploy to Local Network

Deploy the TokenFactory to a local Hardhat network:

npx hardhat ignition deploy ignition/modules/TokenFactory.ts

Deploy to Sepolia Testnet

First, configure your private key using the hardhat-keystore plugin:

npx hardhat keystore set SEPOLIA_PRIVATE_KEY

Then deploy to Sepolia:

npx hardhat ignition deploy --network sepolia ignition/modules/TokenFactory.ts

Deploy to Amoy Testnet (Polygon)

Configure your private key:

npx hardhat keystore set AMOY_PRIVATE_KEY

Deploy to Amoy:

npx hardhat ignition deploy --network amoy ignition/modules/TokenFactory.ts

Creating Tokens

After deploying the TokenFactory, you can create tokens by calling the createToken function with the following parameters:

interface TokenParams {
  name: string;              // Token name (e.g., "My Token")
  symbol: string;            // Token symbol (e.g., "MTK")
  decimals: uint8;           // Decimal places (0-18)
  initialSupply: uint256;    // Initial token supply
  initialHolder: address;    // Address to receive initial supply
  maxSupply: uint256;        // Maximum supply (0 for unlimited)
  config: {
    _isMintable: boolean;    // Enable minting
    _isBurnable: boolean;    // Enable burning
    _isSetTotalSupply: boolean;  // Enforce max supply
    _hasChangeOwner: boolean;     // Reserved for future use
    _isLimitTokenPerAddress: boolean; // Reserved for future use
  }
}

Example interaction using ethers/viem:

const tokenParams = {
  name: "My Custom Token",
  symbol: "MCT",
  decimals: 18,
  initialSupply: ethers.parseEther("1000000"),
  initialHolder: "0xYourAddress",
  maxSupply: ethers.parseEther("10000000"),
  config: {
    _isMintable: true,
    _isBurnable: true,
    _isSetTotalSupply: true,
    _hasChangeOwner: false,
    _isLimitTokenPerAddress: false
  }
};

// Send transaction with creation fee
await tokenFactory.createToken(tokenParams, { 
  value: await tokenFactory.creationFee() 
});

Contract API

TokenFactory Functions

createToken(TokenParams memory params) payable

Deploys a new ERC20 token with specified parameters. Requires sending the creation fee as ETH.

Events: Emits TokenCreated(address indexed tokenAddress, address indexed creator)

setCreationFee(uint256 _newFee) onlyOwner

Updates the token creation fee.

setFeeRecipient(address _newRecipient) onlyOwner

Updates the address that receives creation fees.

getTokenByCreator(address _creator) view returns (address[])

Returns all token addresses created by a specific address.

getAllTokens() view returns (address[])

Returns all token addresses created through the factory.

ERC20Token Functions

In addition to standard ERC20 functions (transfer, approve, transferFrom, balanceOf, etc.), each token includes:

mint(address account, uint256 amount) onlyOwner

Mints new tokens (if minting is enabled and max supply not exceeded).

burn(uint256 amount) onlyOwner

Burns tokens from owner's balance (if burning is enabled).

pause() onlyOwner

Pauses all token transfers.

unpause() onlyOwner

Resumes token transfers.

modifyBlacklist(address _user, bool _value) onlyOwner

Adds or removes an address from the blacklist.

getBlacklist(address _user) view returns (bool)

Checks if an address is blacklisted.

Network Configuration

The project supports multiple networks:

• hardhatMainnet: Simulated Ethereum mainnet
• hardhatOp: Simulated Optimism L2
• sepolia: Ethereum Sepolia testnet (Chain ID: 11155111)
• amoy: Polygon Amoy testnet (Chain ID: 80002)

Network configurations can be found in hardhat.config.ts.

Technology Stack

• Hardhat 3 Beta: Development framework
• Solidity 0.8.28: Smart contract language
• OpenZeppelin Contracts v5.4.0: Secure contract libraries
• Viem: TypeScript library for Ethereum interactions
• Node.js Test Runner: Native testing framework
• Forge (Foundry): Solidity testing framework
• Hardhat Ignition: Deployment system

Security Features

• Fee Validation: Ensures sufficient ETH sent for token creation
• Zero Address Checks: Prevents deployment with invalid addresses
• Access Control: Owner-only functions for sensitive operations
• Max Supply Enforcement: Prevents minting beyond configured limits
• Decimal Limits: Restricts decimals to 0-18 range
• Blacklist Protection: Prevents blacklisted addresses from transfers
• Pause Mechanism: Emergency stop for token transfers

Test Coverage

The project includes comprehensive test coverage:

TokenFactory Tests (TokenFactory.t.sol)

• Initial state validation
• Token creation and deployment
• Fee collection and refunding
• Access control and ownership
• Token tracking by creator
• Event emission verification

ERC20Token Tests (ERC20Token.t.sol)

• Initial setup and configuration
• Minting and burning functionality
• Blacklist enforcement
• Pause/unpause mechanics
• Max supply enforcement
• Invalid parameter validation

Development

Compiler Settings

The project uses Solidity 0.8.28 with optimizer enabled (200 runs) for production deployments.

Verify Contracts

After deployment, verify your contracts on Etherscan:

npx hardhat verify --network sepolia <CONTRACT_ADDRESS>

Ensure you have set your ETHERSCAN_API_KEY in the environment or configuration variables.

License

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

Contributing

Contributions are welcome! Please ensure all tests pass before submitting pull requests:

npx hardhat test

Support

For issues related to:

• Hardhat 3 Beta: Join the Hardhat 3 Beta Telegram group
• This Project: Open an issue in the project repository