Deploy an ERC-20 Token on Humanity Testnet using Hardhat

This guide walks you through deploying an ERC-20 token smart contract on the Humanity Protocol network using Hardhat and MetaMask.

Prerequisites

Before you begin, you need to install the following dependencies:

• Node.js v22.14.0 or later

⚠️ Note

If you are on Windows, we strongly recommend using WSL 2 when following this guide.

You can find the code for this tutorial in the following repo. Remember to rename your .env.example to .env adding your private key and Alchemy API Key

https://github.com/humanity-org/hp-human-only-airdrop-off-chain-contractsgithub.com

It covers the complete development workflow, from initial setup and configuration to deployment and verification. You'll learn how to set up Hardhat for the Humanity Protocol testnet, configure your environment variables, write and test an ERC-20 smart contract with optional initial token transfer functionality, deploy it to the network, and verify your deployed contract on the Humanity Protocol block explorer.

Before deploying your first smart contract to the Humanity Protocol testnet, you'll need to configure your wallet and get some testnet tokens.

If you haven't already, install the MetaMask browser extension and create a wallet.

⚠️

Always use a dedicated test wallet for development — never use a wallet that holds real assets. Testnets are for experimentation, and it's safer to separate your development activities from your personal or mainnet funds.

To connect MetaMask to the Humanity testnet and get some testnet tokens, follow the steps here:

📚 Working with Humanity Testnet

Project Setup

Now we have completed our wallet setup, let's first create the folder and basic structure of our project:

mkdir humanity-erc20-contract && cd humanity-erc20-contract
echo "node_modules \\\\n .env \\\\n cache \\\\n artifacts" >> .gitignore
echo "# humanity-erc20-contract" >> README.md
git init
git branch -M main
touch package.json

Add the following content to your package.json:

{
  "name": "humanity-erc20-contract",
  "version": "1.0.0",
  "description": "Simple project for deploying an ERC-20 token (DemoToken) to Humanity Protocol testnet. The token can be used for backend-controlled airdrops with off-chain human verification via Humanity Protocol SDK/API.",
  "scripts": {
    "compile": "npx hardhat compile",
    "test": "npx hardhat test",
    "deploy": "npx hardhat run scripts/deploy.js --network humanity-testnet"
  },
  "devDependencies": {
    "@nomicfoundation/hardhat-toolbox": "^5.0.0",
    "@openzeppelin/contracts": "^5.0.0",
    "dotenv": "^16.5.0",
    "hardhat": "^2.22.17"
  },
  "dependencies": {
    "ethers": "^6.14.4"
  }
}

Install all the packages with:

npm install

Let's now create the folder structure for our project by creating contracts, scripts and test folders inside the /humanity-erc20-contract root folder. Also let's create an .env file and a hardhat.config.js file at the root level. Your folder structure should look like this:

humanity-erc20-contract/
├── contracts/
├── scripts/
├── test/
├── .env
├── .gitignore
├── hardhat.config.js
├── README.md
└── package.json

Environment Configuration

Now inside our .env file add the following variables:

# Wallet Configuration
# This wallet will be the contract owner and receive initial tokens
PRIVATE_KEY=<YOUR_PRIVATE_KEY>

# Humanity Protocol Testnet Configuration
# Get a free API key at <https://dashboard.alchemy.com/> (recommended)
# Or use the public endpoint: <https://humanity-testnet.g.alchemy.com/public>
HUMANITY_TESTNET=https://humanity-testnet.g.alchemy.com/v2/<YOUR_ALCHEMY_API_KEY>
HUMANITY_API_URL=https://humanity-testnet.explorer.alchemy.com/api
HUMANITY_BROWSER_URL=https://humanity-testnet.explorer.alchemy.com

# Optional: Initial Token Transfer on Deployment
# Send tokens to another address during contract deployment (saves gas)
# Example use cases:
# - Airdrop backend wallet: Send tokens directly to your distribution wallet
# - Treasury: Send to a multisig or treasury address
# - Team allocation: Send to team vesting contract
# Leave blank or use 0x0000000000000000000000000000000000000000 to skip
INITIAL_RECIPIENT=
# Amount in DEMO tokens (not wei). Example: 500000 = 500,000 DEMO tokens
INITIAL_AMOUNT=

For this tutorial we are using MetaMask and the private key associated with our test account holding our testnet tokens. In order to get the private key from your account follow these instructions:

How to export a private key in MetaMask Extension and Mobile | MetaMask Help Centersupport.metamask.io

Replace <YOUR_PRIVATE_KEY> with the one you just copied from MetaMask.

