Skip to content

Instantly share code, notes, and snippets.

@Aboudjem

Aboudjem/25-referrals.md

Last active March 30, 2026 08:00
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save Aboudjem/7e41875574516416d03d14b9eccaa967 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save Aboudjem/7e41875574516416d03d14b9eccaa967 to your computer and use it in GitHub Desktop.
Download ZIP
Integra PRD: 25-referrals
Raw
25-referrals.md

Referrals & Points

Owner: Kalki | Ship: Week 3 | Est: 0.5 day | Chain: integra-testnet-1 (EVM 26218) URL: referrals.integralayer.com

Overview

On-chain referral system where users generate unique invite links, share them across social channels, and earn 10% of their referee's XP permanently. Referral relationships are recorded on-chain for full transparency and auditability. A competitive leaderboard ranks top inviters, turning power users into ecosystem evangelists. This is the primary viral growth loop for testnet adoption.

Features

  • Unique Invite Links — Each wallet gets a short-code referral link tied to their address, usable across all ecosystem dApps
  • On-Chain Attribution — Referee-to-referrer mapping stored in contract state, immutable and publicly verifiable
  • 10% Passive XP Share — Referrer earns 10% of all XP their referee accumulates across every ecosystem dApp, forever
  • Signup Bonus — Both referrer (+50 XP) and referee (+100 XP) receive a one-time bonus on successful registration
  • Social Share Buttons — One-click sharing to Twitter and Telegram with pre-filled templates mentioning @IntegraLayer
  • Referral Leaderboard — Public ranking of top inviters by invite count and total XP earned from referrals
  • Referral Dashboard — Personal stats page showing invite count, XP earned from referrals, and referral tree
  • Anti-Abuse Guards — No self-referral, one referrer per address, sybil-resistant claim gating
  • Milestone Badges — Achievement badges at 10, 50, and 100 successful referrals
  • Ecosystem-Wide Onboarding — Referral link works as the entry point to any dApp in the ecosystem, not just the referral page
  • Share Templates — Pre-written copy for Twitter ("I'm exploring the @IntegraLayer testnet and earning XP. Join me and we both get bonus points: [link]") and Telegram

Functions

  • generateLink(referrer) — Creates a unique short-code referral link for the caller's address
  • registerReferral(referee, referrer) — Records the referral relationship on-chain (called once on referee signup)
  • claimBonus(referee) — Referee claims signup bonus, which also triggers the referrer's bonus
  • getReferrer(referee) — Returns the referrer address for a given referee
  • getReferralCount(referrer) — Returns total successful referral count for an address
  • getLeaderboard() — Returns top referrers ranked by invite count or XP earned
  • getReferralXP(referrer) — Returns total passive XP accumulated from all referees

User Flow

  1. User connects via Web3Auth
  2. User sees their referral dashboard with unique link, invite count, and XP earned
  3. User copies their link or clicks one-click share (Twitter/Telegram)
  4. Friend clicks the link and lands on the ecosystem signup page
  5. Friend signs up and is attributed to the referrer on-chain
  6. Both parties receive their one-time XP bonus
  7. Referrer passively earns 10% of referee's ongoing XP from all ecosystem activity
  8. User checks the leaderboard to see their ranking among top inviters

Deliverables

  • Referrals smart contract with on-chain referee-referrer mapping
  • Referral link generation and resolution service
  • Referral dashboard page (stats, referral tree, XP breakdown)
  • Leaderboard page (ranked by invite count and XP earned)
  • Social share buttons with pre-filled Twitter and Telegram templates
  • Anti-abuse validation (no self-referral, one referrer per address)
  • XP multiplier integration (10% passive share across all ecosystem dApps)
  • Milestone badge system (10/50/100 referrals)

Integration Points

  • Depends on: Web3Auth (@integra/web3auth-provider), XP system (all ecosystem dApps report XP)
  • Used by: All ecosystem dApps (referral link is the universal onboarding entry point)
  • Explorer: Integra Explorer (referral registrations visible as on-chain txs)

XP Rewards

Action Points
Referee signup bonus (one-time, for new user) +100 XP
Referrer bonus per successful invite +50 XP
Ongoing passive share of referee's XP +10%
Reach 10 successful referrals (milestone) +500 XP

Success Metrics

Metric Target
Unique referral links generated 5,000+
Successful referral signups 1,000+
Referral conversion rate (click to signup) >15%
Users with 10+ referrals 50+
% of new users arriving via referral link >30%
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment