dubs-server 1.0.0

package/scripts/migrations/001_analytics_tables.sql

@@ -0,0 +1,422 @@
+-- ============================================
+-- ANALYTICS TABLES MIGRATION
+-- ============================================
+-- Run this migration to set up the unified analytics system
+-- This expands the basic audit_logs table into a full event-driven analytics system
+
+-- ============================================
+-- 1. CORE EVENTS TABLE
+-- ============================================
+-- This is the heart of the analytics system - every trackable action is an event
+
+CREATE TABLE IF NOT EXISTS events (
+    -- Primary key
+    id BIGSERIAL PRIMARY KEY,
+    
+    -- Event identification
+    event_id UUID NOT NULL DEFAULT gen_random_uuid(),
+    event_name VARCHAR(100) NOT NULL,
+    event_category VARCHAR(50) NOT NULL,
+    
+    -- User context (nullable for anonymous events)
+    user_id VARCHAR(255),              -- wallet_address or user identifier
+    session_id VARCHAR(100),           -- Browser session ID
+    device_id VARCHAR(100),            -- Device fingerprint (optional)
+    
+    -- Event data
+    properties JSONB DEFAULT '{}',     -- Event-specific data
+    context JSONB DEFAULT '{}',        -- Environmental context (device, page, etc.)
+    
+    -- Timing
+    client_timestamp TIMESTAMPTZ,      -- When event occurred on client
+    server_timestamp TIMESTAMPTZ DEFAULT NOW(),
+    
+    -- Source tracking
+    source VARCHAR(50) DEFAULT 'web',  -- web, mobile, telegram, api, server
+    version VARCHAR(20),               -- App version
+    
+    -- Indexing helpers (denormalized for performance)
+    date_partition DATE GENERATED ALWAYS AS (DATE(server_timestamp)) STORED,
+    hour_partition INTEGER GENERATED ALWAYS AS (EXTRACT(HOUR FROM server_timestamp)::INTEGER) STORED,
+    
+    -- For funnel analysis
+    funnel_step VARCHAR(100),
+    funnel_id VARCHAR(100)
+);
+
+-- Add comment
+COMMENT ON TABLE events IS 'Unified event stream for analytics, logging, and auditing';
+
+-- Performance indexes
+CREATE INDEX IF NOT EXISTS idx_events_user_time ON events(user_id, server_timestamp DESC);
+CREATE INDEX IF NOT EXISTS idx_events_category_time ON events(event_category, server_timestamp DESC);
+CREATE INDEX IF NOT EXISTS idx_events_name_time ON events(event_name, server_timestamp DESC);
+CREATE INDEX IF NOT EXISTS idx_events_session ON events(session_id, server_timestamp);
+CREATE INDEX IF NOT EXISTS idx_events_date_partition ON events(date_partition);
+CREATE INDEX IF NOT EXISTS idx_events_funnel ON events(funnel_id, funnel_step) WHERE funnel_id IS NOT NULL;
+CREATE INDEX IF NOT EXISTS idx_events_properties ON events USING gin(properties);
+CREATE INDEX IF NOT EXISTS idx_events_context ON events USING gin(context);
+CREATE INDEX IF NOT EXISTS idx_events_source ON events(source, server_timestamp DESC);
+
+-- ============================================
+-- 2. SESSION SUMMARIES TABLE
+-- ============================================
+-- Aggregated session data for faster querying
+
+CREATE TABLE IF NOT EXISTS session_summaries (
+    id SERIAL PRIMARY KEY,
+    session_id VARCHAR(100) UNIQUE NOT NULL,
+    user_id VARCHAR(255),
+    
+    -- Session timing
+    started_at TIMESTAMPTZ NOT NULL,
+    ended_at TIMESTAMPTZ,
+    last_activity_at TIMESTAMPTZ,
+    duration_seconds INTEGER,
+    
+    -- Session metrics
+    event_count INTEGER DEFAULT 0,
+    page_views INTEGER DEFAULT 0,
+    games_viewed INTEGER DEFAULT 0,
+    games_created INTEGER DEFAULT 0,
+    games_joined INTEGER DEFAULT 0,
+    messages_sent INTEGER DEFAULT 0,
+    
+    -- Conversion tracking
+    converted BOOLEAN DEFAULT FALSE,
+    conversion_type VARCHAR(50),
+    conversion_value NUMERIC(20, 9),
+    
+    -- Device/context
+    device_type VARCHAR(50),           -- mobile, tablet, desktop
+    platform VARCHAR(50),              -- web, telegram, ios, android
+    browser VARCHAR(100),
+    os VARCHAR(100),
+    screen_resolution VARCHAR(20),
+    
+    -- Traffic source
+    referrer VARCHAR(500),
+    landing_page VARCHAR(500),
+    utm_source VARCHAR(100),
+    utm_medium VARCHAR(100),
+    utm_campaign VARCHAR(100),
+    utm_term VARCHAR(100),
+    utm_content VARCHAR(100),
+    
+    -- Geographic (optional - from IP lookup)
+    country_code VARCHAR(5),
+    region VARCHAR(100),
+    city VARCHAR(100),
+    
+    created_at TIMESTAMPTZ DEFAULT NOW(),
+    updated_at TIMESTAMPTZ DEFAULT NOW()
+);
+
+COMMENT ON TABLE session_summaries IS 'Aggregated session data for analytics dashboards';
+
+CREATE INDEX IF NOT EXISTS idx_session_user ON session_summaries(user_id);
+CREATE INDEX IF NOT EXISTS idx_session_time ON session_summaries(started_at DESC);
+CREATE INDEX IF NOT EXISTS idx_session_converted ON session_summaries(converted, conversion_type);
+CREATE INDEX IF NOT EXISTS idx_session_platform ON session_summaries(platform, started_at DESC);
+
+-- ============================================
+-- 3. DAILY METRICS TABLE
+-- ============================================
+-- Pre-aggregated daily metrics for fast dashboard queries
+
+CREATE TABLE IF NOT EXISTS daily_metrics (
+    id SERIAL PRIMARY KEY,
+    metric_date DATE NOT NULL,
+    metric_name VARCHAR(100) NOT NULL,
+    
+    -- Dimensions (nullable - allows various groupings)
+    dimension_1 VARCHAR(100),          -- e.g., sport type, platform, country
+    dimension_2 VARCHAR(100),          -- e.g., device type, game mode
+    dimension_3 VARCHAR(100),          -- e.g., utm_source
+    
+    -- Metrics
+    count BIGINT DEFAULT 0,
+    sum_value NUMERIC(20, 9) DEFAULT 0,
+    avg_value NUMERIC(20, 9),
+    min_value NUMERIC(20, 9),
+    max_value NUMERIC(20, 9),
+    unique_users INTEGER DEFAULT 0,
+    unique_sessions INTEGER DEFAULT 0,
+    
+    -- Metadata
+    created_at TIMESTAMPTZ DEFAULT NOW(),
+    updated_at TIMESTAMPTZ DEFAULT NOW(),
+    
+    UNIQUE(metric_date, metric_name, dimension_1, dimension_2, dimension_3)
+);
+
+COMMENT ON TABLE daily_metrics IS 'Pre-aggregated metrics for dashboard performance';
+
+CREATE INDEX IF NOT EXISTS idx_daily_metrics_date ON daily_metrics(metric_date DESC);
+CREATE INDEX IF NOT EXISTS idx_daily_metrics_name ON daily_metrics(metric_name, metric_date DESC);
+CREATE INDEX IF NOT EXISTS idx_daily_metrics_dimensions ON daily_metrics(metric_name, dimension_1, dimension_2);
+
+-- ============================================
+-- 4. FUNNEL DEFINITIONS TABLE
+-- ============================================
+-- Store funnel configurations for analysis
+
+CREATE TABLE IF NOT EXISTS funnel_definitions (
+    id SERIAL PRIMARY KEY,
+    funnel_id VARCHAR(100) UNIQUE NOT NULL,
+    funnel_name VARCHAR(200) NOT NULL,
+    description TEXT,
+    
+    -- Steps as ordered JSON array
+    -- [{"step": 1, "event_name": "wallet_connected", "label": "Connected Wallet"}, ...]
+    steps JSONB NOT NULL,
+    
+    -- Configuration
+    window_hours INTEGER DEFAULT 24,   -- Max time between first and last step
+    require_order BOOLEAN DEFAULT TRUE, -- Must steps happen in order?
+    is_active BOOLEAN DEFAULT TRUE,
+    
+    -- Ownership
+    created_by VARCHAR(255),
+    
+    created_at TIMESTAMPTZ DEFAULT NOW(),
+    updated_at TIMESTAMPTZ DEFAULT NOW()
+);
+
+COMMENT ON TABLE funnel_definitions IS 'Funnel configurations for conversion analysis';
+
+-- ============================================
+-- 5. USER ANALYTICS PROFILES
+-- ============================================
+-- Aggregated user-level analytics (updated periodically)
+
+CREATE TABLE IF NOT EXISTS user_analytics (
+    id SERIAL PRIMARY KEY,
+    user_id VARCHAR(255) UNIQUE NOT NULL,
+    
+    -- Lifetime metrics
+    first_seen_at TIMESTAMPTZ,
+    last_seen_at TIMESTAMPTZ,
+    total_sessions INTEGER DEFAULT 0,
+    total_events INTEGER DEFAULT 0,
+    
+    -- Engagement
+    total_page_views INTEGER DEFAULT 0,
+    total_games_created INTEGER DEFAULT 0,
+    total_games_joined INTEGER DEFAULT 0,
+    total_games_won INTEGER DEFAULT 0,
+    total_messages_sent INTEGER DEFAULT 0,
+    
+    -- Financial
+    total_wagered_sol NUMERIC(20, 9) DEFAULT 0,
+    total_won_sol NUMERIC(20, 9) DEFAULT 0,
+    total_claimed_sol NUMERIC(20, 9) DEFAULT 0,
+    
+    -- Referral metrics
+    referral_code VARCHAR(50),
+    referred_by VARCHAR(255),
+    total_referrals INTEGER DEFAULT 0,
+    
+    -- Segmentation
+    is_paying_user BOOLEAN DEFAULT FALSE,
+    first_wager_at TIMESTAMPTZ,
+    user_tier VARCHAR(50) DEFAULT 'new',  -- new, active, power, whale
+    
+    -- Churn prediction
+    days_since_last_activity INTEGER,
+    churn_risk VARCHAR(20),               -- low, medium, high
+    
+    created_at TIMESTAMPTZ DEFAULT NOW(),
+    updated_at TIMESTAMPTZ DEFAULT NOW()
+);
+
+COMMENT ON TABLE user_analytics IS 'Aggregated user-level analytics for segmentation and analysis';
+
+CREATE INDEX IF NOT EXISTS idx_user_analytics_tier ON user_analytics(user_tier);
+CREATE INDEX IF NOT EXISTS idx_user_analytics_churn ON user_analytics(churn_risk);
+CREATE INDEX IF NOT EXISTS idx_user_analytics_last_seen ON user_analytics(last_seen_at DESC);
+
+-- ============================================
+-- 6. INSERT DEFAULT FUNNELS
+-- ============================================
+
+INSERT INTO funnel_definitions (funnel_id, funnel_name, description, steps, window_hours)
+VALUES 
+(
+    'registration',
+    'User Registration',
+    'Track users from wallet connection to completed registration',
+    '[
+        {"step": 1, "event_name": "wallet_connected", "label": "Connected Wallet"},
+        {"step": 2, "event_name": "registration_started", "label": "Started Registration"},
+        {"step": 3, "event_name": "avatar_selected", "label": "Selected Avatar"},
+        {"step": 4, "event_name": "registration_completed", "label": "Completed Registration"}
+    ]'::jsonb,
+    24
+),
+(
+    'first_bet',
+    'First Bet',
+    'Track users from viewing games to placing their first bet',
+    '[
+        {"step": 1, "event_name": "game_viewed", "label": "Viewed Game"},
+        {"step": 2, "event_name": "game_create_started", "label": "Started Creating Game"},
+        {"step": 3, "event_name": "team_selected", "label": "Selected Team"},
+        {"step": 4, "event_name": "wager_amount_set", "label": "Set Wager Amount"},
+        {"step": 5, "event_name": "transaction_signed", "label": "Signed Transaction"},
+        {"step": 6, "event_name": "game_created", "label": "Game Created"}
+    ]'::jsonb,
+    2
+),
+(
+    'sports_betting',
+    'Sports Betting Flow',
+    'Track the sports betting user journey',
+    '[
+        {"step": 1, "event_name": "page_viewed", "label": "Viewed Sports Tab", "filter": {"pageName": "sports"}},
+        {"step": 2, "event_name": "game_card_clicked", "label": "Clicked Game Card"},
+        {"step": 3, "event_name": "bet_modal_opened", "label": "Opened Bet Modal"},
+        {"step": 4, "event_name": "team_selected", "label": "Selected Team"},
+        {"step": 5, "event_name": "bet_confirmed", "label": "Confirmed Bet"}
+    ]'::jsonb,
+    1
+),
+(
+    'social_engagement',
+    'Social Engagement',
+    'Track users engaging with social features',
+    '[
+        {"step": 1, "event_name": "chat_opened", "label": "Opened Chat"},
+        {"step": 2, "event_name": "chat_message_sent", "label": "Sent Message"},
+        {"step": 3, "event_name": "friend_request_sent", "label": "Sent Friend Request"},
+        {"step": 4, "event_name": "friend_request_accepted", "label": "Friend Request Accepted"}
+    ]'::jsonb,
+    168
+),
+(
+    'referral',
+    'Referral Flow',
+    'Track referral program engagement',
+    '[
+        {"step": 1, "event_name": "referral_code_generated", "label": "Generated Code"},
+        {"step": 2, "event_name": "referral_link_copied", "label": "Copied Link"},
+        {"step": 3, "event_name": "referral_code_used", "label": "Code Used by Friend"},
+        {"step": 4, "event_name": "referral_badge_earned", "label": "Badge Earned"}
+    ]'::jsonb,
+    720
+)
+ON CONFLICT (funnel_id) DO NOTHING;
+
+-- ============================================
+-- 7. HELPER FUNCTIONS
+-- ============================================
+
+-- Function to update session summary on new event
+CREATE OR REPLACE FUNCTION update_session_on_event()
+RETURNS TRIGGER AS $$
+BEGIN
+    INSERT INTO session_summaries (session_id, user_id, started_at, last_activity_at, event_count)
+    VALUES (NEW.session_id, NEW.user_id, NEW.server_timestamp, NEW.server_timestamp, 1)
+    ON CONFLICT (session_id) DO UPDATE SET
+        user_id = COALESCE(session_summaries.user_id, EXCLUDED.user_id),
+        last_activity_at = EXCLUDED.last_activity_at,
+        event_count = session_summaries.event_count + 1,
+        page_views = session_summaries.page_views + CASE WHEN NEW.event_name = 'page_viewed' THEN 1 ELSE 0 END,
+        games_viewed = session_summaries.games_viewed + CASE WHEN NEW.event_name = 'game_viewed' THEN 1 ELSE 0 END,
+        games_created = session_summaries.games_created + CASE WHEN NEW.event_name = 'game_created' THEN 1 ELSE 0 END,
+        games_joined = session_summaries.games_joined + CASE WHEN NEW.event_name = 'game_joined' THEN 1 ELSE 0 END,
+        messages_sent = session_summaries.messages_sent + CASE WHEN NEW.event_name = 'chat_message_sent' THEN 1 ELSE 0 END,
+        updated_at = NOW();
+    
+    RETURN NEW;
+END;
+$$ LANGUAGE plpgsql;
+
+-- Create trigger (only if session_id is provided)
+DROP TRIGGER IF EXISTS trigger_update_session ON events;
+CREATE TRIGGER trigger_update_session
+    AFTER INSERT ON events
+    FOR EACH ROW
+    WHEN (NEW.session_id IS NOT NULL)
+    EXECUTE FUNCTION update_session_on_event();
+
+-- Function to update user analytics on event
+CREATE OR REPLACE FUNCTION update_user_analytics_on_event()
+RETURNS TRIGGER AS $$
+BEGIN
+    INSERT INTO user_analytics (user_id, first_seen_at, last_seen_at, total_events)
+    VALUES (NEW.user_id, NEW.server_timestamp, NEW.server_timestamp, 1)
+    ON CONFLICT (user_id) DO UPDATE SET
+        last_seen_at = EXCLUDED.last_seen_at,
+        total_events = user_analytics.total_events + 1,
+        total_page_views = user_analytics.total_page_views + CASE WHEN NEW.event_name = 'page_viewed' THEN 1 ELSE 0 END,
+        total_games_created = user_analytics.total_games_created + CASE WHEN NEW.event_name = 'game_created' THEN 1 ELSE 0 END,
+        total_games_joined = user_analytics.total_games_joined + CASE WHEN NEW.event_name = 'game_joined' THEN 1 ELSE 0 END,
+        total_messages_sent = user_analytics.total_messages_sent + CASE WHEN NEW.event_name = 'chat_message_sent' THEN 1 ELSE 0 END,
+        days_since_last_activity = 0,
+        updated_at = NOW();
+    
+    RETURN NEW;
+END;
+$$ LANGUAGE plpgsql;
+
+-- Create trigger (only if user_id is provided)
+DROP TRIGGER IF EXISTS trigger_update_user_analytics ON events;
+CREATE TRIGGER trigger_update_user_analytics
+    AFTER INSERT ON events
+    FOR EACH ROW
+    WHEN (NEW.user_id IS NOT NULL)
+    EXECUTE FUNCTION update_user_analytics_on_event();
+
+-- ============================================
+-- 8. VIEWS FOR COMMON QUERIES
+-- ============================================
+
+-- Daily Active Users view
+CREATE OR REPLACE VIEW v_daily_active_users AS
+SELECT 
+    date_partition as date,
+    COUNT(DISTINCT user_id) as dau,
+    COUNT(DISTINCT session_id) as sessions,
+    COUNT(*) as total_events
+FROM events
+WHERE user_id IS NOT NULL
+GROUP BY date_partition
+ORDER BY date_partition DESC;
+
+-- Events summary by category
+CREATE OR REPLACE VIEW v_events_by_category AS
+SELECT 
+    date_partition as date,
+    event_category,
+    event_name,
+    COUNT(*) as event_count,
+    COUNT(DISTINCT user_id) as unique_users
+FROM events
+GROUP BY date_partition, event_category, event_name
+ORDER BY date_partition DESC, event_count DESC;
+
+-- Session conversion summary
+CREATE OR REPLACE VIEW v_session_conversions AS
+SELECT 
+    DATE(started_at) as date,
+    platform,
+    COUNT(*) as total_sessions,
+    COUNT(CASE WHEN converted THEN 1 END) as converted_sessions,
+    ROUND(100.0 * COUNT(CASE WHEN converted THEN 1 END) / NULLIF(COUNT(*), 0), 2) as conversion_rate,
+    AVG(duration_seconds) as avg_session_duration
+FROM session_summaries
+GROUP BY DATE(started_at), platform
+ORDER BY DATE(started_at) DESC;
+
+-- ============================================
+-- MIGRATION COMPLETE
+-- ============================================
+-- Next steps:
+-- 1. Create TypeScript types matching this schema
+-- 2. Build AnalyticsService on frontend
+-- 3. Build analytics routes on backend
+-- 4. Start tracking events!
+
+
+

