Verified Airdrop dApp Overview

This page gives an overview of the airdrop dApp including needed repositories, architecture, end to end flow and prerequisites.

What you will build

By the end of this walkthrough, you will have:

• On-chain

  • DemoToken deployed as the reward token

  • MockAirdropProtocol deployed (upgradeable proxy) and configured to use:

    • Humanity Verification Oracle

    • Humanity Fee Escrow

  • Fee escrow funded so the dApp can pay verification fees

  • The airdrop contract funded with reward tokens for distribution

• Frontend

  • A React-based dApp that:

    • Connects user wallets

    • Checks eligibility / verification status

    • Triggers verification flow and allows claiming

Repositories used in this demo

This separation allows the on-chain verification logic and the frontend integration to be adopted independently, depending on how a project is structured.

• Smart contracts repo (Hardhat): deploys DemoToken + MockAirdropProtocol and includes deployment scripts and basic tests

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

• Frontend repo (Bun + Vite + React): wallet connection + claim UI; configured via .env with chain + contract addresses

https://github.com/humanity-developers/verification-airdrop-dapp

High-level architecture

                           ┌─────────────────────┐
                           │     User Wallet     │
                           └──────────┬──────────┘
                                      │
                        connect + sign tx
                                      │
                                      ▼
                           ┌─────────────────────┐
                           │    Frontend dApp    │
                           └──────────┬──────────┘
                                      │
                                 read / write
                                      │
                                      ▼
                ┌──────────────────────────────────────┐
                │        MockAirdropProtocol           │
                │            (Upgradeable)             │
                └──────────┬───────────────┬──────────┘
                           │               │
                 ERC20 transfer     request / check verification
                           │               │
                           ▼               ▼
               ┌────────────────┐   ┌────────────────────────────┐
               │   DemoToken    │   │ Humanity Verification      │
               │ (ERC-20 Token) │   │         Oracle             │
               └────────────────┘   └──────────────┬─────────────┘
                                                   │
                                      callback / result
                                                   │
                                                   ▼
                                     (back to MockAirdropProtocol)


   ┌────────────────────────────┐
   │   DApp Operator / Backend  │
   └──────────────┬─────────────┘
                  │
              pre-fund fees
                  │
                  ▼
        ┌─────────────────────────┐
        │   Humanity Fee Escrow   │
        └──────────────┬──────────┘
                       │
         covers verification costs
                       │
                       ▼
             Humanity Verification Oracle

Key point: The Fee Escrow is funded by the dApp operator (or an off-chain service) so users don’t need to manage verification fee funding themselves; the on-chain verification interactions are routed through the Oracle + escrow integration

End-to-end flow

1. Operator (you) deploys contracts

   • Deploy DemoToken

   • Deploy MockAirdropProtocol configured with the Oracle + Fee Escrow addresses hp-demo-contracts-readme

2. Operator funds the system

   • Deposit native tokens into Fee Escrow for the dApp (so verification requests can be paid)

   • Transfer DemoToken into the airdrop contract so it can distribute rewards hp-demo-contracts-readme

3. User claims through the frontend

   • User connects wallet in the dApp

   • dApp checks whether the address is verified/eligible

   • User requests verification (when needed)

   • After verification is confirmed, user calls claim and receives DemoToken exactly once

What you need before starting

• A funded testnet wallet (for deployments + escrow funding)

• Current Humanity Verification Oracle and Fee Escrow contract addresses for the network you’re using (the contracts repo expects you to provide them)

• The two repos cloned locally:

  • contracts repo (Hardhat)

  • frontend repo (Bun/Vite/React)

Next steps

• Smart Contracts Setup: deploy + fund the on-chain components (token + airdrop + escrow)

• Frontend Integration: wire the deployed contract addresses into the dApp and run the full verify → claim user flow