🏁 Token Race - Crypto Betting Platform

A modern, decentralized crypto betting platform where users can bet on vetted tokens using USDC and compete in races based on price performance.

🚀 Features

Core Functionality

Dynamic Race Duration: Flexible race durations from minutes to months
Real-time Price Tracking: Live price updates during races
Leaderboard System: Track performance and rankings
Web3-First Design: Wallet connection is all you need to start
Optional Email Auth: Enhanced features with Supabase account
Database Integration: Supabase PostgreSQL for bet history tracking
Responsive Design: Optimized for desktop and mobile

Technical Features

Modern React Stack: Built with React 18, Vite, and TypeScript
Web3 Integration: RainbowKit + wagmi for wallet connectivity
Database: Supabase PostgreSQL with Row-Level Security
Dual Authentication: Web3 wallet (required) + Email auth (optional)
Beautiful UI: Tailwind CSS with custom cyberpunk theme
Animations: Framer Motion for smooth interactions
Real-time Updates: React Query for data management
Environment Configuration: Secure dotenv-based configuration

Supported Networks

Ethereum Mainnet
Polygon
Sepolia Testnet

🛠️ Tech Stack

Frontend Framework: React 18.2.0
Build Tool: Vite 5.0.8
Database: Supabase (PostgreSQL)
Authentication: Web3 wallets (primary) + Supabase Auth (optional)
Styling: Tailwind CSS 3.4.0
Web3: RainbowKit 2.0.2 + wagmi 2.5.7
Animations: Framer Motion 10.16.16
Icons: Lucide React 0.294.0
Charts: Recharts 2.8.0
Notifications: React Hot Toast 2.4.1
Date Handling: date-fns 3.0.6

📦 Installation

Prerequisites

Node.js 18+
npm or yarn
MetaMask or any Web3 wallet
Supabase account (optional, for bet history tracking)

Setup Instructions

Clone the repository

git clone <repository-url>
cd token-race-frontend

Install dependencies
```
npm install
```
Set up Supabase (Optional)

a. Create a new Supabase project at supabase.com

b. Get your project URL and anon key from the project settings

c. Run the database migrations:
```
# Copy the SQL from supabase/migrations/ files and run them in your Supabase SQL editor
# Or use the Supabase CLI if you have it installed
```

Configure environment variables Copy the example environment file and configure your settings:

cp .env.example .env

Edit .env and add your configuration:

# Required: WalletConnect Project ID
VITE_WALLET_CONNECT_PROJECT_ID=your_new_wallet_connect_project_id_here

# Optional: Supabase Configuration (for bet history tracking)
VITE_SUPABASE_URL=https://your-project-ref.supabase.co
VITE_SUPABASE_ANON_KEY=your-anon-key-here

# Optional: Custom RPC URLs (uses public RPCs if not provided)
VITE_RPC_URL_MAINNET=your_mainnet_rpc_url_here
VITE_RPC_URL_POLYGON=your_polygon_rpc_url_here
VITE_RPC_URL_SEPOLIA=your_sepolia_rpc_url_here

# Smart Contract Addresses
VITE_RACE_CONTRACT_ADDRESS=0x1234567890123456789012345678901234567890
VITE_USDC_CONTRACT_ADDRESS=0xA0b86a33E6441c8C06DD2b7c94b7E0e8c0c8c8c8

Get your WalletConnect Project ID
- Visit WalletConnect Cloud
- Sign up or log in to your account
- Click "Create New Project"
- Enter your project details and copy your Project ID
- Add it to your .env file
Start the development server
```
npm run dev
```
Open your browser Navigate to http://localhost:5173 (or the port shown in terminal)

🎯 How It Works

Web3-First Approach

TOKEN RACE is designed with a Web3-first philosophy:

Connect Wallet: Users simply connect their MetaMask or other Web3 wallet
Start Betting: Immediately access all core features without any signup
Optional Enhancement: Create an email account for bet history tracking and notifications

Authentication Levels

Level 1: Wallet Connection (Required)

✅ Place bets on tokens
✅ View current race status
✅ Access all core betting features
✅ View real-time leaderboards
❌ Bet history tracking across sessions
❌ Email notifications

Level 2: Email Account (Optional)

✅ All Level 1 features
✅ Persistent bet history tracking
✅ Email notifications for race events
✅ Enhanced profile management
✅ Cross-device access to betting history

🗄️ Database Schema

The application uses Supabase PostgreSQL with the following tables:

Users Table

users (
  id uuid PRIMARY KEY REFERENCES auth.users(id),
  wallet_address text UNIQUE,
  email text,
  created_at timestamptz DEFAULT now(),
  updated_at timestamptz DEFAULT now()
)

Bets Table

