Skip to content

lucky-roll.md

Latest commit

 

History

History
45 lines (32 loc) · 1.89 KB

lucky-roll.md

File metadata and controls

45 lines (32 loc) · 1.89 KB

Lucky Roll (Faucet) Feature

Lucky Roll Preview

The "Lucky Roll" is the core faucet mechanic where users roll a provably fair number to win rewards based on a tier system.

🎲 Core Mechanics

Randomness

  • Source: Node.js crypto.randomInt(0, 10000).
  • Range: 0000 - 9999 (Inclusive).
  • Tiers: Dynamic configuration maps roll ranges to reward amounts (e.g., 9999 = Jackpot).

Security & Integrity

  1. Transactional Integrity:

    • Uses pg_advisory_xact_lock on the User ID and IP Address during the claim transaction.
    • Purpose: Prevents race conditions (double claims) and high-concurrency exploits.

  2. Cooldowns:

    • User-based: Enforces cooldownSeconds (default: 3600s / 1 hour) per account.
    • IP-based: Prevents multiple accounts claiming from the same IP network simultaneously. The later of the two cooldowns is enforced.

  3. Circuit Breaker:

    • Global system lock check before processing.
    • Stops payouts if the system is in maintenance or under attack.

  4. Bot Detection (Heuristic):

    • Analyzes the last 6 claims.
    • Checks for "perfect intervals" (claiming within 15 seconds of the cooldown expiring).
    • Penalty: If behavior is consistent (5/5 perfect intervals), the user's suspiciousActivityScore is increased.
    • Ban: If score >= 100, the user is auto-banned for 24 hours.

Technical Implementation

  • Service: lib/services/faucet.ts
  • Endpoint: app/(protected)/lucky-roll/page.tsx
  • Validation: Server-side checks for email verification and ban status.

⚙️ Configuration

Admins can configure:

  • Cooldown: Time between claims.
  • Tiers: Ranges and Reward amounts.
  • Jackpot: Special tier notifications via Socket.io.