[GF-23] [FRONTEND] Growth & Retention (Referral Program, Points System, Leaderboard)

[wumibals]

Overview

⚠️ Depends on: #42 (GF-09 — Wallet Integration) — referrals and leaderboard require a connected wallet address for attribution and display.

Build growth and retention features: a referral program, a points/loyalty system for early depositors, and an opt-in leaderboard. These are standard in comparable DeFi protocol launches (Pendle, EigenLayer, Kelp DAO) and are effective at driving early TVL and word-of-mouth growth.

Problem

YieldLadder has no mechanism to reward early depositors or incentivise referral growth. The protocol has strong fundamentals but no retention hook beyond yield — and yield alone is insufficient for early-stage protocol growth when awareness is low.

Proposed Solution

1. Referral Program (/referral page)

Referral link generation:
Each connected wallet gets a unique referral URL: https://yieldladder.dev/r/<short_code> where short_code is derived from the wallet address (e.g. first 8 chars of the base32 address).

The referral link pre-populates a cookie or localStorage entry when visited. When the referred user makes their first deposit (via the deposit flow in GF-13), the referrer's address is stored alongside the deposit event.

Referral tracking page:
Show the connected user's:

• Unique referral link with a Copy button and a Share on Twitter intent
• Number of referred users (wallets that deposited using their link)
• Total USDC deposited by referred users
• Referral reward earned (if a reward structure is defined — see below)

Referral reward structure (team to define exact terms; implement the display):
Suggested: referrer earns a one-time bonus of 0.50% of the referee's first deposit amount, credited as additional share-units in the same tier as the referee's deposit. Display the unclaimed reward amount on the referral page with a Claim button.

2. Points / Loyalty System

Award points to wallets based on:

• Deposit amount: 1 point per 1 USDC deposited
• Lock duration bonus: Flex = 1×, L3 = 1.05×, L6 = 1.15×, L12 = 1.40× (mirrors lock multipliers)
• Early depositor bonus: 2× points for deposits made within the first 30 days of mainnet launch
• Harvest caller bonus: 50 points per harvest triggered

Display on /portfolio:

• User's total points
• Points breakdown by category
• A brief note: Points may be redeemable for protocol benefits in a future governance vote (keeps optionality without over-promising)

3. Leaderboard (/leaderboard page, opt-in)

An opt-in leaderboard showing the top depositors per tier. Users opt in by signing a message with their wallet (no personal data required — just their address and consent to appear publicly).

Display:

• Rank, truncated address, tier, shares held, points earned
• Top 50 per tier, with the connected user's rank shown even if outside top 50

Acceptance Criteria

• /referral page exists and generates a unique referral URL per connected wallet
• Referral link can be copied to clipboard and shared via a Twitter intent
• Referred user's first deposit is attributed to the referrer (via localStorage or cookie)
• Referral stats page shows referred count and total referred deposits
• Points are calculated and displayed on the /portfolio page
• Points formula matches the deposit amount × tier bonus × early depositor status
• Harvest caller bonus is awarded and visible
• /leaderboard page requires opt-in (wallet signature) before showing the user's address publicly
• Leaderboard shows top 50 per tier and the connected user's rank
• All features degrade gracefully if wallet is not connected (show connect prompt)