mining.md

Mining Simulation Feature

The Mining feature allows users to purchase "Virtual Miners" (Plans) that generate tokens passively over time.

⛏️ Mechanics

Virtual Hashrate

• Users buy plans to acquire "Hashrate".
• Formula: Reward = Hashrate * RatePerHashPerSecond * SecondsElapsed.
• The exact RatePerHashPerSecond is determined by the dailyRewardPerHash config (default: 1 hash = X tokens/day).

Checkpoint System

To serve thousands of users efficiently, the system does not update balances every second. Instead, it uses a Lazy Checkpoint system:

1. State: Stored in user_mining_state (Total Hashrate, Last Claimed Time, Pending Rewards).
2. Calculation: When a user visits the page, buys a miner, or claims:
   • Calculating (Now - LastClaimedTime).
   • Accruing new rewards to pendingRewards.
   • Updating LastClaimedTime to Now.

Plan Types

1. Standard Plans: Pre-configured by admins (Price, Hashrate, Duration).
2. Custom Plans: Users define investment amount and duration. The system dynamically calculates the Hashrate to achieve a target APY (Configurable).

🔒 Security

1. Atomic Transactions:

   • Purchases use database transactions to deduct tokens and grant miners simultaneously.
   • Uses FOR UPDATE row locking to prevent negative balance exploits.

2. Validation:

   • Checks plan availability (isActive, Sale End Date).
   • Enforces "Max Supply" and "Max Per User" limits.

3. Claim Limits:

   • Minimum Claim: Users must accumulate a minimum amount (e.g., 10 tokens) to claim.
   • Cooldown: Optional cooldown between claims (e.g., 1 hour) to reduce DB write load.

🛠️ Implementation

• Service: lib/services/mining.ts
• Config: lib/services/mining-config.ts (Stored in DB settings).
• Models: user_miners, user_mining_state, mining_plans.