Verified Airdrop dApp Overview

Architecture overview, smart contract design, frontend integration, end-to-end verification flow, repository links, and setup 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-contractsgithub.com

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

GitHub - humanity-developers/verification-airdrop-dappGitHub

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)

  • Front end 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