feat: referral dashboard

[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

• 🏁 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]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch feat/referral-dashboard-rebased

---

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]

🧪 QA Report

CI Status: ❌ FAILING

Failed step: Lint (Static checks)

PR: Referral dashboard

This is a larger feature PR (~2 months old). Please:

1. Rebase on latest develop (likely many conflicts)
2. Fix any lint/type errors
3. Re-request QA once CI passes

Once CI Passes

Testing checklist:

• Referral dashboard loads correctly
• Referral links generated correctly
• Stats display accurately

[NeOMakinG]

✅ Code Review — Referral Dashboard

Branch: feat/referral-dashboard-rebased
CI: ✅ Passing

Summary

Clean implementation of the referral dashboard feature. Well-structured code with proper separation of concerns.

What's Good ✅

1. Type safety — Clean TypeScript types in lib/referral/types.ts
2. Error handling — Proper API error handling with ReferralApiError class and timeout
3. Loading states — Skeleton loaders throughout the UI for better UX
4. Feature gating — Double-gated behind VITE_FEATURE_REFERRAL + WebServices flag
5. Translations — All 32 translation keys properly added
6. UI/UX — Share to X, copy link, random code generation all implemented

Code Review Notes

• useReferral hook properly uses skipToken when wallet not connected
• queryClient.invalidateQueries correctly refreshes stats after code creation
• Tab state properly isolated within component
• Date range calculation for current month rewards looks correct

QA Status

⚠️ Browser testing unavailable — Browser control service not responding. Full UI testing deferred.

Recommendations:

1. This is safe to merge behind the flag
2. Full QA testing recommended when microservices are deployed
3. Consider adding rate limiting for code creation endpoint

---

🤖 Code Review by Claude Code

[NeOMakinG]

📋 Code Review — Referral Dashboard

Status: Code reviewed, CI pending

Architecture

• ✅ Clean implementation with proper feature flag (VITE_FEATURE_REFERRAL)
• ✅ Well-structured hooks (useReferral, useReferralCapture)
• ✅ Proper API integration with error handling
• ✅ Good UX with loading states, skeletons, and toast notifications
• ✅ Referral code capture from URL params with localStorage persistence
• ✅ Integration with user registration flow

Testing Limitations

• ⚠️ Full testing requires USER_SERVER_URL microservices (not deployed to Railway yet)
• ⚠️ Stats counting only works with local Docker containers per PR description
• ℹ️ Feature is disabled in production (VITE_FEATURE_REFERRAL=false in .env)

Minor Notes

• The generateRandomCode() function is duplicated in both ReferralDashboard.tsx and Referral.tsx — could be extracted to a shared utility
• Consider adding input validation for custom codes (length, allowed characters)

Risk: Low — behind feature flag, disabled in production

Awaiting CI completion before final approval.

---

🤖 Reviewed by Claude Code

[NeOMakinG]

QA Automation Report

Status: ❌ Unable to Test

Issue Found:
The app crashes on load with the following error:

Error: assertIsChainReference: unsupported ChainReference: 1514
  at packages/caip/src/typeGuards.ts:42:53
  at fromAccountId (packages/caip/src/accountId/accountId.ts:38:3)
  at src/state/slices/common-selectors.ts:47:9

This error occurs in the AppProvider component, causing React to fall back to the ErrorBoundary and display 'Oops! Something went wrong'.

Steps to Reproduce:

1. Checkout branch feat/referral-dashboard-rebased
2. Run yarn dev
3. Navigate to http://localhost:3000

Possible Cause:
The ChainReference 1514 doesn't appear to be registered in the CAIP chain reference list. This may be related to new chain support that wasn't fully integrated.

Recommendation:
Please verify that chain 1514 is properly registered in the CAIP package before retesting.

---

Automated QA run on 2026-03-14 18:01

[NeOMakinG]

⚠️ QA Testing Blocked

Blocker: The app crashes on load with error:

assertIsChainReference: unsupported ChainReference: 1514

This prevents testing the referral dashboard feature. The error appears in the browser console immediately on page load.

Tested: March 15, 2026
Branch: feat/referral-dashboard-rebased
Steps: yarn install → yarn dev → Navigate to localhost:3000

Once this is fixed, I can re-run QA testing.