> For the complete documentation index, see [llms.txt](https://docs.humanity.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.humanity.org/developer-guides-and-tutorials/on-chain-guides/verified-airdrop-dapp-reference-implementation/verified-airdrop-dapp-overview.md).

# Verified Airdrop dApp Overview

## 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

{% embed url="<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

{% embed url="<https://github.com/humanity-developers/verification-airdrop-dapp>" %}

## High-level architecture

```mermaid
                           ┌─────────────────────┐
                           │     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)](https://github.com/humanity-developers/hp-dapp-demo-contracts)
  * [Front end repo (Bun/Vite/React)](https://github.com/humanity-developers/verification-airdrop-dapp)

## 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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.humanity.org/developer-guides-and-tutorials/on-chain-guides/verified-airdrop-dapp-reference-implementation/verified-airdrop-dapp-overview.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.