bets (
  id serial PRIMARY KEY,
  user_id uuid REFERENCES users(id),
  race_id text NOT NULL,
  token_address text NOT NULL,
  amount bigint NOT NULL,
  timestamp timestamptz DEFAULT now(),
  transaction_hash text,
  status text DEFAULT 'pending'
)

Security Features

Row-Level Security (RLS) enabled on all tables
Users can only access their own data
Authenticated users can view aggregate statistics
Secure helper functions for common queries

🔐 Authentication Architecture

Primary Authentication: Web3 Wallets

Required for all core features
Supports MetaMask, WalletConnect, Coinbase Wallet, etc.
Instant access without any signup process
Secure wallet-based identity

Secondary Authentication: Email (Optional)

Enhances the experience with additional features
Supabase-powered email/password authentication
Enables bet history tracking and notifications
Can be added at any time after wallet connection

Route Protection

Protected routes require wallet connection
Enhanced features require email authentication
Graceful fallbacks for wallet-only users
Clear indicators of what features require email signup

🏗️ Project Structure

src/
├── components/          # Reusable UI components
│   ├── Layout.jsx      # Main layout with dual auth support
│   ├── ProtectedRoute.jsx # Wallet-based route protection
│   └── providers/      # Context providers
├── contexts/           # React contexts
│   └── AuthContext.jsx # Supabase authentication context
├── hooks/              # Custom React hooks
│   ├── useSupabaseSync.js # Sync user data between auth systems
│   └── ...            # Other hooks
├── lib/                # Utilities and configurations
│   ├── supabase-helpers.js # Database helper functions
│   └── ...            # Other utilities
├── pages/              # Page components
│   ├── LoginPage.jsx   # Optional email login
│   ├── SignupPage.jsx  # Optional email signup
│   └── ...            # Other pages
├── supabase/           # Database migrations
│   └── migrations/     # SQL migration files
└── ...

🔧 Configuration

Environment Variables

Required Variables

VITE_WALLET_CONNECT_PROJECT_ID: Your WalletConnect Project ID

Optional Variables (Enhanced Features)

VITE_SUPABASE_URL: Your Supabase project URL
VITE_SUPABASE_ANON_KEY: Your Supabase anonymous key
VITE_RPC_URL_*: Custom RPC URLs for different networks
VITE_*_CONTRACT_ADDRESS: Smart contract addresses
VITE_ENABLE_*: Feature flags

Database Configuration (Optional)

Create Supabase Project: Sign up at supabase.com
Run Migrations: Execute the SQL files in supabase/migrations/ in order:
- create_users_table.sql
- create_bets_table.sql
- create_helper_functions.sql
Configure RLS: Row-Level Security is automatically enabled by the migrations
Test Database: Use the Supabase dashboard to verify tables and policies

🎨 Design Philosophy

Web3-Native UX

Wallet-first design: Primary authentication method prominently featured
Progressive enhancement: Email features clearly marked as optional
Instant access: No barriers to entry for Web3 users
Clear value proposition: Users understand what they get with each auth level

Responsive & Accessible

Mobile-first design: Optimized for mobile Web3 browsers
Touch-friendly: Large touch targets and gesture support
Loading states: Smooth transitions during wallet connections
Error handling: Clear error messages and recovery options

🚀 Available Scripts

npm run dev - Start development server
npm run build - Build for production
npm run preview - Preview production build
npm run lint - Run ESLint

🌐 Deployment

Build for Production

npm run build

Environment Setup

Ensure all environment variables are configured in your deployment platform:

WalletConnect Project ID (required)
Supabase URL and keys (optional)
Contract addresses
Feature flags

Database Setup (Optional)

Create production Supabase project
Run all migration files in order
Configure environment variables
Test authentication and database access

🔒 Security

Wallet-based security: Primary authentication through Web3 wallets
Row-Level Security: Database-level access control
Environment variables: Sensitive data protection
Input validation: Client and server-side validation
Secure Web3 interactions: Best practices implementation
Optional email auth: Additional security layer for enhanced features

🤝 Contributing

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

Documentation: Check the FAQ page in the app
Issues: Create an issue on GitHub
Discord: Join our community server
Email: support@tokenrace.com

🗺️ Roadmap

Built with ❤️ by the Token Race Team

Connect your wallet and start racing! 🏁

Name		Name	Last commit message	Last commit date
screenshots		screenshots
scripts		scripts
src		src
supabase/migrations		supabase/migrations
.env.example		.env.example
.gitignore		.gitignore
DEV.md		DEV.md
README.md		README.md
RECORDING.md		RECORDING.md
STORY.md		STORY.md
index.html		index.html
package-lock.json		package-lock.json
package.json		package.json
postcss.config.js		postcss.config.js
tailwind.config.js		tailwind.config.js
vite.config.js		vite.config.js

Latest commit

History

Folders and files

Repository files navigation