feat: referral dashboard and registering

[NeOMakinG]

Description

Implement the referral dashboard:

• Showing your first code on top
• Ability to create codes and copy/share them
• Under a flag to disable it for now
• Counts your referrals amounts (it wont be working if it's not locally until we deploy properly on AWS, updating railway would be a huge lift right now...)
• Counts your fees for the current period and total fees regardless of the current period

Issue (if applicable)

No issue

Risk

Low, under a flag and not activated yet

High Risk PRs Require 2 approvals

What protocols, transaction types, wallets or contract interactions might be affected by this PR?

Testing

• Launch the docker containers of the microservices
• Uncomment the local URLs of microservices in env.development
• Create a referral code
• Use the referral code with another accounts
• Do swaps with the other accounts
• See that your numbers did increase! Currently it's counting 10% of the fees we take for every swap, but this can change in the future

Engineering

Operations

• [ ] :checkered_flag: My feature is behind a flag and doesn't require operations testing (yet)

Screenshots (if applicable)

Summary by CodeRabbit

• New Features

  • Added referral program enabling users to create and share referral codes.
  • Referral dashboard with statistics on rewards, referrals, and code management.
  • Automatic referral code capture from URLs for tracking referred users.

• Bug Fixes

  • Enhanced order metadata in swap transactions with improved data structure.

• Navigation

  • Added Referral section to header navigation menu.
  • Improved Ramp feature route visibility.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai[bot]]

📝 Walkthrough

Walkthrough

This PR introduces a comprehensive referral system feature, including environment flags, UI components for code management and rewards tracking, hooks for data fetching and URL-based code capture, API integration with the user service, and translations. Additionally, it enhances swapper metadata to include per-swapper-specific fields and order identifiers.

Changes

Cohort / File(s)	Summary
Environment & Configuration .env, .env.development, src/config.ts, src/state/slices/preferencesSlice/preferencesSlice.ts	Added VITE_FEATURE_REFERRAL environment variable (default false) and integrated it into the feature flags configuration and Redux preferences slice.
Referral Type System src/lib/referral/types.ts, src/lib/user/types.ts	Introduced ReferralCode, ReferralStats, CreateReferralCodeRequest, CreateReferralCodeResponse types, and custom ReferralApiError error class; added optional referralCode field to GetOrCreateUserRequest.
Referral API Integration src/lib/referral/api.ts, src/hooks/useReferral/useReferral.tsx	Created referral API client with getReferralStatsByOwner and createReferralCode endpoints; added useReferral hook for data fetching and code creation mutations.
Referral Code Capture src/hooks/useReferralCapture/useReferralCapture.tsx, src/hooks/useUser/useUser.tsx	Implemented URL-based referral code capture and localStorage persistence; integrated referral code into user creation workflow.
Referral UI Components src/components/Referral/*, src/components/Referral/index.ts	Added comprehensive referral feature components: ReferralDashboard (main container), ReferralHeader, ReferralCodeCard, ReferralStatsCards, ReferralTabs, ReferralCodesTable, ReferralCodesManagementTable, CreateCodeCard.
Page Integration & Navigation src/pages/Referral/Referral.tsx, src/pages/Fox/FoxEcosystemPage.tsx, src/components/Layout/Header/Header.tsx, src/Routes/RoutesCommon.tsx	Added Referral page component; integrated ReferralDashboard into FoxEcosystemPage behind feature flag; added referral navigation button to Header; increased Ramp route priority.
App-Level Integration src/App.tsx	Initialized useReferralCapture hook at app root to capture referral codes from URL on mount and route changes.
Translations src/assets/translations/en/main.json	Added comprehensive translation keys for referral feature including descriptions, action labels, statuses, and navigation entry.
Swapper Metadata Enhancement packages/swapper/src/types.ts, packages/swapper/src/swappers/PortalsSwapper/getPortalsTradeQuote/getPortalsTradeQuote.ts, src/lib/tradeExecution.ts	Added orderId field to TradeQuoteStep; added cowswapQuoteSpecific to SwapperSpecificMetadata; augmented Portals trade quote with orderId from order response; propagated swapper-specific metadata fields in trade execution.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25–35 minutes

• Key areas requiring attention:
  • The useReferral hook's React Query integration and error handling, particularly the conditional query execution based on ownerAddress and feature flags
  • The referral code capture mechanism in useReferralCapture and its integration into the App lifecycle; ensure localStorage error handling is robust
  • The swapper metadata additions (orderId, cowswapQuoteSpecific) and their propagation through tradeExecution; verify backward compatibility
  • Integration points where referralCode is passed to the user creation API; ensure validation and error handling
  • Feature flag guarding in Header and FoxEcosystemPage to confirm proper conditional rendering

Possibly related PRs

• shapeshift/web#11281: Modifies Portals swapper trade-quote metadata for cross-chain data; this PR adds orderId to the same metadata structure.
• shapeshift/web#11261: Adds optional metadata fields to TradeQuoteStep in packages/swapper/src/types.ts, similar to this PR's orderId and cowswapQuoteSpecific additions.
• shapeshift/web#11016: Modifies swapper metadata and tradeExecution metadata propagation for per-swapper-specific fields, directly related to this PR's swapper enhancements.

Suggested reviewers

• gomesalexandre
• premiumjibles
• 0xApotheosis

Poem

🐰 A shiny referral path appears,
With codes and stats to bring good cheer,
From URL to local store,
Swapper metadata galore!
We hop through features, clean and clear. ✨

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'feat: referral dashboard and registering' accurately summarizes the main changes: implementing a referral dashboard feature with code creation/registration functionality.

✨ Finishing touches

• [ ] 📝 Generate docstrings

🧪 Generate unit tests (beta)

• [ ] Create PR with unit tests
• [ ] Post copyable unit tests in a comment
• [ ] Commit unit tests in branch referral-dashboard

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[NeOMakinG]

Switching to draft until we know how we will distribute amount, focusing on other priorities