In order to use the Alchemy API Key to connect with Humanity testnet network please follow this tutorial:

How To Create a New Alchemy API Key?Alchemy

Once we have our Alchemy API Key, let's add it to our .env file replacing <YOUR_ALCHEMY_API_KEY> with your own Key.

⚠️ Alchemy API Key

If you do not have an Alchemy account you can still use https://humanity-testnet.g.alchemy.com/public as your HUMANITY_TESTNET variable but you may encounter errors during deployment later on due to polling to public endpoint for block confirmations too often.

Hardhat Configuration

Let's now configure Hardhat. Add the following to the hardhat.config.js:

require('@nomicfoundation/hardhat-toolbox')
require('dotenv').config()

const PRIVATE_KEY = process.env.PRIVATE_KEY || '0xkey'

const HUMANITY_TESTNET = process.env.HUMANITY_TESTNET || ''
const HUMANITY_API_URL = process.env.HUMANITY_API_URL || ''
const HUMANITY_BROWSER_URL = process.env.HUMANITY_BROWSER_URL || ''

/** @type import('hardhat/config').HardhatUserConfig */
module.exports = {
  solidity: {
    compilers: [
      {
        version: '0.8.20',
      },
    ],
  },
  defaultNetwork: 'hardhat',
  networks: {
    hardhat: {},
    'humanity-testnet': {
      url: HUMANITY_TESTNET,
      accounts: PRIVATE_KEY !== '0xkey' ? [PRIVATE_KEY] : [],
    },
    localhost: {
      url: '<http://127.0.0.1:8545/>',
      chainId: 31337,
    },
  },
  etherscan: {
    apiKey: {
      'humanity-testnet': 'empty',
    },
    customChains: [
      {
        network: 'humanity-testnet',
        chainId: 7080969,
        urls: {
          apiURL: HUMANITY_API_URL,
          browserURL: HUMANITY_BROWSER_URL,
        },
      },
    ],
  },
}

Smart Contract

Inside our contracts folder let's create our smart contract. Let's call it DemoToken.sol:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

import "@openzeppelin/contracts/token/ERC20/ERC20.sol";
import "@openzeppelin/contracts/access/Ownable.sol";

/**
 * @title DemoToken
 * @dev Simple ERC-20 token for demonstration purposes.
 *
 * Features:
 * - Initial supply of 1,000,000 DEMO tokens
 * - Owner can mint additional tokens if needed
 * - Optional initial transfer during deployment
 * - 18 decimals (standard)
 */
contract DemoToken is ERC20, Ownable {
    uint256 public constant INITIAL_SUPPLY = 1_000_000 * 10**18; // 1 million tokens

    /**
     * @dev Constructor mints initial supply to deployer
     * @param initialRecipient Optional address to send tokens to (use address(0) to send all to deployer)
     * @param initialAmount Optional amount to send to initialRecipient (only used if initialRecipient != address(0))
     */
    constructor(
        address initialRecipient,
        uint256 initialAmount
    ) ERC20("Demo Token", "DEMO") Ownable(msg.sender) {
        // Mint all tokens to deployer first
        _mint(msg.sender, INITIAL_SUPPLY);

        // If initialRecipient is specified and valid, transfer tokens
        if (initialRecipient != address(0) && initialAmount > 0) {
            require(initialAmount <= INITIAL_SUPPLY, "Initial amount exceeds supply");
            _transfer(msg.sender, initialRecipient, initialAmount);
        }
    }

    /**
     * @dev Allows owner to mint additional tokens
     * @param to Address to mint tokens to
     * @param amount Amount of tokens to mint (in wei, i.e., with 18 decimals)
     */
    function mint(address to, uint256 amount) external onlyOwner {
        _mint(to, amount);
    }

    /**
     * @dev Returns the number of decimals used for token amounts
     */
    function decimals() public pure override returns (uint8) {
        return 18;
    }
}

This contract includes:

• ERC-20 standard implementation using OpenZeppelin

• Initial supply of 1,000,000 DEMO tokens minted to deployer

• Optional initial transfer - Can send tokens to another address during deployment (gas efficient!)

• Minting capability - Owner can mint additional tokens as needed

• Ownership control - Owner can transfer ownership or renounce it

Use Cases

This token setup is ideal for:

• Backend-controlled airdrops - Send tokens directly from distribution wallet

• Treasury management - Send initial supply to multisig

• Team allocations - Transfer to vesting contracts

• Staking rewards - Fund reward pools

The optional initial transfer feature saves approximately ~21,000 gas compared to separate deployment and transfer transactions!

Testing

