DEMO_TOKEN_SYSTEM.md

Demo Token System

Overview

The demo token system allows users to practice trading on the crash game platform without using real cryptocurrency. Users can claim demo tokens, place bets throughout the game, and track their performance with detailed statistics.

Features

🎁 Demo Token Claims

• 1000 tokens per claim: Users get 1000 demo tokens when they first connect
• Daily limit: Users can claim once per day to prevent abuse
• Automatic user creation: New users are automatically created when claiming tokens
• Balance tracking: All transactions are recorded in the database

🎮 Trading Interface

• Real-time betting: Place bets at any multiplier during the game
• Buy/Sell buttons: Simple interface for entering and exiting positions
• Amount controls: Quick adjustment buttons (+0.001, +0.01, +0.1, +1, 1/2, ×2, MAX)
• Percentage slider: Set bet amount as percentage of balance (10%, 25%, 50%, 100%)
• Live balance updates: See your balance change in real-time

📊 Statistics & History

• Comprehensive stats: Total wagered, total won, win rate, average bet
• Betting history: Complete record of all bets with entry/exit multipliers
• Performance tracking: Track your success rate and profit/loss
• Real-time updates: Stats update automatically after each bet

Database Schema

User Model

model User {
  id            Int      @id @default(autoincrement())
  walletAddress String   @unique
  username      String   @unique
  balance       Float    @default(0) // Demo token balance
  totalWagered  Float    @default(0)
  totalWon      Float    @default(0)
  level         Int      @default(1)
  experience    Int      @default(0)
  // ... other fields
}

GameBet Model

model GameBet {
  id              Int      @id @default(autoincrement())
  userId          Int
  roundId         String
  betAmount       Float
  entryMultiplier Float    @default(1.0) // Multiplier when bet was placed
  cashoutMultiplier Float? // Multiplier when cashed out (null if not cashed out)
  profit          Float    @default(0)
  status          GameBetStatus @default(ACTIVE)
  placedAt        DateTime @default(now())
  cashedOutAt     DateTime?
  // ... relations
}

Transaction Model

model Transaction {
  id          Int             @id @default(autoincrement())
  userId      Int
  type        TransactionType // DEPOSIT, WITHDRAWAL, BET, WIN, LOSS, BONUS
  amount      Float
  balance     Float
  description String?
  status      TransactionStatus @default(PENDING)
  createdAt   DateTime        @default(now())
  // ... relations
}

API Endpoints

Claim Demo Tokens

POST /api/demo/claim-tokens
Content-Type: application/json

{
  "walletAddress": "user_wallet_address"
}

Response:

{
  "success": true,
  "message": "Demo tokens claimed successfully!",
  "user": {
    "id": 1,
    "username": "Demo_user123",
    "walletAddress": "user_wallet_address",
    "balance": 1000,
    "level": 1,
    "experience": 0
  }
}

Get User Statistics

GET /api/user/stats/{userId}

Response:

{
  "user": {
    "id": 1,
    "username": "Demo_user123",
    "balance": 850,
    "totalWagered": 500,
    "totalWon": 350,
    "level": 1,
    "experience": 0
  },
  "stats": {
    "totalBets": 10,
    "wonBets": 6,
    "lostBets": 4,
    "winRate": "60.00",
    "averageBet": 50.0
  }
}

Get Betting History

GET /api/user/betting-history/{userId}

Response:

[
  {
    "id": 1,
    "betAmount": 50,
    "entryMultiplier": 1.0,
    "cashoutMultiplier": 2.5,
    "profit": 75,
    "status": "CASHED_OUT",
    "placedAt": "2024-01-01T10:00:00Z",
    "cashedOutAt": "2024-01-01T10:05:00Z",
    "round": {
      "roundId": "abc123",
      "crashPoint": 3.2,
      "startTime": "2024-01-01T10:00:00Z",
      "endTime": "2024-01-01T10:08:00Z",
      "status": "CRASHED"
    }
  }
]

Socket.IO Events

Place Bet

socket.emit("place_bet", {
  betAmount: 50,
  userId: 1
});

Response:

socket.on("bet_placed", (data) => {
  if (data.success) {
    console.log(`Bet placed: ${data.betId}`);
    console.log(`Entry multiplier: ${data.entryMultiplier}x`);
    console.log(`New balance: ${data.newBalance}`);
  }
});

Cashout

socket.emit("cashout", {
  multiplier: 2.5
});

Response:

socket.on("cashout_success", (data) => {
  console.log(`Cashed out at ${data.multiplier}x`);
  console.log(`Total profit: ${data.totalProfit}`);
  console.log(`New balance: ${data.newBalance}`);
});

Frontend Components

DemoTokenPanel

• Displays when user has low balance or is not authenticated
• Shows claim button for demo tokens
• Displays current balance and features

TradingPanel

• Main trading interface with buy/sell buttons
• Amount adjustment controls
• Percentage slider
• Real-time balance display

UserStatsPanel

• User statistics with tabs for stats and history
• Comprehensive betting performance metrics
• Detailed betting history with status indicators

Usage Flow

1. Connect Wallet: User connects their Solana wallet
2. Claim Tokens: User claims 1000 demo tokens (once per day)
3. Place Bets: User can place bets at any multiplier during the game
4. Cashout: User can cashout their bets before the game crashes
5. Track Performance: User can view their statistics and betting history
6. Repeat: User can continue trading with their remaining balance

Testing

Run the test script to verify the demo token system:

cd rugsfe
node scripts/test-demo-tokens.js

This will test:

• Demo token claiming
• Duplicate claim prevention
• User statistics retrieval
• Betting history retrieval

Security Features

• Daily claim limit: Prevents abuse of the demo token system
• Balance validation: Ensures users can't bet more than they have
• Transaction recording: All actions are logged for audit purposes
• Status tracking: Bets are properly marked as active, cashed out, or lost

Future Enhancements

• Leaderboards: Compare performance with other demo traders
• Achievements: Unlock badges for successful trading
• Tutorial mode: Guided introduction to the trading interface
• Advanced analytics: More detailed performance metrics
• Social features: Share trading results with friends