Smart Contracts Set Up

This page describes how to set up the smart contracts needed for the airdrop dApp to work.

This guide walks through deploying and configuring the on-chain components required for a verification-gated airdrop using Humanity Protocol.

The goal is to get you from zero contracts to a fully funded, verification-enabled airdrop contract that can be consumed by a frontend application.

This guide focuses on what to deploy and why.

For full commands, environment variables, and scripts, always refer to the contracts repository README.

https://github.com/humanity-developers/hp-dapp-demo-contracts

What you will build

By completing this section, you will:

• Deploy a reward ERC-20 token

• Deploy a verification-gated airdrop protocol contract

• Connect the airdrop to Humanity’s Verification Oracle

• Pre-fund verification fees using the Fee Escrow

• Fund the airdrop with reward tokens

At the end, your contracts will be ready to serve verified users.

Contracts involved

This setup uses the following on-chain components:

1. DemoToken (ERC-20)

A simple ERC-20 token used as the airdrop reward.

• Minted at deployment

• Used exclusively by the airdrop contract for distribution

• Fully replaceable with your own ERC-20 in real projects

---

2. MockAirdropProtocol (Upgradeable)

The core contract of the demo.

It is responsible for:

• Requesting and checking Humanity verification

• Enforcing one claim per verified address

• Distributing ERC-20 rewards

• Integrating with the Fee Escrow so verification costs are paid by the dApp

The contract is deployed as a UUPS upgradeable proxy so logic can be upgraded without changing addresses.

3. Humanity Protocol Contracts (External)

These contracts are not deployed by you, but must be referenced during setup:

• Verification Oracle

  Handles verification requests and callbacks

• Fee Escrow

  Holds native tokens to pay for verification fees on behalf of your dApp

You will need their addresses for the target network (testnet or mainnet).

Let's install the hardhat project first

git clone https://github.com/humanity-developers/hp-dapp-demo-contracts.git
cd hp-dapp-demo-contracts && npm install

Then let's configure the .env

# Create a .env file in the repo root
cat > .env << 'EOF'
PRIVATE_KEY=your_private_key_here
ALCHEMY_API_KEY=your_alchemy_api_key_here
VERIFICATION_ORACLE_CONTRACT=0x...
FEE_ESCROW_CONTRACT=0x...
REWARD_TOKEN_CONTRACT=0x...
AIRDROP_AMOUNT=1000000000000000000
EOF

Deployment flow (high level)

You will follow this sequence:

1. Deploy the ERC-20 reward token

2. Deploy the airdrop protocol contract

3. Fund the Fee Escrow for verification

4. Fund the airdrop contract with tokens

5. Verify everything is wired correctly

Each step is explained below.

Step 1 — Deploy the reward token

First, deploy the ERC-20 token that will be distributed to verified users.

npx hardhat run scripts/gasToken/deployDemoToken.ts --network humanityTestnet

Why this matters:

• The airdrop contract does not mint tokens

• It can only distribute tokens it already owns

• Token supply and economics are fully controlled by you

What you’ll get from this step:

• TOKEN_CONTRACT_ADDRESS

ℹ️ You can customize token name, symbol, and initial supply via environment variables if needed.

Refer to the contracts repository README for exact configuration options.

https://github.com/humanity-developers/hp-dapp-demo-contracts

Step 2 — Deploy the airdrop protocol contract

Next, deploy the MockAirdropProtocol contract.

npx hardhat run scripts/verificationOracle/dapp/deployMockAirdrop.ts --network humanityTestnet

During deployment, the contract is reading from our .env file and configured with:

• The reward token address

• The Humanity Verification Oracle address

• The Humanity Fee Escrow address

• The airdrop amount per verified user

Why this matters:

• This is where Humanity verification becomes enforceable on-chain

• The contract defines who can claim and how much

• All frontend logic ultimately calls into this contract

What you’ll get from this step:

• AIRDROP_CONTRACT_ADDRESS (proxy address)

⚠️ This address is the one your frontend must use — not the implementation address.

Step 3 — Fund the Fee Escrow (verification fees)

Before users can request verification, the dApp must pre-fund verification fees.

This is done by depositing native tokens into the Fee Escrow contract for your airdrop contract.

We can use the FeeEscrow explorer interface to do so

Where dapp (address) is the address for our deployed AIRDROP_CONTRACT_ADDRESS and Send native tHP (uint256) is the amount of tokens we want allocate for our dApp.

Why this matters:

• Verification requests cost gas and protocol fees

• Users should not need to manage or prepay these fees

• The escrow ensures a smooth UX for verification

Key concept:

• Fees are associated with the airdrop contract address

• One escrow deposit can cover many user verifications

💡 In production setups, this step is often handled by an operator wallet or backend service.

Step 4 — Fund the airdrop with reward tokens

The airdrop contract must hold enough ERC-20 tokens to pay all expected claims.

This is a simple ERC-20 transfer:

• From: token owner wallet

• To: AIRDROP_CONTRACT_ADDRESS

Why this matters:

• The contract will revert claims if it runs out of tokens

• Funding early avoids failed user transactions

Rule of Thumb

total tokens required =
  expected users × airdrop amount per user

Step 5 — Sanity checks

Before moving on to the frontend, confirm:

• ✅ Airdrop contract has a positive ERC-20 balance

• ✅ Fee Escrow shows a funded balance for your contract

• ✅ Deployed contract addresses are saved

Outputs you will need later

Save these values. You’ll use them in the frontend setup:

• TOKEN_CONTRACT_ADDRESS

• AIRDROP_CONTRACT_ADDRESS

• CHAIN_ID

• RPC_URL

Next step

➡️ Proceed to Frontend Integration, where you’ll wire these addresses into the dApp and walk through the user verification + claim flow end to end.