Inside our test folder let's create a test file to test our contract before deployment, so we are sure it works before sending it to the blockchain and spending any tokens. Let's call it DemoToken.test.js:

const { expect } = require('chai')
const { ethers } = require('hardhat')

describe('DemoToken', function () {
  let demoToken, owner, addr1, addr2

  beforeEach(async function () {
    ;[owner, addr1, addr2] = await ethers.getSigners()

    const DemoToken = await ethers.getContractFactory('DemoToken')
    // Deploy without initial transfer (all tokens to deployer)
    demoToken = await DemoToken.deploy(ethers.ZeroAddress, 0)
    await demoToken.waitForDeployment()
  })

  describe('Deployment', function () {
    it('Should set the correct token name', async function () {
      expect(await demoToken.name()).to.equal('Demo Token')
    })

    it('Should set the correct token symbol', async function () {
      expect(await demoToken.symbol()).to.equal('DEMO')
    })

    it('Should set the correct decimals', async function () {
      expect(await demoToken.decimals()).to.equal(18)
    })

    it('Should set the right owner', async function () {
      expect(await demoToken.owner()).to.equal(owner.address)
    })

    it('Should mint initial supply to deployer', async function () {
      const expectedSupply = ethers.parseEther('1000000')
      expect(await demoToken.balanceOf(owner.address)).to.equal(expectedSupply)
    })

    it('Should have correct total supply', async function () {
      const expectedSupply = ethers.parseEther('1000000')
      expect(await demoToken.totalSupply()).to.equal(expectedSupply)
    })
  })

  describe('Initial Transfer on Deployment', function () {
    it('Should transfer tokens to initial recipient on deployment', async function () {
      const DemoToken = await ethers.getContractFactory('DemoToken')
      const transferAmount = ethers.parseEther('500000') // 500k tokens

      const newToken = await DemoToken.deploy(addr1.address, transferAmount)
      await newToken.waitForDeployment()

      // Check recipient received tokens
      expect(await newToken.balanceOf(addr1.address)).to.equal(transferAmount)

      // Check deployer has remaining tokens
      const expectedDeployerBalance = ethers.parseEther('500000')
      expect(await newToken.balanceOf(owner.address)).to.equal(expectedDeployerBalance)
    })

    it('Should send all tokens to deployer if no recipient specified', async function () {
      const DemoToken = await ethers.getContractFactory('DemoToken')
      const newToken = await DemoToken.deploy(ethers.ZeroAddress, 0)
      await newToken.waitForDeployment()

      const expectedSupply = ethers.parseEther('1000000')
      expect(await newToken.balanceOf(owner.address)).to.equal(expectedSupply)
      expect(await newToken.balanceOf(addr1.address)).to.equal(0)
    })

    it('Should ignore amount if recipient is zero address', async function () {
      const DemoToken = await ethers.getContractFactory('DemoToken')
      const newToken = await DemoToken.deploy(ethers.ZeroAddress, ethers.parseEther('100000'))
      await newToken.waitForDeployment()

      const expectedSupply = ethers.parseEther('1000000')
      expect(await newToken.balanceOf(owner.address)).to.equal(expectedSupply)
    })

    it('Should fail if initial amount exceeds supply', async function () {
      const DemoToken = await ethers.getContractFactory('DemoToken')
      const tooMuch = ethers.parseEther('2000000') // More than INITIAL_SUPPLY

      await expect(
        DemoToken.deploy(addr1.address, tooMuch)
      ).to.be.revertedWith('Initial amount exceeds supply')
    })
  })
})

Deployment Script

Finally let's create a deployment script inside our scripts folder called deploy.js:

const hre = require('hardhat')

