🎯 FairDrop - Sybil-Resistant Airdrops on Solana

Fair token distribution powered by on-chain reputation

🌐 Live Demo · 📺 Video Demo · 🔗 FairScale

📺 Demo Video

▶️ Watch the Full Demo

The demo covers:

✅ Connecting Solana wallet (Phantom)
✅ Fetching FairScore from FairScale API
✅ Linking X/Twitter for social score boost
✅ Viewing tier benefits and score breakdown
✅ Claiming an airdrop with tier multiplier
✅ Cooldown system and claim history
✅ Score improvement tips and leaderboard

🌟 Overview

FairDrop is a sybil-resistant airdrop platform that uses FairScale reputation scores to distribute tokens fairly on Solana. Instead of equal distribution that rewards bot farms, FairDrop allocates tokens based on your on-chain reputation.

The Problem

Issue	Impact
🤖 Sybil Attacks	Bots create thousands of wallets to farm airdrops
⚖️ Unfair Distribution	Real users compete with fake accounts
🎭 No Trust Layer	No way to distinguish legitimate participants
💸 Wasted Tokens	Projects lose value to farmers, not users

The Solution

FairDrop uses FairScale's FairScore to create merit-based distribution:

✅ Gate access based on reputation tiers
✅ Multiply allocations for trusted wallets (up to 3x)
✅ Apply dynamic cooldowns based on trust level
✅ Show score improvement tips to help users grow

🏗️ Architecture Overview

┌─────────────────────────────────────────────────────────────────────────────┐
│                              FairDrop Frontend                               │
│                          Next.js 14 + React + TypeScript                     │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  ┌────────────────┐    ┌────────────────┐    ┌────────────────┐            │
│  │    Wallet      │    │   FairScale    │    │    Airdrop     │            │
│  │   Connection   │───▶│   API Client   │───▶│    Manager     │            │
│  │   (Phantom,    │    │                │    │                │            │
│  │   Solflare)    │    │  /score        │    │  Tier Gating   │            │
│  └────────────────┘    │  /fairScore    │    │  Multipliers   │            │
│         │              │  /walletScore  │    │  Cooldowns     │            │
│         │              │  /socialScore  │    └────────────────┘            │
│         │              └────────────────┘             │                     │
│         │                      │                      │                     │
│         ▼                      ▼                      ▼                     │
│  ┌────────────────┐    ┌────────────────┐    ┌────────────────┐            │
│  │    Solana      │    │   FairScore    │    │     Claim      │            │
│  │    Web3.js     │    │   Processing   │    │    History     │            │
│  │                │    │                │    │  (LocalStorage)│            │
│  │  - PublicKey   │    │  - Score 0-1000│    │                │            │
│  │  - Signing     │    │  - Tier Calc   │    │  - Records     │            │
│  │                │    │  - Badges      │    │  - Timestamps  │            │
│  └────────────────┘    └────────────────┘    └────────────────┘            │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                           External Services                                  │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  ┌────────────────┐    ┌────────────────┐    ┌────────────────┐            │
│  │   FairScale    │    │     Solana     │    │    Solscan     │            │
│  │      API       │    │     RPC        │    │    Explorer    │            │
│  │                │    │                │    │                │            │
│  │ api.fairscale  │    │   Devnet /     │    │   Transaction  │            │
│  │    .xyz        │    │   Mainnet      │    │     Links      │            │
│  └────────────────┘    └────────────────┘    └────────────────┘            │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘

Data Flow

User Connects Wallet
        │
        ▼
┌───────────────────┐
│ Fetch FairScore   │◄─── FairScale API (/score?wallet=xxx&twitter=yyy)
│ from FairScale    │
└───────────────────┘
        │
        ▼
┌───────────────────┐
│ Calculate Tier    │     Score 0-299 → Bronze (1x)
│ from Score        │     Score 300-599 → Silver (1.5x)
│                   │     Score 600-849 → Gold (2x)
└───────────────────┘     Score 850-1000 → Diamond (3x)
        │
        ▼
┌───────────────────┐
│ Display Airdrops  │     Filter by tier requirements
│ + Allocations     │     Calculate: base × multiplier
└───────────────────┘
        │
        ▼
┌───────────────────┐
│ Process Claim     │     Check cooldown (tier-based)
│                   │     Save to claim history
└───────────────────┘

🔌 FairScale API Integration

FairDrop deeply integrates FairScale at its core - not just for display, but for all business logic.

API Endpoints Used

Endpoint	Purpose	Example
`GET /score`	Full score + breakdown + badges	Main dashboard data
`GET /fairScore`	Quick score lookup	Leaderboard updates
`GET /walletScore`	On-chain activity score only	Analytics
`GET /socialScore`	Social reputation score	X/Twitter boost

Integration Code

1. Main API Client (src/lib/fairscale.ts)

const FAIRSCALE_API_BASE = "https://api.fairscale.xyz";

