dubs-server 1.0.0

package/services/referralEarningsService.js

@@ -0,0 +1,728 @@
+/**
+ * 💰 Referral Earnings Service
+ * 
+ * Handles referral commission calculation, storage, and payouts.
+ * 
+ * ⚠️ IMPORTANT: Commission goes to the GAME CREATOR's referrer ONLY!
+ * NOT to every player's referrer.
+ * 
+ * Fee Structure:
+ *   - The person who referred the GAME CREATOR earns 1% of the ENTIRE POT
+ *   - Commission comes from the operator's 5% fee (now 4% + 1% referral)
+ *   - If game creator has no referrer, operator keeps the full 5%
+ * 
+ * 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%)
+ *   - Other players' referrers get NOTHING from this game
+ */
+
+const { pool } = require('./db'); // Shared database pool
+
+// Configuration
+const REFERRAL_COMMISSION_RATE = 0.01; // 1%
+const LAMPORTS_PER_SOL = 1_000_000_000;
+
+/**
+ * Get referrer info for a wallet address
+ * Returns null if the user has no referrer
+ */
+async function getReferrerForWallet(walletAddress) {
+  try {
+    const result = await pool.query(`
+      SELECT 
+        u.referral_code,
+        referrer.id as referrer_user_id,
+        referrer.wallet_address as referrer_wallet,
+        referrer.username as referrer_username
+      FROM users u
+      LEFT JOIN users referrer ON u.referral_code = referrer.my_referral_code
+      WHERE u.wallet_address = $1
+        AND u.referral_code IS NOT NULL
+        AND referrer.my_referral_code IS NOT NULL
+    `, [walletAddress]);
+
+    if (result.rows.length === 0) {
+      return null;
+    }
+
+    return result.rows[0];
+  } catch (error) {
+    console.error('[ReferralEarnings] Error getting referrer:', error.message);
+    return null;
+  }
+}
+
+/**
+ * Calculate and store referral commission for the GAME CREATOR's referrer
+ * Called after a game is resolved by the oracle
+ * 
+ * ⚠️ IMPORTANT: Only the GAME CREATOR's referrer earns commission!
+ * They earn 1% of the ENTIRE POT, not just the creator's buy-in.
+ * 
+ * @param {string} gameId - The game ID
+ * @param {string} gameType - 'sports', 'billiards', 'jackpot'
+ * @param {number} potSizeLamports - Total pot size in lamports
+ * @returns {Object} - Summary of commission processed
+ */
+async function processGameCommissions(gameId, gameType, potSizeLamports) {
+  const startTime = Date.now();
+  const logPrefix = `[PROCESS-COMMISSION:${gameId.slice(-8)}]`;
+
+  console.log(`${logPrefix} ════════════════════════════════════════════════════`);
+  console.log(`${logPrefix} 📊 Processing referral commission for game`);
+  console.log(`${logPrefix}    Full Game ID: ${gameId}`);
+  console.log(`${logPrefix}    Game Type: ${gameType}`);
+  console.log(`${logPrefix}    Pot Size: ${potSizeLamports} lamports (${potSizeLamports / LAMPORTS_PER_SOL} SOL)`);
+  console.log(`${logPrefix} ════════════════════════════════════════════════════`);
+
+  const summary = {
+    gameId,
+    gameType,
+    potSizeLamports,
+    gameCreator: null,
+    creatorHasReferrer: false,
+    totalCommissionsLamports: 0,
+    commissions: []
+  };
+
+  try {
+    // Step 1: Get the GAME CREATOR from the games table
+    console.log(`${logPrefix} Step 1: Looking up game creator and their referrer...`);
+    const gameResult = await pool.query(`
+      SELECT
+        g.created_by as creator_wallet,
+        g.title,
+        u.id as creator_user_id,
+        u.username as creator_username,
+        u.referral_code,
+        referrer.id as referrer_user_id,
+        referrer.wallet_address as referrer_wallet,
+        referrer.username as referrer_username,
+        referrer.my_referral_code as referrer_my_code
+      FROM games g
+      JOIN users u ON g.created_by = u.wallet_address
+      LEFT JOIN users referrer ON u.referral_code = referrer.my_referral_code
+      WHERE g.game_id = $1
+    `, [gameId]);
+
+    console.log(`${logPrefix}    Query returned ${gameResult.rows.length} row(s)`);
+
+    if (gameResult.rows.length === 0) {
+      console.log(`${logPrefix} ⚠️ Game ${gameId} not found in database - cannot process commission`);
+      console.log(`${logPrefix}    This could mean: game deleted, or game_id mismatch`);
+      return summary;
+    }
+
+    const game = gameResult.rows[0];
+    summary.gameCreator = game.creator_wallet;
+
+    console.log(`${logPrefix} Step 2: Analyzing game creator's referral status`);
+    console.log(`${logPrefix}    Game title: ${game.title || 'untitled'}`);
+    console.log(`${logPrefix}    Creator: ${game.creator_username || 'unknown'} (${game.creator_wallet})`);
+    console.log(`${logPrefix}    Creator's referral_code: ${game.referral_code || 'NULL (never referred)'}`);
+
+    // Step 2: Check if the game creator has a referrer
+    if (!game.referrer_wallet) {
+      console.log(`${logPrefix} ℹ️ Game creator has NO referrer`);
+      if (game.referral_code) {
+        console.log(`${logPrefix}    ⚠️ Creator has referral_code="${game.referral_code}" but no matching referrer!`);
+        console.log(`${logPrefix}    Possible causes: referrer account deleted, referrer's my_referral_code changed`);
+      } else {
+        console.log(`${logPrefix}    Creator signed up without a referral code - operator keeps full 5%`);
+      }
+      return summary;
+    }
+
+    summary.creatorHasReferrer = true;
+    console.log(`${logPrefix} ✅ FOUND REFERRER!`);
+    console.log(`${logPrefix}    Referrer: ${game.referrer_username || 'unknown'} (${game.referrer_wallet})`);
+    console.log(`${logPrefix}    Match: creator.referral_code(${game.referral_code}) = referrer.my_referral_code(${game.referrer_my_code})`);
+
+    // Step 3: Calculate commission (1% of ENTIRE POT)
+    console.log(`${logPrefix} Step 3: Calculating commission (1% of pot)`);
+    const commissionLamports = Math.floor(potSizeLamports * REFERRAL_COMMISSION_RATE);
+    console.log(`${logPrefix}    ${potSizeLamports} × ${REFERRAL_COMMISSION_RATE} = ${commissionLamports} lamports`);
+    console.log(`${logPrefix}    Commission: ${commissionLamports / LAMPORTS_PER_SOL} SOL`);
+
+    if (commissionLamports <= 0) {
+      console.log(`${logPrefix} ⚠️ Skipping - commission is 0 or negative (pot too small)`);
+      return summary;
+    }
+
+    // Step 4: Insert earning record (one per game, for the creator's referrer)
+    console.log(`${logPrefix} Step 4: Inserting referral_earnings record...`);
+    console.log(`${logPrefix}    NOTE: This creates a 'pending' status record WITHOUT tx signature`);
+    console.log(`${logPrefix}    The oracle's recordReferralCommission should update this with signature later`);
+
+    try {
+      const insertResult = await pool.query(`
+        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 ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, 'pending')
+        ON CONFLICT (referee_wallet, game_id) DO NOTHING
+        RETURNING id
+      `, [
+        game.referrer_user_id,
+        game.referrer_wallet,
+        game.creator_user_id,
+        game.creator_wallet,
+        gameId,
+        gameType,
+        potSizeLamports,
+        potSizeLamports, // Using pot size as "buy-in" since commission is based on whole pot
+        true, // Game was created (considered a "win" for commission purposes)
+        0,
+        REFERRAL_COMMISSION_RATE,
+        commissionLamports
+      ]);
+
+      if (insertResult.rows.length > 0) {
+        summary.totalCommissionsLamports = commissionLamports;
+        summary.commissions.push({
+          referrerWallet: game.referrer_wallet,
+          referrerUsername: game.referrer_username,
+          refereeWallet: game.creator_wallet,
+          refereeUsername: game.creator_username,
+          commissionLamports,
+          commissionSOL: commissionLamports / LAMPORTS_PER_SOL
+        });
+
+        console.log(`${logPrefix} ✅ SUCCESS! Created referral_earnings record (ID: ${insertResult.rows[0].id})`);
+        console.log(`${logPrefix}    ${game.referrer_username || game.referrer_wallet.slice(0, 8)} earns ${commissionLamports / LAMPORTS_PER_SOL} SOL`);
+        console.log(`${logPrefix}    from ${game.creator_username || game.creator_wallet.slice(0, 8)}'s game`);
+      } else {
+        console.log(`${logPrefix} ℹ️ Record already exists (conflict on referee_wallet + game_id)`);
+        console.log(`${logPrefix}    This is expected if processGameCommissions was called twice for same game`);
+      }
+    } catch (insertError) {
+      console.error(`${logPrefix} ❌ ERROR inserting referral_earnings record:`);
+      console.error(`${logPrefix}    Message: ${insertError.message}`);
+      console.error(`${logPrefix}    Code: ${insertError.code}`);
+    }
+
+    const duration = Date.now() - startTime;
+    console.log(`${logPrefix} ════════════════════════════════════════════════════`);
+    console.log(`${logPrefix} 🎉 Processed in ${duration}ms`);
+    console.log(`${logPrefix} ════════════════════════════════════════════════════`);
+
+    return summary;
+
+  } catch (error) {
+    console.error(`${logPrefix} ❌ FATAL ERROR processing game commissions:`);
+    console.error(`${logPrefix}    Message: ${error.message}`);
+    console.error(`${logPrefix}    Stack: ${error.stack}`);
+    throw error;
+  }
+}
+
+/**
+ * Get referral earnings for a specific wallet
+ * @param {string} walletAddress - Referrer's wallet address
+ * @param {Object} options - Query options
+ * @returns {Object} - Earnings list and summary
+ */
+async function getEarningsForWallet(walletAddress, options = {}) {
+  const { limit = 50, offset = 0, status = null } = options;
+
+  try {
+    // Get summary stats
+    const summaryResult = await pool.query(`
+      SELECT 
+        COUNT(*) as total_earnings,
+        COALESCE(SUM(commission_amount), 0) as total_earned_lamports,
+        COALESCE(SUM(CASE WHEN status = 'pending' THEN commission_amount ELSE 0 END), 0) as pending_lamports,
+        COALESCE(SUM(CASE WHEN status = 'paid' THEN commission_amount ELSE 0 END), 0) as paid_lamports,
+        COUNT(DISTINCT referee_wallet) as unique_referees,
+        COUNT(DISTINCT game_id) as games_count
+      FROM referral_earnings
+      WHERE referrer_wallet = $1
+    `, [walletAddress]);
+
+    // Build query for individual earnings
+    let earningsQuery = `
+      SELECT 
+        re.*,
+        u.username as referee_username,
+        u.avatar as referee_avatar,
+        g.title as game_title,
+        g.sports_event
+      FROM referral_earnings re
+      LEFT JOIN users u ON re.referee_wallet = u.wallet_address
+      LEFT JOIN games g ON re.game_id = g.game_id
+      WHERE re.referrer_wallet = $1
+    `;
+    const params = [walletAddress];
+
+    if (status) {
+      earningsQuery += ` AND re.status = $${params.length + 1}`;
+      params.push(status);
+    }
+
+    earningsQuery += ` ORDER BY re.created_at DESC LIMIT $${params.length + 1} OFFSET $${params.length + 2}`;
+    params.push(limit, offset);
+
+    const earningsResult = await pool.query(earningsQuery, params);
+
+    const summary = summaryResult.rows[0];
+
+    return {
+      summary: {
+        totalEarnings: parseInt(summary.total_earnings),
+        totalEarnedLamports: parseInt(summary.total_earned_lamports),
+        totalEarnedSOL: parseInt(summary.total_earned_lamports) / LAMPORTS_PER_SOL,
+        pendingLamports: parseInt(summary.pending_lamports),
+        pendingSOL: parseInt(summary.pending_lamports) / LAMPORTS_PER_SOL,
+        paidLamports: parseInt(summary.paid_lamports),
+        paidSOL: parseInt(summary.paid_lamports) / LAMPORTS_PER_SOL,
+        uniqueReferees: parseInt(summary.unique_referees),
+        gamesCount: parseInt(summary.games_count)
+      },
+      earnings: earningsResult.rows.map(row => ({
+        id: row.id,
+        refereeWallet: row.referee_wallet,
+        refereeUsername: row.referee_username,
+        refereeAvatar: row.referee_avatar,
+        gameId: row.game_id,
+        gameType: row.game_type,
+        gameTitle: row.game_title,
+        sportsEvent: row.sports_event,
+        refereeBuyInLamports: parseInt(row.referee_buy_in),
+        refereeBuyInSOL: parseInt(row.referee_buy_in) / LAMPORTS_PER_SOL,
+        refereeWon: row.referee_won,
+        refereePayoutLamports: parseInt(row.referee_payout),
+        refereePayoutSOL: parseInt(row.referee_payout) / LAMPORTS_PER_SOL,
+        commissionRate: parseFloat(row.commission_rate),
+        commissionLamports: parseInt(row.commission_amount),
+        commissionSOL: parseInt(row.commission_amount) / LAMPORTS_PER_SOL,
+        status: row.status,
+        createdAt: row.created_at,
+        paidAt: row.paid_at,
+        txSignature: row.payout_tx_signature // Include tx signature for transaction matching
+      })),
+      pagination: {
+        limit,
+        offset,
+        hasMore: earningsResult.rows.length === limit
+      }
+    };
+
+  } catch (error) {
+    console.error('[ReferralEarnings] Error getting earnings:', error.message);
+    throw error;
+  }
+}
+
+/**
+ * Get pending payouts grouped by referrer (for batch payout processing)
+ * @param {number} minAmount - Minimum amount in lamports to include
+ * @returns {Array} - List of referrers with pending amounts
+ */
+async function getPendingPayouts(minAmount = 0) {
+  try {
+    const result = await pool.query(`
+      SELECT 
+        referrer_wallet,
+        COUNT(*) as num_earnings,
+        SUM(commission_amount) as total_pending_lamports
+      FROM referral_earnings
+      WHERE status = 'pending'
+      GROUP BY referrer_wallet
+      HAVING SUM(commission_amount) >= $1
+      ORDER BY SUM(commission_amount) DESC
+    `, [minAmount]);
+
+    return result.rows.map(row => ({
+      referrerWallet: row.referrer_wallet,
+      numEarnings: parseInt(row.num_earnings),
+      totalPendingLamports: parseInt(row.total_pending_lamports),
+      totalPendingSOL: parseInt(row.total_pending_lamports) / LAMPORTS_PER_SOL
+    }));
+
+  } catch (error) {
+    console.error('[ReferralEarnings] Error getting pending payouts:', error.message);
+    throw error;
+  }
+}
+
+/**
+ * Mark earnings as paid (called after successful payout transaction)
+ * @param {string} referrerWallet - Wallet that received payout
+ * @param {string} txSignature - Solana transaction signature
+ * @param {number} batchId - Optional batch ID
+ * @returns {number} - Number of records updated
+ */
+async function markEarningsAsPaid(referrerWallet, txSignature, batchId = null) {
+  try {
+    const result = await pool.query(`
+      UPDATE referral_earnings
+      SET 
+        status = 'paid',
+        paid_at = NOW(),
+        payout_tx_signature = $2,
+        payout_batch_id = $3
+      WHERE referrer_wallet = $1
+        AND status = 'pending'
+      RETURNING id
+    `, [referrerWallet, txSignature, batchId]);
+
+    console.log(`[ReferralEarnings] ✅ Marked ${result.rows.length} earnings as paid for ${referrerWallet.slice(0, 8)}`);
+    return result.rows.length;
+
+  } catch (error) {
+    console.error('[ReferralEarnings] Error marking earnings as paid:', error.message);
+    throw error;
+  }
+}
+
+/**
+ * Create a payout batch record
+ * @param {number} totalAmount - Total lamports in batch
+ * @param {number} numReferrers - Number of unique referrers
+ * @param {number} numEarnings - Number of earning records
+ * @returns {number} - Batch ID
+ */
+async function createPayoutBatch(totalAmount, numReferrers, numEarnings) {
+  try {
+    const result = await pool.query(`
+      INSERT INTO referral_payout_batches (
+        total_amount,
+        num_referrers,
+        num_earnings,
+        status
+      ) VALUES ($1, $2, $3, 'pending')
+      RETURNING id
+    `, [totalAmount, numReferrers, numEarnings]);
+
+    return result.rows[0].id;
+
+  } catch (error) {
+    console.error('[ReferralEarnings] Error creating payout batch:', error.message);
+    throw error;
+  }
+}
+
+/**
+ * Update payout batch status
+ * @param {number} batchId - Batch ID
+ * @param {string} status - New status
+ * @param {string} txSignature - Optional transaction signature
+ * @param {string} errorMessage - Optional error message
+ */
+async function updatePayoutBatch(batchId, status, txSignature = null, errorMessage = null) {
+  try {
+    const completedAt = status === 'completed' ? 'NOW()' : 'NULL';
+    
+    await pool.query(`
+      UPDATE referral_payout_batches
+      SET 
+        status = $2,
+        tx_signature = COALESCE($3, tx_signature),
+        error_message = $4,
+        processed_at = CASE WHEN $2 = 'processing' THEN NOW() ELSE processed_at END,
+        completed_at = CASE WHEN $2 = 'completed' THEN NOW() ELSE completed_at END,
+        retry_count = CASE WHEN $2 = 'failed' THEN retry_count + 1 ELSE retry_count END
+      WHERE id = $1
+    `, [batchId, status, txSignature, errorMessage]);
+
+  } catch (error) {
+    console.error('[ReferralEarnings] Error updating payout batch:', error.message);
+    throw error;
+  }
+}
+
+/**
+ * Get referral leaderboard (top earners)
+ * @param {number} limit - Number of results
+ * @returns {Array} - Leaderboard entries
+ */
+async function getLeaderboard(limit = 20) {
+  try {
+    const result = await pool.query(`
+      SELECT 
+        re.referrer_wallet,
+        u.username,
+        u.avatar,
+        COUNT(DISTINCT re.referee_wallet) as total_referees,
+        COUNT(re.id) as total_games,
+        SUM(re.commission_amount) as total_earned_lamports
+      FROM referral_earnings re
+      LEFT JOIN users u ON re.referrer_wallet = u.wallet_address
+      GROUP BY re.referrer_wallet, u.username, u.avatar
+      ORDER BY SUM(re.commission_amount) DESC
+      LIMIT $1
+    `, [limit]);
+
+    return result.rows.map((row, index) => ({
+      rank: index + 1,
+      walletAddress: row.referrer_wallet,
+      username: row.username,
+      avatar: row.avatar,
+      totalReferees: parseInt(row.total_referees),
+      totalGames: parseInt(row.total_games),
+      totalEarnedLamports: parseInt(row.total_earned_lamports),
+      totalEarnedSOL: parseInt(row.total_earned_lamports) / LAMPORTS_PER_SOL
+    }));
+
+  } catch (error) {
+    console.error('[ReferralEarnings] Error getting leaderboard:', error.message);
+    throw error;
+  }
+}
+
+/**
+ * Get platform-wide referral stats
+ * @returns {Object} - Platform stats
+ */
+async function getPlatformStats() {
+  try {
+    // Get stats from referral_earnings table (actual commissions paid)
+    const earningsResult = await pool.query(`
+      SELECT 
+        COUNT(DISTINCT referrer_wallet) as total_referrers_with_earnings,
+        COUNT(DISTINCT referee_wallet) as total_referees_with_earnings,
+        COUNT(*) as total_earnings,
+        COALESCE(SUM(commission_amount), 0) as total_paid_out_lamports,
+        COALESCE(SUM(CASE WHEN status = 'pending' THEN commission_amount ELSE 0 END), 0) as total_pending_lamports
+      FROM referral_earnings
+    `);
+
+    // Get stats from users table (referral relationships)
+    // Active referrers: users who have a my_referral_code AND have at least one user who used their code
+    const referrersResult = await pool.query(`
+      SELECT COUNT(DISTINCT referrer.id) as total_active_referrers
+      FROM users referrer
+      WHERE referrer.my_referral_code IS NOT NULL
+        AND EXISTS (
+          SELECT 1 FROM users referee 
+          WHERE referee.referral_code = referrer.my_referral_code
+        )
+    `);
+
+    // Total referred users: users who signed up with a referral code
+    const refereesResult = await pool.query(`
+      SELECT COUNT(*) as total_referred_users
+      FROM users
+      WHERE referral_code IS NOT NULL
+    `);
+
+    const earningsStats = earningsResult.rows[0];
+    const referrersStats = referrersResult.rows[0];
+    const refereesStats = refereesResult.rows[0];
+
+    return {
+      // Active referrers: users who have referred at least one person (from users table)
+      totalReferrers: parseInt(referrersStats.total_active_referrers) || 0,
+      // Referred users: users who signed up with a referral code (from users table)
+      totalReferees: parseInt(refereesStats.total_referred_users) || 0,
+      // Earnings stats (from referral_earnings table)
+      totalEarnings: parseInt(earningsStats.total_earnings) || 0,
+      totalPaidOutLamports: parseInt(earningsStats.total_paid_out_lamports) || 0,
+      totalPaidOutSOL: parseInt(earningsStats.total_paid_out_lamports) / LAMPORTS_PER_SOL || 0,
+      totalPendingLamports: parseInt(earningsStats.total_pending_lamports) || 0,
+      totalPendingSOL: parseInt(earningsStats.total_pending_lamports) / LAMPORTS_PER_SOL || 0
+    };
+
+  } catch (error) {
+    console.error('[ReferralEarnings] Error getting platform stats:', error.message);
+    throw error;
+  }
+}
+
+/**
+ * Record an on-chain commission payment
+ * Called by the oracle after game resolution with referrer
+ *
+ * This is for tracking/display purposes - the actual SOL transfer
+ * already happened on-chain during game resolution.
+ *
+ * @param {string} gameId - The game ID
+ * @param {string} referrerWallet - Referrer's wallet that received payment
+ * @param {number} commissionLamports - Commission amount in lamports
+ * @param {boolean} paidOnChain - Whether payment was made on-chain (should be true)
+ * @param {string} txSignature - Transaction signature for the payout
+ * @param {string} gameType - Type of game ('sports', 'connect4', 'billiards')
+ * @returns {Object} - Result of the recording
+ */
+async function recordOnChainCommission(gameId, referrerWallet, commissionLamports, paidOnChain = true, txSignature = null, gameType = 'sports') {
+  const logPrefix = `[ONCHAIN-COMMISSION:${gameId.slice(-8)}]`;
+
+  console.log(`${logPrefix} ════════════════════════════════════════════════════`);
+  console.log(`${logPrefix} 📝 Recording on-chain referral commission`);
+  console.log(`${logPrefix}    Full Game ID: ${gameId}`);
+  console.log(`${logPrefix}    Referrer Wallet: ${referrerWallet}`);
+  console.log(`${logPrefix}    Commission: ${commissionLamports} lamports (${commissionLamports / LAMPORTS_PER_SOL} SOL)`);
+  console.log(`${logPrefix}    Paid On-Chain: ${paidOnChain}`);
+  console.log(`${logPrefix}    TX Signature: ${txSignature || 'NOT PROVIDED ⚠️'}`);
+  console.log(`${logPrefix}    Game Type: ${gameType}`);
+  console.log(`${logPrefix} ════════════════════════════════════════════════════`);
+
+  if (!txSignature) {
+    console.log(`${logPrefix} ⚠️ WARNING: No transaction signature - record will be unverifiable on blockchain!`);
+  }
+
+  try {
+    // Get game and referrer info
+    console.log(`${logPrefix} Step 1: Looking up game and user info...`);
+    const gameResult = await pool.query(`
+      SELECT
+        g.game_id,
+        g.created_by as creator_wallet,
+        g.title,
+        creator.id as creator_user_id,
+        creator.username as creator_username,
+        referrer.id as referrer_user_id,
+        referrer.username as referrer_username
+      FROM games g
+      JOIN users creator ON g.created_by = creator.wallet_address
+      LEFT JOIN users referrer ON referrer.wallet_address = $2
+      WHERE g.game_id = $1
+    `, [gameId, referrerWallet]);
+
+    console.log(`${logPrefix}    Query returned ${gameResult.rows.length} row(s)`);
+
+    if (gameResult.rows.length === 0) {
+      console.log(`${logPrefix} ❌ Game ${gameId} not found in database`);
+      return { success: false, error: 'Game not found' };
+    }
+
+    const game = gameResult.rows[0];
+    console.log(`${logPrefix}    Game: ${game.title || 'untitled'}`);
+    console.log(`${logPrefix}    Creator: ${game.creator_username || 'unknown'} (${game.creator_wallet})`);
+    console.log(`${logPrefix}    Referrer user in DB: ${game.referrer_username || 'NOT FOUND'} (ID: ${game.referrer_user_id || 'NULL'})`);
+
+    // Check if already recorded
+    console.log(`${logPrefix} Step 2: Checking for existing referral_earnings record...`);
+    const existingResult = await pool.query(`
+      SELECT id, status, payout_tx_signature FROM referral_earnings
+      WHERE game_id = $1 AND referrer_wallet = $2
+    `, [gameId, referrerWallet]);
+
+    console.log(`${logPrefix}    Found ${existingResult.rows.length} existing record(s)`);
+
+    if (existingResult.rows.length > 0) {
+      const existing = existingResult.rows[0];
+      console.log(`${logPrefix}    Existing record ID: ${existing.id}`);
+      console.log(`${logPrefix}    Existing status: ${existing.status}`);
+      console.log(`${logPrefix}    Existing tx_signature: ${existing.payout_tx_signature || 'NULL'}`);
+
+      // Update existing record to mark as paid on-chain with signature
+      console.log(`${logPrefix} Step 3: Updating existing record with paid status and signature...`);
+      await pool.query(`
+        UPDATE referral_earnings
+        SET
+          status = 'paid',
+          paid_at = NOW(),
+          payout_tx_signature = COALESCE($3, payout_tx_signature),
+          notes = 'Paid on-chain during game resolution'
+        WHERE game_id = $1 AND referrer_wallet = $2
+      `, [gameId, referrerWallet, txSignature]);
+
+      console.log(`${logPrefix} ✅ SUCCESS: Updated existing record as paid on-chain`);
+      console.log(`${logPrefix}    Record ID: ${existing.id}`);
+      console.log(`${logPrefix}    New signature: ${txSignature || '(kept existing)'}`);
+
+      return {
+        success: true,
+        action: 'updated',
+        earningId: existing.id,
+        txSignature
+      };
+    }
+
+    // Insert new record (already paid on-chain) with signature
+    console.log(`${logPrefix} Step 3: No existing record - creating new one with 'paid' status...`);
+    const estimatedPotSize = commissionLamports * 100; // 1% commission means pot is 100x
+    console.log(`${logPrefix}    Estimated pot size: ${estimatedPotSize} lamports (${estimatedPotSize / LAMPORTS_PER_SOL} SOL)`);
+
+    const insertResult = await pool.query(`
+      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,
+        paid_at,
+        payout_tx_signature,
+        notes
+      ) VALUES ($1, $2, $3, $4, $5, $6, $7, $7, true, 0, $8, $9, 'paid', NOW(), $10, 'Paid on-chain during game resolution')
+      RETURNING id
+    `, [
+      game.referrer_user_id || null,
+      referrerWallet,
+      game.creator_user_id,
+      game.creator_wallet,
+      gameId,
+      gameType, // Use the provided gameType
+      estimatedPotSize, // pot_size (estimated from commission)
+      REFERRAL_COMMISSION_RATE,
+      commissionLamports,
+      txSignature
+    ]);
+
+    console.log(`${logPrefix} ✅ SUCCESS: Created new referral_earnings record`);
+    console.log(`${logPrefix}    New Record ID: ${insertResult.rows[0].id}`);
+    console.log(`${logPrefix}    TX Signature stored: ${txSignature || 'NULL'}`);
+    console.log(`${logPrefix} ════════════════════════════════════════════════════`);
+
+    return {
+      success: true,
+      action: 'created',
+      earningId: insertResult.rows[0].id,
+      txSignature
+    };
+
+  } catch (error) {
+    console.error(`${logPrefix} ❌ FATAL ERROR recording on-chain commission:`);
+    console.error(`${logPrefix}    Message: ${error.message}`);
+    console.error(`${logPrefix}    Code: ${error.code}`);
+    console.error(`${logPrefix}    Stack: ${error.stack}`);
+    return { success: false, error: error.message };
+  }
+}
+
+module.exports = {
+  // Configuration
+  REFERRAL_COMMISSION_RATE,
+  LAMPORTS_PER_SOL,
+  
+  // Core functions
+  getReferrerForWallet,
+  processGameCommissions,
+  getEarningsForWallet,
+  
+  // On-chain commission recording
+  recordOnChainCommission,
+  
+  // Payout functions (for off-chain batch payouts - legacy)
+  getPendingPayouts,
+  markEarningsAsPaid,
+  createPayoutBatch,
+  updatePayoutBatch,
+  
+  // Stats and leaderboard
+  getLeaderboard,
+  getPlatformStats
+};
+