async function main() {
  console.log('🚀 Deploying DemoToken to Humanity Testnet...\\n')
  console.log(`Network: ${hre.network.name}`)

  const [deployer] = await hre.ethers.getSigners()
  console.log('📝 Deploying with account:', deployer.address)

  const balance = await hre.ethers.provider.getBalance(deployer.address)
  console.log('💰 Account balance:', hre.ethers.formatEther(balance), 'tHP\\n')

  // ========================================
  // Deploy DemoToken
  // ========================================
  console.log('1️⃣  Deploying DemoToken...')

  // Optional: Set initial recipient and amount
  // To send tokens to backend wallet on deployment, set these values:
  const INITIAL_RECIPIENT = process.env.INITIAL_RECIPIENT || hre.ethers.ZeroAddress
  const INITIAL_AMOUNT = process.env.INITIAL_AMOUNT
    ? hre.ethers.parseEther(process.env.INITIAL_AMOUNT)
    : 0

  if (INITIAL_RECIPIENT !== hre.ethers.ZeroAddress && INITIAL_AMOUNT > 0) {
    console.log(`   Initial transfer: ${hre.ethers.formatEther(INITIAL_AMOUNT)} DEMO to ${INITIAL_RECIPIENT}`)
  }

  const DemoToken = await hre.ethers.getContractFactory('DemoToken')
  const demoToken = await DemoToken.deploy(INITIAL_RECIPIENT, INITIAL_AMOUNT)
  await demoToken.waitForDeployment()
  const demoTokenAddress = await demoToken.getAddress()
  console.log('✅ DemoToken deployed to:', demoTokenAddress)

  // ========================================
  // Verify token details
  // ========================================
  console.log('\\n2️⃣  Verifying token details...')
  const name = await demoToken.name()
  const symbol = await demoToken.symbol()
  const decimals = await demoToken.decimals()
  const totalSupply = await demoToken.totalSupply()
  const deployerBalance = await demoToken.balanceOf(deployer.address)

  console.log('   Token Name:', name)
  console.log('   Token Symbol:', symbol)
  console.log('   Decimals:', decimals)
  console.log('   Total Supply:', hre.ethers.formatEther(totalSupply), symbol)
  console.log('   Deployer Balance:', hre.ethers.formatEther(deployerBalance), symbol)

  // ========================================
  // Wait for confirmations before verification
  // ========================================
  if (hre.network.name !== 'hardhat' && hre.network.name !== 'localhost') {
    console.log('\\n3️⃣  Waiting for block confirmations...')
    try {
      await demoToken.deploymentTransaction().wait(5)
      console.log('✅ Deployment confirmed!')

      // Wait additional time for explorer indexing
      console.log('⏳ Waiting 30 seconds for explorer to index contract...')
      await new Promise((resolve) => setTimeout(resolve, 30000))
    } catch (error) {
      console.log(
        '⚠️  Warning: Could not wait for confirmations (rate limit), but deployment was successful!'
      )
    }

    // ========================================
    // Verify contract on block explorer
    // ========================================
    console.log('\\n4️⃣  Verifying contract on block explorer...')

    try {
      await hre.run('verify:verify', {
        address: demoTokenAddress,
        constructorArguments: [INITIAL_RECIPIENT, INITIAL_AMOUNT.toString()],
      })
      console.log('✅ DemoToken verified!')
    } catch (error) {
      if (error.message.includes('Already Verified')) {
        console.log('ℹ️  DemoToken already verified')
      } else {
        console.log('⚠️  DemoToken verification failed:', error.message)
        console.log('\\n   You can verify manually with:')
        console.log(
          `   npx hardhat verify --network humanity-testnet ${demoTokenAddress} "${INITIAL_RECIPIENT}" "${INITIAL_AMOUNT.toString()}"`
        )
      }
    }
  }

  // ========================================
  // Summary
  // ========================================
  console.log('\\n✨ Deployment complete!\\n')
  console.log('📋 Contract Information:\\n')
  console.log(`TOKEN_CONTRACT_ADDRESS=${demoTokenAddress}`)
  console.log(`TOKEN_NAME=${name}`)
  console.log(`TOKEN_SYMBOL=${symbol}`)
  console.log(`DEPLOYER_ADDRESS=${deployer.address}`)
  console.log(`INITIAL_SUPPLY=${hre.ethers.formatEther(totalSupply)}`)
  console.log('\\n📋 Network Information:\\n')
  console.log(`CHAIN_ID=7080969`)
  console.log(
    `RPC_URL=${process.env.HUMANITY_TESTNET || '<https://humanity-testnet.g.alchemy.com/public>'}`
  )
  console.log(
    `BLOCK_EXPLORER_URL=${process.env.HUMANITY_BROWSER_URL || '<https://humanity-testnet.explorer.alchemy.com>'}`
  )
  console.log(
    `\\n🔗 View on Explorer: ${process.env.HUMANITY_BROWSER_URL || '<https://humanity-testnet.explorer.alchemy.com>'}/address/${demoTokenAddress}\\n`
  )
}

main()
  .then(() => process.exit(0))
  .catch((error) => {
    console.error(error)
    process.exit(1)
  })

Compile the Contract

We are ready to compile our contract by running:

npm run compile

You should see output indicating successful compilation.

Run Tests

Let's first test our contract by running:

npm run test

We should see something like this on our terminal:

