The List - Whitelist System Documentation

Overview

A tiered whitelist system for capturing XRPL addresses with specific NFT holding requirements and Google OAuth verification. The system generates three separate CSV lists for different mint phases. There will be a specific window of time when the list is available for applications.

Core Features

  • 3-Tier System: 1st degree (best), 2nd degree, 3rd degree
  • NFT Verification: Checks holdings across approved collections using snapshot data
  • Google OAuth: Human verification for bot prevention
  • CSV Generation: Separate lists for each mint phase
  • Snapshot-Based: Uses pre-existing snapshots for verification

Technical Architecture

Frontend Components

  • Whitelist application form
  • XRPL address validation
  • Google OAuth integration
  • NFT ownership verification (snapshot-based)
  • Tier qualification display
  • Admin panel for list generation

Database Schema

-- Users table
users (
  id SERIAL PRIMARY KEY,
  xrpl_address VARCHAR(255) UNIQUE NOT NULL,
  google_email VARCHAR(255),
  google_name VARCHAR(255),
  tier_1st_degree BOOLEAN DEFAULT FALSE,
  tier_2nd_degree BOOLEAN DEFAULT FALSE,
  tier_3rd_degree BOOLEAN DEFAULT FALSE,
  created_at TIMESTAMP DEFAULT NOW(),
  updated_at TIMESTAMP DEFAULT NOW()
)

-- NFT Holdings table
nft_holdings (
  id SERIAL PRIMARY KEY,
  user_id INTEGER REFERENCES users(id),
  collection_name VARCHAR(255),
  token_id VARCHAR(255),
  verified_at TIMESTAMP DEFAULT NOW()
)

User Flow

  1. User connects XRPL wallet
  2. User authenticates with Google OAuth
  3. System verifies NFT holdings using snapshot data
  4. User is assigned appropriate tier(s)
  5. Qualification details are displayed to user
  6. User submits whitelist application
  7. Admin generates CSV lists for each mint phase

API Endpoints

  • POST /api/whitelist/verify - Verify XRPL address and NFTs using snapshots
  • GET /api/whitelist/google-auth - Google OAuth
  • POST /api/whitelist/submit - Submit whitelist application
  • GET /api/admin/generate-lists - Generate CSV files (admin only)

Security Considerations

  • Google OAuth for human verification
  • XRPL address validation
  • Rate limiting on verification requests
  • Admin-only access to list generation
  • Secure storage of Google tokens

Tier Requirements

1st Degree (Limit: 10 Mints) - BEST TIER

  • NFT Requirements: Must hold NFTs from approved collections (snapshot-based)
  • Mint Cost: Free
  • Snapshot: Taken on August 16th, 2024
  • Collections: Based on snapshot data

2nd Degree (Limit: 25 Mints)

  • NFT Requirements: Must hold any one NFT from approved collections
  • Human Verification: Must prove you are human via Google OAuth
  • Mint Cost: 3 XRP
  • Collections: Based on snapshot data

3rd Degree (Limit: 50 Mints)

  • NFT Requirements: None
  • Human Verification: Must prove you are human via Google OAuth
  • Mint Cost: 5 XRP

Public Mint

  • Limit: Unlimited
  • Cost: 10 XRP
  • Requirements: None

Collection Details

Approved Collections

The system uses snapshot data from August 16th, 2024 to verify NFT holdings. Collections include:

  • I Have Hands
  • Knights of the Strange Arm
  • Science
  • Milady Noir (2nd Degree only, not mentioned in UI)

Collection Rarity Distribution

Tier Count % of Total
Mythics 12 0.12%
Grails 50 0.50%
Rares 100 1.00%
Uncommon 970 9.70%
Commons 8,880 88.80%
Total 10,000 100%

Implementation Phases

Phase 1: Core Infrastructure ✅

  • Database setup
  • Basic user management
  • XRPL wallet integration

Phase 2: Google OAuth Integration ✅

  • OAuth implementation
  • Human verification
  • Bot prevention measures

Phase 3: Whitelist Application ✅

  • User interface for applications
  • Tier qualification logic
  • Snapshot-based verification system

Phase 4: Admin Tools ✅

  • CSV generation
  • List management
  • Analytics dashboard

Technology Stack

  • Frontend: Next.js, React, TypeScript
  • Backend: Next.js API routes
  • Authentication: Google OAuth 2.0
  • XRPL Integration: Snapshot-based verification
  • Styling: Tailwind CSS, DaisyUI
  • Deployment: Railway

Current Status

✅ COMPLETED - All phases implemented and deployed

  • Google OAuth authentication working
  • Snapshot-based NFT verification implemented
  • Tier qualification system functional
  • Admin tools for CSV generation ready
  • Mobile-responsive UI implemented
  • Image optimization with Next.js Image component

Next Steps

  1. Monitor whitelist applications
  2. Generate CSV lists for mint phases
  3. Distribute lists to users on September 11th
  4. Direct users to xrp.cafe for minting

Important Notes

  • Snapshot Date: August 16th, 2024
  • Minting Platform: xrp.cafe
  • Mint Date: September 11th, 2024
  • Verification Method: Snapshot-based (not live XRPL queries)
  • Human Verification: Google OAuth required for 2nd and 3rd Degree tiers