This repository contains a token airdrop flow protected by a Sparse Merkle Tree + Circom proofs. The steps below are a compact, practical guide to prepare proofs, build/deploy contracts, and run the web app locally.

For a complete visual walkthrough of the application, see the Visual Documentation which includes screenshots of:

• Authentication flow with Sign-In with Ethereum (SIWE)
• Zero-knowledge proof generation
• Token claiming interface
• Transaction status and confirmations
• User dashboard and token balance

• Foundry (forge/anvil) installed and in PATH
• Node.js >= 16 or Bun (the repo includes a bun.lock in webapp/ and circuits/circom/)
• circom & snarkjs (for circuit compile / proving) or follow the JS-based scripts in circuits/circom/
• powersOfTau28_hez_final_15.ptau is present in circuits/circom/

If you rely on the provided Foundry scripts for Merkle/proof generation, Foundry must be built with --ffi enabled for external calls.

1. Populate airdrop recipients:

   • Edit data/addresses.csv with address,amount rows.

2. Create environment file:

   • Create a .env file in the root of the project.
   • Add a SECRET to the .env file. This is used for generating nullifiers.

     SECRET=your_super_secret_phrase
     

3. Generate Merkle tree and circuit inputs:

   • The repository includes a script to build the Merkle data from data/addresses.csv. Run it from the root directory:

   cd circuits/circom
   bun install
   bun merkle_tree_generator.js
   cd ../..

   • This script generates two important files in the out/ directory:
     • out/smt_results_fixed.json: Contains the Merkle root, proofs, and leaf data.
     • out/inputs_circom_fixed.json: An array of inputs for the Circom circuit, one for each address in the CSV.

4. (Optional) Compile circuit and produce proofs with circom + snarkjs

   • Follow the instructions in circuits/circom/README.md to compile the circuit and generate proofs. The input files are already generated by the previous step.
   • The SMT tree level can be changed in the circom file and the generator script.

1. Build contracts with Foundry:

   forge build

2. Deploy locally using Anvil:

   • Start a local Anvil chain. Anvil provides a list of pre-funded accounts with private keys.

   anvil

   • Use one of the private keys provided by Anvil to deploy the contracts. The first default private key is usually 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80.

   forge script script/Deployer.s.sol:Deployer --rpc-url http://127.0.0.1:8545 --private-key <ANVIL_PRIVATE_KEY> --broadcast -vvvv

   • (Optional) Fund another wallet: To test the airdrop claim from a different wallet (e.g., your MetaMask), you can send it some Ether from an Anvil account using cast send.

   cast send <YOUR_OTHER_WALLET_ADDRESS> --value 1ether --private-key <ANVIL_PRIVATE_KEY> --rpc-url http://127.0.0.1:8545

3. Deploy to a live network:

   • Replace the RPC URL and provide your own private key to deploy to a testnet or mainnet.

   forge script script/Deployer.s.sol:Deployer --rpc-url <RPC_URL> --private-key <PRIVATE_KEY> --broadcast -vvvv

1. Enter the webapp folder and install:

   cd webapp
   bun install   # or `npm ci` / `pnpm install` if you prefer

2. Start dev server:

   bun dev       # or `npm run dev`

3. Configure the UI

   • Point the app to the deployed contract addresses / network in the app config (check webapp/src/lib or the environment variables the app expects).

The application generates privacy-preserving zero-knowledge proofs to verify token eligibility without revealing sensitive information.

Users can claim their airdrop tokens using the generated calldata with full transaction transparency.

Track token balances and claim status through an intuitive dashboard interface.

Comprehensive error handling prevents double-spending and provides clear user feedback.

├── circuits/           # Zero-knowledge circuit definitions
├── src/               # Smart contracts (Solidity)
├── script/            # Deployment scripts
├── webapp/            # Next.js frontend application
├── data/              # CSV data for airdrop recipients
├── resources/         # Screenshots and documentation
└── test/              # Contract tests

• Visual Documentation - Complete screenshot walkthrough
• Circuit Documentation - ZK circuit details
• Smart Contract Documentation - Solidity contracts