DemoToken
  Deployment
    ✔ Should set the correct token name
    ✔ Should set the correct token symbol
    ✔ Should set the correct decimals
    ✔ Should set the right owner
    ✔ Should mint initial supply to deployer
    ✔ Should have correct total supply
  Initial Transfer on Deployment
    ✔ Should transfer tokens to initial recipient on deployment
    ✔ Should send all tokens to deployer if no recipient specified
    ✔ Should ignore amount if recipient is zero address
    ✔ Should fail if initial amount exceeds supply

10 passing (4s)

Deploy to Humanity Protocol Testnet

Now we are finally ready to deploy our contract! You have two options:

Option A: Deploy with all tokens to deployer (default)

npm run deploy

Option B: Deploy with initial token transfer (Recommended)

This saves gas by combining deployment and token transfer in a single transaction.

First, add to your .env file:

INITIAL_RECIPIENT=0xYourBackendWalletAddress
INITIAL_AMOUNT=500000  # 500,000 DEMO tokens

Then deploy:

npm run deploy

You should see something like this in your terminal:

🚀 Deploying DemoToken to Humanity Testnet...

Network: humanity-testnet
📝 Deploying with account: 0xYourAddress...
💰 Account balance: 0.5 tHP

1️⃣  Deploying DemoToken...
   Initial transfer: 500000.0 DEMO to 0xRecipientAddress
✅ DemoToken deployed to: 0xABC123...

2️⃣  Verifying token details...
   Token Name: Demo Token
   Token Symbol: DEMO
   Decimals: 18
   Total Supply: 1000000.0 DEMO
   Deployer Balance: 500000.0 DEMO

3️⃣  Waiting for block confirmations...
✅ Deployment confirmed!
⏳ Waiting 30 seconds for explorer to index contract...

4️⃣  Verifying contract on block explorer...
✅ DemoToken verified!

✨ Deployment complete!

📋 Contract Information:

TOKEN_CONTRACT_ADDRESS=0xABC123...
TOKEN_NAME=Demo Token
TOKEN_SYMBOL=DEMO
DEPLOYER_ADDRESS=0xYourAddress...
INITIAL_SUPPLY=1000000.0

📋 Network Information:

CHAIN_ID=7080969
RPC_URL=https://humanity-testnet.g.alchemy.com/v2/...
BLOCK_EXPLORER_URL=https://humanity-testnet.explorer.alchemy.com

🔗 View on Explorer: <https://humanity-testnet.explorer.alchemy.com/address/0xABC123>...

⚠️

If you encounter some errors, it's probably due to using the Alchemy public RPC endpoint. To avoid this, please get your own API key here. In any case, even with errors, your contract should be deployed!

View Your Contract on Explorer

In order to see your deployed contract, visit Humanity Protocol Testnet Explorer and search for your contract address using the TOKEN_CONTRACT_ADDRESS from the previous step and click on the item that pops up.

It will take you to your contract page. If you click on the Transactions tab you will see the details from your deployment transaction.

Manual Verification (if needed)

If automatic verification failed, you can verify manually using Hardhat:

Without initial transfer:

npx hardhat verify --network humanity-testnet <TOKEN_ADDRESS> "0x0000000000000000000000000000000000000000" "0"

With initial transfer:

npx hardhat verify --network humanity-testnet <TOKEN_ADDRESS> "<INITIAL_RECIPIENT>" "<INITIAL_AMOUNT_IN_WEI>"

Example:

npx hardhat verify --network humanity-testnet 0xABC123... "0xRecipientAddress" "500000000000000000000000"

You should see something similar in your terminal:

[WARNING] Network and explorer-specific api keys are deprecated...
Successfully submitted source code for contract
contracts/DemoToken.sol:DemoToken at <DEPLOYED_CONTRACT_ADDRESS>
for verification on the block explorer. Waiting for verification result...

Successfully verified contract DemoToken on the block explorer.
<https://humanity-testnet.explorer.alchemy.com/address/><DEPLOYED_CONTRACT_ADDRESS>#code

You should see our contract has been verified and able to see our Solidity code, compiler and ABI details rather than just our Bytecode.

Interact with Your Contract

Besides viewing the contract, verifying gives us the ability to test our functions directly from the explorer. If we click on the Contract tab and then Write Contract sub-tab, we will see our DemoToken.sol functions and we can start calling them directly from the explorer.

⚠️

In order to interact with our contract we must connect to the Humanity Protocol website explorer by clicking on the Connect button located at the top right portion of the screen.

The explorer will give us also the option to simulate our transactions and will print the estimated gas for the real transaction.

Congratulations, you have successfully set up your development environment with Hardhat, connected your MetaMask wallet to the Humanity Protocol Testnet, obtained test tokens from the faucet, configured your project settings, and tested as well as deployed an ERC-20 token contract on the network.