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

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

High-level architecture

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

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

Last updated