Hunt Town Clap - Open Source Reference

This repository contains reference code extracted from the Hunt Town Clap ecosystem - a Farcaster-based tipping and engagement platform. The code is shared for educational purposes and as a reference for developers building similar applications.

⚠️ Note: This is reference code only. Configuration files, environment variables, and database schemas are omitted. The code may not compile as-is.

📁 Repository Structure

clap-opensource/
├── apis/                    # Backend API server (Frog/Hono framework)
├── mini-app/                # Frontend Mini App (React Router + Vite)
├── contracts/               # Solidity smart contracts (Hardhat)
└── grpc-indexer/            # Farcaster Hub indexer via gRPC

---

🏗️ Architecture Overview

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│   Mini App      │────▶│   APIs Server    │────▶│   PostgreSQL    │
│  (React/Vite)   │     │  (Frog/Hono)     │     │   (Prisma)      │
└─────────────────┘     └──────────────────┘     └─────────────────┘
                               │
                               ▼
                        ┌──────────────────┐
                        │  External APIs   │
                        │ (Neynar, Alchemy)│
                        └──────────────────┘

┌─────────────────┐     ┌──────────────────┐
│  gRPC Indexer   │────▶│  Farcaster Hub   │
│                 │     │    (gRPC)        │
└─────────────────┘     └──────────────────┘

┌─────────────────┐
│   Contracts     │────▶ Base Mainnet
│  (Solidity)     │
└─────────────────┘

---

🔧 APIs (/apis)

The backend API server built with Frog (a framework for Farcaster Frames) and Hono.

Key Directories

Directory	Description
src/routes/	API endpoints and Frame handlers
src/services/	Business logic layer
src/utils/	Utility functions (Neynar, Alchemy, Discord, etc.)
src/constants/	Contract addresses, ABIs, and configuration

Main Features

• Tipping System - Webhook-based and action-based clap/tip processing
• Allowance Management - Daily allowance calculation based on NFT holdings and OpenRank score
• Leaderboard - Daily/monthly rankings for builders and tippers
• Farcaster Frames v2 - Notification webhooks and frame interactions
• Merkle Claims - Grant distribution with merkle proof verification

---

📱 Mini App (/mini-app)

The frontend application built with React Router v7 and Vite, designed to run as a Farcaster Mini App (Frame v2).

Key Directories

Directory	Description
app/routes/	Page components (home, profile, ranking, etc.)
app/components/	Reusable UI components including swipe cards
app/hooks/	Custom React hooks for data fetching
app/stores/	Zustand state management
app/providers/	React context providers (Wagmi, RainbowKit)

Main Features

• Swipe-to-Clap Interface - Tinder-like card swiping for content discovery
• Farcaster Quick Auth - JWT-based authentication via Farcaster
• Wallet Integration - RainbowKit + Wagmi for on-chain interactions
• Clap History & Stats - Personal analytics and rewards tracking

Environment Variables Required

VITE_API_URL=             # Backend API URL
VITE_BUGSNAG_API_KEY=     # Client-side error tracking

---

📜 Contracts (/contracts)

Solidity smart contracts for grant distribution, built with Hardhat.

Contracts

Contract	Description
BuilderGrant.sol	V1 grant distribution for top builders with donation options
BuilderGrantV2.sol	Simplified V2 grant distribution for up to 90 builders
TipperGrant.sol	Merkle-based grant claims for tippers

Deployed Addresses (Base Mainnet)

• TipperGrant: 0x2eF7f539271E3457DBbBDDe78E14DF434D887a69
• BuilderGrantV2: 0x9B63FE4AE7522d89B67f216070F420F19d4f5D34

Running Tests

cd contracts
npm install
npx hardhat test

---

🔍 gRPC Indexer (/grpc-indexer)

Real-time Farcaster Hub indexer using gRPC streams to monitor casts and reactions. Built on top of Snapchain - the decentralized peer-to-peer network that powers Farcaster.

📚 Documentation: Snapchain gRPC API Reference

Features

• Monitors cast additions and deletions
• Tracks reactions (likes, recasts) for engagement scoring
• Curates content based on author reputation and content quality
• Filters spam and low-quality content

Curation Criteria

• Author must have 50+ followers (200+ if not Pro subscribed)
• Cast must be at least 40 characters
• Excludes blacklisted authors and text patterns
• Content must be less than 7 days old

---

🔗 External Services Used

Service	Purpose
Neynar	Farcaster API & webhooks
Alchemy	Blockchain data & NFT queries
Airstack	Farcaster hub access
OpenRank	User reputation scoring
DefiLlama	Token price data
Decent	Cross-chain transaction building
Snapchain	Farcaster Hub gRPC streaming

---

📄 License

This code is provided as-is for reference purposes. Please check with the Hunt Town team for licensing details before using in production.