Rewards System

The Vezta rewards system is a gamification engine that drives user engagement through points, missions, login streaks, referrals, and access keys. Every action — trading, viewing markets, sharing content, referring friends — earns points tracked in a centralized ledger.

Points System

Points Ledger

Post-signup point transactions are recorded in PointsLedger (the pre-signup waitlist keeps a separate WaitlistPointsLedger keyed by waitlistEntryId):

Points are purely additive — there is no spending flow in the current system (points are used for rank/access key eligibility, not redemption).

Earning Sources

Missions

Mission Types

Mission API Flow

1. Client fetches available missions: GET /api/v1/rewards
2. User completes a mission — client calls: POST /api/v1/rewards/missions/:missionId
3. Server validates completion, awards points, updates ledger
4. Points dashboard refreshed: GET /api/v1/rewards/points-history

Bulk claiming is supported via POST /api/v1/rewards/missions/claim-all.

Login Streaks

Tracked in LoginStreak — one row per (user, calendar day), unique on (userId, loginDate):

Current and longest streaks are derived by scanning consecutive loginDate rows — they are not stored columns.

Rules:

• A new row is written when the user logs in on a new calendar day (UTC)
• The current streak is the run of consecutive loginDate rows ending today; a gap resets it
• Bonus points scale with streak length: 5 × currentStreak

Referral System

The referral system uses three-tier deep earnings:

Referral Codes

• Each user can generate a custom referral code via POST /api/v1/rewards/referral-code
• Codes are 4-12 alphanumeric characters, checked for uniqueness
• Custom codes cannot duplicate existing access keys or group codes
• Default code is the user's ID if no custom code is set

Referral Tree

GET /api/v1/rewards/referral-tree returns the user's downline tree — who they referred, who those users referred, and so on, with point earnings at each level.

Access Keys

Access keys are the gating mechanism for the beta. Users earn the ability to generate keys by accumulating points.

Key Lifecycle

enum KeyStatus {
  ACTIVE = 'ACTIVE',
  USED = 'USED',
  REVOKED = 'REVOKED',
  EXPIRED = 'EXPIRED',
}

Key Generation Flow

1. User reaches point threshold: GET /api/v1/rewards/access-keys/remaining shows available keys
2. User generates key: POST /api/v1/rewards/access-keys/generate (optionally with custom code)
3. Key is created as ACTIVE with a 30-day expiry
4. User shares the key with a friend
5. Friend signs up at /access-key using the key
6. Backend activates key, sets beta_access=1 cookie, records referral

Group Codes

Group codes (managed by admins) are bulk invitation codes that don't count against a user's key limit:

Group codes are used for promotional campaigns, waitlist batch releases, and partner invitations.

Challenges

Time-limited challenges are special missions with higher point rewards:

• Displayed via GET /api/v1/rewards/challenges
• Have start and end dates
• Examples: "Trade $1000 volume this week", "Refer 3 friends in March"
• Completed challenges award 100-500 points
• Challenges are separate from daily missions and tracked independently

Admin Access Key Management

Admins have full CRUD over access keys: