Front End Integration
Build React frontend that connects wallets, checks verification status, calls smart contract functions, and displays airdrop eligibility.
This guide walks through integrating a frontend application with the verification-gated airdrop contracts deployed in the previous step.
The goal is to connect a wallet-based UI to the MockAirdropProtocol contract so users can:
Connect their wallet
Request Humanity verification (when needed)
Claim tokens exactly once after verification
This guide explains the integration flow.
For full setup commands, monorepo structure, and UI details, refer to the frontend repository README.
What you will build
By completing this section, you will:
Configure the frontend to target your deployed contracts
Connect the dApp to Humanity networks
Enable the verification → claim user flow
Run the application locally or deploy it to production
Frontend responsibilities
The frontend is responsible for orchestrating user actions, not enforcing rules.
On-chain enforcement is handled entirely by the contracts.
The frontend must:
Connect user wallets
Read verification and eligibility state from the blockchain
Trigger verification and claim transactions
Provide clear UX feedback for each step
Let's begin by installing our Front End dApp project
Then let's configure our .env file
Inputs required from the on-chain setup
Before starting, make sure you have the following values from the Smart Contracts Setup step:
AIRDROP_CONTRACT_ADDRESSTOKEN_CONTRACT_ADDRESSCHAIN_IDRPC_URLVITE_WALLETCONNECT_PROJECT(get it from https://dashboard.reown.com/)
These values are injected into the frontend via environment variables.
Step 1 — Configure network and contracts
The frontend is chain-agnostic and configured entirely through environment variables.
You will set:
Target network (testnet or mainnet)
RPC endpoint
Deployed contract addresses
Why this matters:
The frontend never “discovers” contracts automatically
Explicit configuration avoids accidental interaction with the wrong network
Makes switching environments trivial
ℹ️ Only variables prefixed with VITE_ are exposed to the client.
We can now fire up our application by running
Our application should be visible at http://localhost:3000/
Step 2 — Wallet connection and network handling
The dApp uses modern Web3 tooling to handle wallet interactions:
Wallet connection (MetaMask, WalletConnect, etc.)
Network detection and switching
Transaction signing and submission
From the user’s perspective:
User opens the app
Connects a wallet
Is prompted to switch networks if needed
Why this matters:
Verification and claims only work on the correct chain
Network mismatches are the most common source of UX friction
Step 3 — Reading verification & eligibility state
Once a wallet is connected, the frontend queries the airdrop contract to determine:
Whether the user is already verified
Whether the user has already claimed
Whether verification is required
Not verified
Show “Verify” action
Verified
Show “Claim” action
Claimed
Disable actions / show success
Why this matters:
Users should never submit transactions that will revert
Clear state-driven UI reduces failed transactions
Step 4 — Triggering verification
If the user is not yet verified:
The frontend sends a transaction to the airdrop contract
The contract forwards the request to the Humanity Verification Oracle
Verification fees are paid from the Fee Escrow (not the user)
Important UX notes:
The frontend should:
Show pending state
Allow users to re-check status
Avoid duplicate requests
💡 In production systems, you may complement this with off-chain indexing or notifications.
Step 5 — Claiming the airdrop
Once verification is confirmed:
The frontend enables the Claim action
User submits a transaction to the airdrop contract
Tokens are transferred directly to the user’s wallet
On-chain guarantees:
Each address can only claim once
Claims revert if verification is missing
Claims revert if the contract is out of tokens
Local development flow
Typical local workflow:
Configure environment variables
Start the frontend dev server
Connect a testnet wallet
Walk through verify → claim flow
Inspect transactions in the block explorer
This allows you to validate:
Wallet UX
Network configuration
Contract integration
Verification logic
Deployment options
The frontend is a static web application and can be deployed to:
Vercel (recommended)
Netlify
Cloudflare Pages
Any static hosting provider
Deployment requires:
Setting the same environment variables used locally
Ensuring the target chain RPC is accessible from the browser
Common integration pitfalls
Wrong contract address
Always double-check proxy addresses, not implementation addresses.
Wrong chain ID
Wallet may connect successfully but transactions will fail.
Insufficient escrow funding
Verification requests will fail if the Fee Escrow is empty.
Airdrop contract not funded
Claims will revert if token balance is zero.
Last updated