> 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/smart-contracts-set-up.md). # Smart Contracts Set Up This guide walks through deploying and configuring the **on-chain components** required for a verification-gated airdrop using Humanity. The goal is to get you from **zero contracts** to a **fully funded, verification-enabled airdrop contract** that can be consumed by a frontend application. > This guide focuses on what to deploy and why. > > For full commands, environment variables, and scripts, always refer to the contracts repository README. > > ## What you will build By completing this section, you will: * Deploy a reward ERC-20 token * Deploy a verification-gated airdrop protocol contract * Connect the airdrop to Humanity’s Verification Oracle * Pre-fund verification fees using the Fee Escrow * Fund the airdrop with reward tokens At the end, your contracts will be **ready to serve verified users**. ## Contracts involved This setup uses the following on-chain components: ### 1. DemoToken (ERC-20) A simple ERC-20 token used as the airdrop reward. * Minted at deployment * Used exclusively by the airdrop contract for distribution * Fully replaceable with your own ERC-20 in real projects *** ### 2. MockAirdropProtocol (Upgradeable) The core contract of the demo. It is responsible for: * Requesting and checking Humanity verification * Enforcing **one claim per verified address** * Distributing ERC-20 rewards * Integrating with the Fee Escrow so verification costs are paid by the dApp The contract is deployed as a **UUPS upgradeable proxy** so logic can be upgraded without changing addresses. ### 3. Humanity Contracts (External) These contracts are **not deployed by you**, but must be referenced during setup: * **Verification Oracle** Handles verification requests and callbacks * **Fee Escrow** Holds native tokens to pay for verification fees on behalf of your dApp You will need their addresses for the target network (testnet or mainnet). Let's install the hardhat project first ```bash git clone https://github.com/humanity-developers/hp-dapp-demo-contracts.git cd hp-dapp-demo-contracts && npm install ``` Then let's configure the .env ```bash # Create a .env file in the repo root cat > .env << 'EOF' PRIVATE_KEY=your_private_key_here ALCHEMY_API_KEY=your_alchemy_api_key_here VERIFICATION_ORACLE_CONTRACT=0x... FEE_ESCROW_CONTRACT=0x... REWARD_TOKEN_CONTRACT=0x... AIRDROP_AMOUNT=1000000000000000000 EOF ``` ## Deployment flow (high level) You will follow this sequence: 1. Deploy the ERC-20 reward token 2. Deploy the airdrop protocol contract 3. Fund the Fee Escrow for verification 4. Fund the airdrop contract with tokens 5. Verify everything is wired correctly Each step is explained below. ### Step 1 — Deploy the reward token First, deploy the ERC-20 token that will be distributed to verified users. ```bash npx hardhat run scripts/gasToken/deployDemoToken.ts --network humanityTestnet ``` Why this matters: * The airdrop contract does **not mint tokens** * It can only distribute tokens it already owns * Token supply and economics are fully controlled by you What you’ll get from this step: * `TOKEN_CONTRACT_ADDRESS` > ℹ️ You can customize token name, symbol, and initial supply via environment variables if needed. > > Refer to the contracts repository README for exact configuration options. > > ### Step 2 — Deploy the airdrop protocol contract Next, deploy the `MockAirdropProtocol` contract. ```bash npx hardhat run scripts/verificationOracle/dapp/deployMockAirdrop.ts --network humanityTestnet ``` During deployment, the contract is reading from our `.env` file and configured with: * The **reward token address** * The **Humanity Verification Oracle address** * The **Humanity Fee Escrow address** * The **airdrop amount per verified user** Why this matters: * This is where Humanity verification becomes enforceable on-chain * The contract defines *who* can claim and *how much* * All frontend logic ultimately calls into this contract What you’ll get from this step: * `AIRDROP_CONTRACT_ADDRESS` (proxy address) > ⚠️ This address is the one your frontend must use — not the implementation address. ### Step 3 — Fund the Fee Escrow (verification fees) Before users can request verification, the dApp must **pre-fund verification fees**. This is done by depositing native tokens into the Fee Escrow contract **for your airdrop contract**. We can use the [FeeEscrow explorer interface](https://humanity-testnet.explorer.alchemy.com/address/0x1a247b7d7076e4c4D97D87c62947Ab5495C13423?tab=read_write_proxy) to do so
Where `dapp (address)` is the address for our deployed `AIRDROP_CONTRACT_ADDRESS` and `Send native tHP (uint256)` is the amount of tokens we want allocate for our dApp. Why this matters: * Verification requests cost gas and protocol fees * Users should not need to manage or prepay these fees * The escrow ensures a smooth UX for verification Key concept: * Fees are associated with the **airdrop contract address** * One escrow deposit can cover many user verifications > 💡 In production setups, this step is often handled by an operator wallet or backend service. ### Step 4 — Fund the airdrop with reward tokens The airdrop contract must hold enough ERC-20 tokens to pay all expected claims. This is a simple ERC-20 transfer: * **From**: token owner wallet * **To**: `AIRDROP_CONTRACT_ADDRESS` Why this matters: * The contract will revert claims if it runs out of tokens * Funding early avoids failed user transactions Rule of Thumb ``` total tokens required = expected users × airdrop amount per user ``` ### Step 5 — Sanity checks Before moving on to the frontend, confirm: * ✅ Airdrop contract has a positive ERC-20 balance * ✅ Fee Escrow shows a funded balance for your contract * ✅ Deployed contract addresses are saved #### Outputs you will need later Save these values. You’ll use them in the frontend setup: * `TOKEN_CONTRACT_ADDRESS` * `AIRDROP_CONTRACT_ADDRESS` * `CHAIN_ID` * `RPC_URL` ## Next step ➡️ **Proceed to Frontend Integration**, where you’ll wire these addresses into the dApp and walk through the user verification + claim flow end to end. --- # 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/smart-contracts-set-up.md?ask=&goal= ``` `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.