Memo-based referral / attribution system

[OluRemiFour]

Close: #94

Summary

I have implemented a complete, fully functional, high-performance Memo-Based Referral and Attribution System for TurboLong. The implementation spans the frontend app and a dedicated referrals backend Worker utilizing Cloudflare D1.

No new smart contracts were needed; referrals are attributed via standard text memos attached to token approval / position opening transactions on the Stellar Network, then captured by a lightweight off-chain indexer.

🛠️ Components Implemented

1. Backend: integrations/referrals/ Worker
   A modular, high-efficiency Cloudflare Worker containing:

D1 Database Schema (src/schema.sql):
referral_codes: maps owner addresses to their generated referral codes.
referral_events: stores tracked deposit transaction records (with unique transaction hashes to prevent double-counting).
REST API Routes (src/index.ts):
POST /referrals/register: registers/verifies code owned by a wallet address.
GET /referrals/code: returns the code associated with an address.
GET /referrals/stats: computes aggregate stats (total referrals, unique depositors), pool breakdowns, and lists recent referred activity.
Cron Indexer (scheduled):
Automatically runs every 15 minutes.
Fetches the latest transactions on the tracked Blend pool contract addresses from the Stellar Horizon API.
Filters transactions containing ref: text memos, validates the code, and records the deposit event on D1.
2. Frontend: index.html & style.css
Navigation Toggles: Added "Refer & Earn" navigation tabs in the desktop top-nav and the mobile sidebar.
Referral Dashboard View (#referral-view):
Gates stats behind wallet connection.
Generates and displays a shareable referral code and link (complete with copy-to-clipboard buttons).
Premium-styled stats cards showing Total Referrals, Unique Depositors, and Active Referrals.
Detailed grid layouts displaying Breakdown by Pool tables and a live Recent Referrals timeline.
Premium HSL dark-theme styling matching TurboLong's elegant visual system.
3. Frontend Logic: main.ts & blend.ts
URL Parameter Extraction: Instantly captures ?ref= from search parameters on application load and stores it securely in sessionStorage as a pending referral.
Deterministic Code Generation: Generates unique, memorable referral codes (REF-<FIRST_4_CHARS>-<RAND_HEX>) for connecting users.
Memo Injection: Updated the protocol's token approval step (buildApproveXdr) to check sessionStorage and append the pending referral code as a standard text memo before transaction signing and submission.

Related Issue

Closes #94

Checks

• I read the contribution guide.
• I kept this pull request scoped to the linked issue.
• I ran the relevant local checks or explained why they were skipped.
• For Drips wave issues, I claimed the issue before opening this pull request.

Notes for Reviewers

[drips-wave]

@OluRemiFour Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

[OluRemiFour]

Done, Close: #200