export async function getFairScoreFromAPI(
  walletAddress: string,
  apiKey: string,
  twitterHandle?: string
): Promise<FairScoreResponse> {
  // Build query with optional Twitter handle
  const params = new URLSearchParams({ wallet: walletAddress });
  if (twitterHandle) {
    params.append("twitter", twitterHandle);
  }

  const response = await fetch(
    `${FAIRSCALE_API_BASE}/score?${params.toString()}`,
    {
      headers: {
        "fairkey": apiKey,  // FairScale API authentication
        "Content-Type": "application/json",
      },
    }
  );

  const data: FairScaleAPIScoreResponse = await response.json();
  
  // Transform API response - scale 0-100 to 0-1000
  return {
    wallet: data.wallet,
    fairScore: Math.round(data.fairscore * 10),
    tier: mapTier(data.tier),
    badges: data.badges.map(transformBadge),
    breakdown: {
      walletScore: data.fairscore_base,
      socialScore: data.social_score,
      walletAgeDays: data.features.wallet_age_days,
      txCount: data.features.tx_count,
      activeDays: data.features.active_days,
      platformDiversity: data.features.platform_diversity,
      // ... more features
    },
  };
}

2. Tier-Based Access Control (src/components/AirdropList.tsx)

// Airdrops are gated by minimum tier requirement
const canAccessAirdrop = (airdrop: Airdrop): boolean => {
  if (!tier) return false;
  const tierOrder = ["bronze", "silver", "gold", "diamond"];
  const userTierIndex = tierOrder.indexOf(tier.name);
  const requiredTierIndex = tierOrder.indexOf(airdrop.minTier);
  return userTierIndex >= requiredTierIndex;
};

3. Allocation Multipliers (src/lib/fairscale.ts)

// Higher FairScore = larger allocation
export function calculateAllocation(baseAmount: number, fairScore: number): number {
  const tier = getTierFromScore(fairScore);
  return Math.floor(baseAmount * tier.multiplier);
}

// Tier multipliers
export const TIERS = {
  bronze:  { minScore: 0,   multiplier: 1.0 },
  silver:  { minScore: 300, multiplier: 1.5 },
  gold:    { minScore: 600, multiplier: 2.0 },
  diamond: { minScore: 850, multiplier: 3.0 },
};

4. Dynamic Cooldowns (src/lib/fairscale.ts)

// Trust reduces wait time between claims
export function getCooldownHours(tier: TierName): number {
  switch (tier) {
    case "diamond": return 0;   // No cooldown - max trust
    case "gold":    return 6;   // 6 hour cooldown
    case "silver":  return 12;  // 12 hour cooldown
    case "bronze":  return 24;  // 24 hour cooldown
  }
}

5. Social Score Integration (src/components/Dashboard.tsx)

// Users can link their X/Twitter handle to boost score
const handleTwitterSubmit = async () => {
  localStorage.setItem(TWITTER_STORAGE_KEY, twitterInput);
  setTwitterHandle(twitterInput);
  
  // Refetch score with Twitter handle included
  const result = await fetchFairScore(
    publicKey.toBase58(),
    twitterInput  // Passed to FairScale API
  );
  setScoreData(result);
};

API Features Used

FairDrop uses these FairScale API features:

Feature	API Field	How We Use It
Fair Score	`fairscore`	Main score (0-1000 scaled)
Wallet Score	`fairscore_base`	On-chain activity component
Social Score	`social_score`	X/Twitter reputation boost
Wallet Age	`features.wallet_age_days`	Display in breakdown
Transaction Count	`features.tx_count`	Activity metric
Active Days	`features.active_days`	Consistency metric
Platform Diversity	`features.platform_diversity`	DeFi exploration
Conviction Ratio	`features.conviction_ratio`	Holding behavior
Badges	`badges[]`	Achievement display
Tier	`tier`	Access gating

🎮 Features

Reputation-Based Allocation

Tier	FairScore	Multiplier	Cooldown	Benefits
🥉 Bronze	0-299	1.0x	24h	Basic access
🥈 Silver	300-599	1.5x	12h	Early access
🥇 Gold	600-849	2.0x	6h	Priority + Exclusive drops
💎 Diamond	850-1000	3.0x	None	VIP + Governance

Core Features

Feature	Description
🔐 Tier-Gated Access	Only eligible wallets can claim specific airdrops
📈 Dynamic Multipliers	Higher reputation = larger token allocations
⏱️ Smart Cooldowns	Trust level reduces wait times between claims
📊 Score Breakdown	Transparent view of how your score is calculated
🏆 Achievement Badges	Visual recognition of on-chain accomplishments
📜 Claim History	Track all your claims with transaction links
💡 Improvement Tips	Personalized suggestions to boost your score
🏅 Leaderboard	See how you rank against other users
🎚️ Eligibility Simulator	Preview what you unlock at different score levels
📤 Social Sharing	Share your score on X/Twitter

🚀 Getting Started

Prerequisites

Node.js 18+
npm or yarn
Solana wallet (Phantom recommended)
FairScale API key (Get one here)

Installation

# 1. Clone the repository
git clone https://github.com/z0neSec/FairDrop.git
cd FairDrop