package/scripts/migrations/002_add_matchup_image_url.sql

@@ -0,0 +1,14 @@
+-- Migration 002: Add matchup_image_url column to games table
+-- This column stores the S3 URL for pre-generated matchup images
+
+ALTER TABLE games ADD COLUMN IF NOT EXISTS matchup_image_url TEXT;
+
+-- Optional: Add an index if you'll be querying by this column
+-- CREATE INDEX IF NOT EXISTS idx_games_matchup_image_url ON games(matchup_image_url);
+
+-- Verify the column was added
+SELECT column_name, data_type 
+FROM information_schema.columns 
+WHERE table_name = 'games' AND column_name = 'matchup_image_url';
+
+

package/scripts/migrations/003_referral_earnings.sql

@@ -0,0 +1,208 @@
+-- ═══════════════════════════════════════════════════════════════════════════
+-- REFERRAL EARNINGS SYSTEM
+-- ═══════════════════════════════════════════════════════════════════════════
+-- 
+-- This migration creates the referral earnings tracking system.
+-- 
+-- ⚠️ IMPORTANT: Commission goes to the GAME CREATOR's referrer ONLY!
+-- 
+-- The person who referred the GAME CREATOR earns 1% of the ENTIRE POT.
+-- Other players' referrers do NOT earn anything from the game.
+-- 
+-- Fee Structure:
+--   Current:  5% Operator + 1% Oracle = 6% Total
+--   Proposed: 4% Operator + 1% Referrer + 1% Oracle = 6% Total
+--
+-- If game creator has no referrer, the 1% goes to the operator (5% total).
+--
+-- Example (10-player game, 0.5 SOL buy-in each = 5 SOL pot):
+--   - Game creator was referred by UserX
+--   - UserX earns 0.05 SOL (1% of 5 SOL pot)
+--   - Operator gets 0.20 SOL (4% of 5 SOL) instead of 0.25 SOL (5%)
+--
+-- ═══════════════════════════════════════════════════════════════════════════
+
+-- Main earnings table - tracks each individual earning event
+CREATE TABLE IF NOT EXISTS referral_earnings (
+  id SERIAL PRIMARY KEY,
+  
+  -- Relationship: Referrer (who earns) and Referee (who played)
+  referrer_user_id INTEGER REFERENCES users(id) ON DELETE SET NULL,
+  referrer_wallet VARCHAR(44) NOT NULL,
+  referee_user_id INTEGER REFERENCES users(id) ON DELETE SET NULL,
+  referee_wallet VARCHAR(44) NOT NULL,
+  
+  -- Game details
+  game_id VARCHAR(255) NOT NULL,
+  game_type VARCHAR(50) NOT NULL, -- 'sports', 'billiards', 'jackpot'
+  
+  -- Financial details (all in lamports)
+  pot_size BIGINT NOT NULL,            -- Total pot of the game
+  referee_buy_in BIGINT NOT NULL,      -- Amount referee wagered
+  referee_won BOOLEAN NOT NULL,        -- Did referee win?
+  referee_payout BIGINT DEFAULT 0,     -- Amount referee won (0 if lost)
+  
+  -- Commission details
+  commission_rate DECIMAL(6,4) NOT NULL DEFAULT 0.0100, -- 1% = 0.0100
+  commission_amount BIGINT NOT NULL,   -- Actual commission in lamports
+  
+  -- Status and payout tracking
+  status VARCHAR(20) DEFAULT 'pending' CHECK (status IN ('pending', 'paid', 'cancelled')),
+  created_at TIMESTAMP DEFAULT NOW(),
+  paid_at TIMESTAMP,
+  payout_tx_signature VARCHAR(128),
+  payout_batch_id INTEGER,
+  notes TEXT, -- Optional notes (e.g., "Paid on-chain during game resolution")
+  
+  -- Prevent duplicate entries for same referee in same game
+  UNIQUE(referee_wallet, game_id)
+);
+
+-- Indexes for efficient queries
+CREATE INDEX IF NOT EXISTS idx_referral_earnings_referrer ON referral_earnings(referrer_user_id, status);
+CREATE INDEX IF NOT EXISTS idx_referral_earnings_referrer_wallet ON referral_earnings(referrer_wallet);
+CREATE INDEX IF NOT EXISTS idx_referral_earnings_referee ON referral_earnings(referee_user_id);
+CREATE INDEX IF NOT EXISTS idx_referral_earnings_game ON referral_earnings(game_id);
+CREATE INDEX IF NOT EXISTS idx_referral_earnings_status ON referral_earnings(status);
+CREATE INDEX IF NOT EXISTS idx_referral_earnings_created ON referral_earnings(created_at DESC);
+CREATE INDEX IF NOT EXISTS idx_referral_earnings_pending ON referral_earnings(referrer_wallet) WHERE status = 'pending';
+
+-- Payout batches table - tracks batch payouts to referrers
+CREATE TABLE IF NOT EXISTS referral_payout_batches (
+  id SERIAL PRIMARY KEY,
+  
+  -- Batch details
+  total_amount BIGINT NOT NULL,        -- Total lamports in this batch
+  num_referrers INTEGER NOT NULL,      -- Number of unique referrers paid
+  num_earnings INTEGER NOT NULL,       -- Number of individual earning records
+  
+  -- Transaction details
+  tx_signature VARCHAR(128),
+  status VARCHAR(20) DEFAULT 'pending' CHECK (status IN ('pending', 'processing', 'completed', 'failed')),
+  
+  -- Timing
+  created_at TIMESTAMP DEFAULT NOW(),
+  processed_at TIMESTAMP,
+  completed_at TIMESTAMP,
+  
+  -- Error tracking
+  error_message TEXT,
+  retry_count INTEGER DEFAULT 0
+);
+
+CREATE INDEX IF NOT EXISTS idx_payout_batches_status ON referral_payout_batches(status);
+
+-- Aggregated summary view for quick dashboard stats
+CREATE OR REPLACE VIEW referral_earnings_summary AS
+SELECT 
+  u.id as user_id,
+  u.wallet_address,
+  u.username,
+  u.my_referral_code,
+  COALESCE(COUNT(re.id), 0) as total_referral_games,
+  COALESCE(SUM(re.commission_amount), 0) as total_earned_lamports,
+  COALESCE(SUM(CASE WHEN re.status = 'pending' THEN re.commission_amount ELSE 0 END), 0) as pending_lamports,
+  COALESCE(SUM(CASE WHEN re.status = 'paid' THEN re.commission_amount ELSE 0 END), 0) as paid_lamports,
+  MAX(re.created_at) as last_earning_at
+FROM users u
+LEFT JOIN referral_earnings re ON u.wallet_address = re.referrer_wallet
+WHERE u.my_referral_code IS NOT NULL
+GROUP BY u.id, u.wallet_address, u.username, u.my_referral_code;
+
+-- Function to calculate referral commission for a game
+-- Call this after game resolution to record earnings for all players with referrers
+CREATE OR REPLACE FUNCTION process_game_referral_commissions(
+  p_game_id VARCHAR(255),
+  p_game_type VARCHAR(50),
+  p_pot_size BIGINT,
+  p_commission_rate DECIMAL DEFAULT 0.0100
+)
+RETURNS INTEGER AS $$
+DECLARE
+  v_count INTEGER := 0;
+  v_player RECORD;
+BEGIN
+  -- For each player in the game who has a referrer
+  FOR v_player IN 
+    SELECT 
+      ugr.wallet_address as referee_wallet,
+      ugr.buy_in,
+      ugr.won_game,
+      ugr.amount_claimed,
+      u.id as referee_user_id,
+      u.referral_code,
+      referrer.id as referrer_user_id,
+      referrer.wallet_address as referrer_wallet
+    FROM user_game_refs ugr
+    JOIN users u ON ugr.wallet_address = u.wallet_address
+    JOIN users referrer ON u.referral_code = referrer.my_referral_code
+    WHERE ugr.game_id = p_game_id
+      AND u.referral_code IS NOT NULL
+      AND referrer.my_referral_code IS NOT NULL
+  LOOP
+    -- Calculate commission (1% of pot size, proportional to player's contribution)
+    -- Each player's referrer gets 1% of THAT PLAYER's buy-in
+    DECLARE
+      v_commission BIGINT;
+    BEGIN
+      -- Commission = 1% of referee's buy-in (in lamports)
+      v_commission := FLOOR(v_player.buy_in * 1000000000 * p_commission_rate);
+      
+      -- Skip if commission is 0
+      IF v_commission > 0 THEN
+        -- Insert or update earning record
+        INSERT INTO referral_earnings (
+          referrer_user_id,
+          referrer_wallet,
+          referee_user_id,
+          referee_wallet,
+          game_id,
+          game_type,
+          pot_size,
+          referee_buy_in,
+          referee_won,
+          referee_payout,
+          commission_rate,
+          commission_amount,
+          status
+        ) VALUES (
+          v_player.referrer_user_id,
+          v_player.referrer_wallet,
+          v_player.referee_user_id,
+          v_player.referee_wallet,
+          p_game_id,
+          p_game_type,
+          p_pot_size,
+          FLOOR(v_player.buy_in * 1000000000), -- Convert SOL to lamports
+          COALESCE(v_player.won_game, false),
+          COALESCE(FLOOR(v_player.amount_claimed * 1000000000), 0),
+          p_commission_rate,
+          v_commission,
+          'pending'
+        )
+        ON CONFLICT (referee_wallet, game_id) DO NOTHING;
+        
+        v_count := v_count + 1;
+      END IF;
+    END;
+  END LOOP;
+  
+  RETURN v_count;
+END;
+$$ LANGUAGE plpgsql;
+
+-- Grant necessary permissions (if using different roles)
+-- GRANT ALL ON referral_earnings TO your_app_role;
+-- GRANT ALL ON referral_payout_batches TO your_app_role;
+-- GRANT SELECT ON referral_earnings_summary TO your_app_role;
+
+-- Log migration
+DO $$
+BEGIN
+  RAISE NOTICE '✅ Referral earnings tables created successfully';
+  RAISE NOTICE '   - referral_earnings: tracks individual commission events';
+  RAISE NOTICE '   - referral_payout_batches: tracks batch payouts';
+  RAISE NOTICE '   - referral_earnings_summary: aggregated view for dashboards';
+  RAISE NOTICE '   - process_game_referral_commissions(): function to process game commissions';
+END $$;
+