[Airdrop P2] Referral system

[realproject7]

Parent: #877
Depends on: #878

Scope

Complete referral system: code generation (with Farcaster username option), registration (via URL + manual input), and story share integration.

Referral Code

POST /api/airdrop/referral-code

Generate or retrieve referral code for connected wallet.

• Default: 8-char nanoid → store in pl_referral_codes
• Farcaster username option: If request includes useFarcasterUsername: true:
  • Verify wallet owns a Farcaster account (check users table for matching FID)
  • Set code = username, is_farcaster_username = true
  • Reject if username already taken as a code by another wallet
• Return existing code if already generated (immutable — cannot change once set)

Referral Registration

POST /api/airdrop/register-referral

Record referral relationship.

• Called when user connects wallet with a ref code (from URL param or manual input)
• Lookup referrer by code in pl_referral_codes
• Store in pl_referrals (referrer_address, referred_address, referral_code)
• Reject if referred address already has a referrer (one referrer per wallet, first-come)
• No retroactive points — referral only applies to future buy-points

Client-Side

• Global useReferralCapture hook (root layout or provider):
  • On any page load, read ?ref= query param
  • Store in localStorage if present
  • On wallet connect, submit stored ref code via register-referral API
  • Works on /airdrop, /story/*, and any other page
• Manual input on /airdrop page:
  • "Who referred you?" input field
  • Only visible when user has no referrer set
  • Non-editable once submitted
  • Shows "Referred by: @username" after set

Story Share Integration

• Modify existing story share button to append ?ref=CODE when user has a referral code
• Example: plotlink.xyz/story/48?ref=project7
• Works on all story pages (/story/[id])

Files

• src/app/api/airdrop/referral-code/route.ts
• src/app/api/airdrop/register-referral/route.ts
• Add: useReferralCapture hook or root layout effect
• Modify: story share button component (append ?ref=CODE)

Acceptance Criteria

• Referral code generated (nanoid) and retrievable
• Farcaster username can be used as code (verified via FID ownership)
• Code is immutable once set
• ?ref= captured on any PlotLink page via global hook → localStorage
• Referral registered on wallet connect
• Manual "Who referred you?" input works (one-time, non-editable)
• Rejects duplicate referral (one referrer per wallet)
• No retroactive points for past buys
• Story share URLs include ?ref=CODE when user has a code