# 2. Install dependencies
npm install

# 3. Set up environment variables
cp .env.example .env.local

Configuration

Edit .env.local:

# Required: FairScale API Key
NEXT_PUBLIC_FAIRSCALE_API_KEY=your_api_key_here

# Optional: Solana RPC URL (defaults to devnet)
NEXT_PUBLIC_RPC_URL=https://api.devnet.solana.com

Running the App

# Development mode (with hot reload)
npm run dev

# Production build
npm run build
npm start

Open http://localhost:3000 in your browser.

📁 Project Structure

FairDrop/
├── src/
│   ├── app/
│   │   ├── globals.css          # Global styles + Tailwind
│   │   ├── layout.tsx           # Root layout with providers
│   │   └── page.tsx             # Main page component
│   │
│   ├── components/
│   │   ├── Navbar.tsx           # Navigation + wallet button
│   │   ├── HeroSection.tsx      # Landing hero section
│   │   ├── HowItWorks.tsx       # Feature explanation
│   │   ├── Dashboard.tsx        # Main dashboard (score + airdrops)
│   │   ├── ScoreDisplay.tsx     # FairScore visualization + breakdown
│   │   ├── AirdropList.tsx      # Airdrop cards + claim logic
│   │   ├── ScoreImprovementTips.tsx  # Personalized tips
│   │   ├── ShareScore.tsx       # Social sharing
│   │   ├── Leaderboard.tsx      # Top users ranking
│   │   ├── EligibilitySimulator.tsx  # Score preview slider
│   │   ├── PlatformStats.tsx    # Platform metrics
│   │   └── Footer.tsx           # Footer links
│   │
│   ├── lib/
│   │   ├── fairscale.ts         # ⭐ FairScale API integration
│   │   └── utils.ts             # Helper functions
│   │
│   └── providers/
│       └── WalletProvider.tsx   # Solana wallet context
│
├── public/                       # Static assets
├── .env.example                  # Environment template
├── tailwind.config.ts            # Tailwind configuration
└── package.json                  # Dependencies

🛠️ Tech Stack

Category	Technology
Framework	Next.js 14 (App Router)
Language	TypeScript
Styling	Tailwind CSS
Animations	Framer Motion
Blockchain	Solana Web3.js
Wallet	Solana Wallet Adapter
Reputation	FairScale API
Deployment	Vercel

🌐 Deployment

Deploy to Vercel (Recommended)

Click the button above
Connect your GitHub account
Add environment variable: NEXT_PUBLIC_FAIRSCALE_API_KEY
Deploy!

Manual Deployment

# Build for production
npm run build

# The output is in .next/ folder
# Deploy to any Node.js hosting provider

🔮 Future Roadmap

On-chain claim transactions with SPL tokens
Project dashboard for airdrop creators
Merkle proof verification for large drops
Multi-chain support (EVM via FairScale)
DAO governance integration
Real-time score updates via WebSocket
Mobile app (React Native)

📄 License

MIT License - see LICENSE for details.

🙏 Acknowledgments

FairScale - On-chain reputation infrastructure
Solana - High-performance blockchain
FairScale Hackathon - For the opportunity

Built with 💚 for the FairScale Hackathon 2026

🌐 Live Demo · 🔗 FairScale · 🐦 Twitter

Name		Name	Last commit message	Last commit date
public		public
src		src
.env.example		.env.example
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
next.config.js		next.config.js
package-lock.json		package-lock.json
package.json		package.json
postcss.config.js		postcss.config.js
tailwind.config.ts		tailwind.config.ts
tsconfig.json		tsconfig.json
vercel.json		vercel.json

Navigation Menu

Repository files navigation

🎯 FairDrop - Sybil-Resistant Airdrops on Solana

📺 Demo Video

🌟 Overview

The Problem

The Solution

🏗️ Architecture Overview

Data Flow

🔌 FairScale API Integration

API Endpoints Used

Integration Code

API Features Used

🎮 Features

Reputation-Based Allocation

Core Features

🚀 Getting Started

Prerequisites

Installation

Configuration

Running the App

📁 Project Structure

🛠️ Tech Stack

🌐 Deployment

Deploy to Vercel (Recommended)

Manual Deployment

🔮 Future Roadmap

📄 License

🙏 Acknowledgments

About

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

🎯 FairDrop - Sybil-Resistant Airdrops on Solana

📺 Demo Video

🌟 Overview

The Problem

The Solution

🏗️ Architecture Overview

Data Flow

🔌 FairScale API Integration

API Endpoints Used

Integration Code

API Features Used

🎮 Features

Reputation-Based Allocation

Core Features

🚀 Getting Started

Prerequisites

Installation

Configuration

Running the App

📁 Project Structure

🛠️ Tech Stack

🌐 Deployment

Deploy to Vercel (Recommended)

Manual Deployment

🔮 Future Roadmap

📄 License

🙏 Acknowledgments

About

Resources

Stars

Watchers

Forks

Contributors

Languages