CeloRefer SDK

A TypeScript SDK for interacting with the CeloRefer referral system on the Celo blockchain.

📚 Full Documentation: https://celoref.mintlify.app/api-reference/introduction

Overview

CeloRefer is a decentralized referral system that allows users to earn rewards by referring others to participate in DeFi activities. This SDK provides a simple interface for integrating CeloRefer functionality into your applications.

Key Highlights

• Mobile-First: SocialConnect integration allows users to join using phone numbers instead of complex wallet addresses
• Type-Safe: Built with TypeScript for excellent IDE support and type safety
• Production Ready: 22+ passing tests, deployed on Celo Sepolia testnet
• Comprehensive: 70+ methods covering all referral, quest, NFT, and reward operations

Features

• User Management - Registration with referral codes and genesis user setup
• Badge System - Dynamic tier system (Bronze, Silver, Gold, Platinum) based on referrals
• Dynamic Rewards - Multi-level referral rewards with tier-based multipliers
• Quest System - Gamified challenges with rewards for completing milestones
• Seasonal Competitions - Time-based leaderboards with prize pools
• Reputation NFTs - On-chain achievement badges with dynamic metadata
• SocialConnect Integration - Phone number-based registration for mobile users
• Partner Integration - DApp subscription and authorization system
• Leaderboard - Real-time ranking and statistics
• Token Operations - cUSD balance checking and staking
• Referral Links - Easy link generation for sharing

Installation

npm install celorefer-sdk viem

Or with other package managers:

yarn add celorefer-sdk viem
pnpm add celorefer-sdk viem
bun add celorefer-sdk viem

Usage

Initialize the SDK

import { CeloReferSDK } from 'celorefer-sdk';
import { createWalletClient, http } from 'viem';
import { celoAlfajores } from 'viem/chains';

// Create wallet client
const walletClient = createWalletClient({
  chain: celoAlfajores,
  transport: http(),
  account: yourAccount, // from privateKeyToAccount or browser wallet
});

// Initialize SDK (creates public client internally)
const sdk = CeloReferSDK.create(celoAlfajores, walletClient);

Register a New User

// Register with a referral code
const txHash = await sdk.registerUser('REF123ABC');
console.log('Registration transaction hash:', txHash);

// Register as genesis user (first user)
const genesisTxHash = await sdk.registerGenesisUser('MYCODE');
console.log('Genesis registration transaction hash:', genesisTxHash);

Get User Information

// Get user information
const userInfo = await sdk.getUserInfo('0x123...');
console.log('User info:', userInfo);

// Get badge tier
const badgeTier = await sdk.getBadgeTier('0x123...');
console.log('Badge tier:', badgeTier);

// Get referral code
const referralCode = await sdk.getReferralCode('0x123...');
console.log('Referral code:', referralCode);

SocialConnect Integration

CeloRefer integrates with Celo's SocialConnect protocol to enable phone number-based onboarding:

// Users can register and participate using their phone numbers
// The SDK handles the phone-to-address mapping seamlessly

// Example: Register user with phone number (via SocialConnect)
// The system links phone number to blockchain address automatically
const phoneNumber = '+1234567890';
// SocialConnect attestation happens in the background
// User gets a blockchain address mapped to their phone number

// Then register normally with referral code
const txHash = await sdk.registerUser('REF123ABC');

// Benefits:
// - No need to remember complex wallet addresses
// - Mobile-native experience
// - Easy user recovery via phone number
// - Seamless social sharing of referral links

Staking Operations

// Stake cUSD with referral registration
const stakeTxHash = await sdk.stake(1000000000000000000n, 'REF123ABC'); // 1 cUSD
console.log('Stake transaction hash:', stakeTxHash);

// Stake with genesis registration
const genesisStakeTxHash = await sdk.stakeWithGenesis(1000000000000000000n, 'MYCODE');
console.log('Genesis stake transaction hash:', genesisStakeTxHash);

Quest System

// List all active quests
const quests = await sdk.listActiveQuests();
console.log('Active quests:', quests);

// Get quest details
const quest = await sdk.getQuest(1);
console.log('Quest:', quest.name, quest.targetReferrals, quest.rewardAmount);

// Check user's progress on a quest
const progress = await sdk.getUserQuestProgress(userAddress, 1);
console.log('Progress:', progress.progress, 'Completed:', progress.completed);

// Claim quest reward
if (progress.completed) {
  const txHash = await sdk.claimQuestReward(1);
  console.log('Claimed quest reward:', txHash);
}

Seasonal Competitions

// Get current season
const season = await sdk.getCurrentSeason();
console.log('Prize pool:', season.totalPrizePool);
console.log('Winners count:', season.winnersCount);

// Get user's season stats
const seasonId = await sdk.getCurrentSeasonId();
const userStats = await sdk.getSeasonUserStats(seasonId, userAddress);
console.log('Season referrals:', userStats.referrals);
console.log('Season earnings:', userStats.earnings);

// List all seasons
const allSeasons = await sdk.listSeasons();
console.log('Total seasons:', allSeasons.length);

Reputation NFT System

// Mint reputation NFT
const txHash = await sdk.mintReputationNFT(userAddress);
console.log('NFT minted:', txHash);

// Check if user has NFT
const hasNFT = await sdk.hasReputationNFT(userAddress);
console.log('Has NFT:', hasNFT);

// Get NFT data
if (hasNFT) {
  const tokenId = await sdk.getTokenIdByUser(userAddress);
  const nftData = await sdk.getReputationNFTData(userAddress);
  console.log('NFT Tier:', nftData.tier);
  console.log('NFT Referrals:', nftData.referrals);
  console.log('NFT Earnings:', nftData.earnings);
  
  // Get token URI
  const tokenURI = await sdk.getNFTTokenURI(tokenId);
  console.log('Token URI:', tokenURI);
}

// Generate badge SVG
const svg = sdk.generateBadgeSVG(tier, referrals, earnings, rank);
// Use this SVG in your UI

Partner Integration (for DApps)

// Check if authorized partner
const isPartner = await sdk.isAuthorizedPartner(partnerAddress);

// Record user action and distribute rewards
if (isPartner) {
  const actionValue = 1000000000000000000n; // 1 cUSD
  const txHash = await sdk.recordAction(userAddress, actionValue);
  console.log('Action recorded:', txHash);
}

// Get partner subscription details
const subscription = await sdk.getPartnerSubscription(partnerAddress);
console.log('Subscription tier:', subscription.tier);
console.log('Expiry:', subscription.expiryTime);

// Get platform fee
const fee = await sdk.getPlatformFee();
console.log('Platform fee:', fee / 100, '%'); // Convert basis points to %

// Get treasury address
const treasury = await sdk.getTreasury();
console.log('Treasury:', treasury);

Dynamic Reward Rates

// Get user's reward rates (based on badge tier)
const rates = await sdk.getRewardRates(userAddress);
console.log('Level 1 rate:', sdk.bpsToPercentage(rates.level1Bps), '%');
console.log('Level 2 rate:', sdk.bpsToPercentage(rates.level2Bps), '%');

// Badge tiers get better rates:
// Bronze: 5% / 2%
// Silver: 6% / 2.5%
// Gold: 7% / 3%
// Platinum: 8% / 3.5%

Leaderboard

// Get top users (returns mock data for now)
const topUsers = await sdk.getTopUsers(10);
topUsers.forEach(user => {
  console.log(`Rank ${user.rank}: ${user.address}`);
  console.log(`Referrals: ${user.referralCount}, Earnings: ${user.totalEarnings}`);
});

// Get user's rank
const rank = await sdk.getUserRank(userAddress);
console.log('Your rank:', rank);

// Get leaderboard stats
const stats = await sdk.getLeaderboardStats();
console.log('Total users:', stats.totalUsers);
console.log('Total referrals:', stats.totalReferrals);

Utility Functions

// Generate referral link
const referralLink = sdk.generateReferralLink('REF123ABC');
console.log('Referral link:', referralLink);

// Get badge information
const badgeInfo = sdk.getBadgeInfo(2); // Gold badge
console.log('Badge info:', badgeInfo);

// Get contract statistics
const stats = await sdk.getContractStats();
console.log('Contract stats:', stats);

// Convert basis points to percentage
const percentage = sdk.bpsToPercentage(500n); // 5%

Deployed Contracts

Network: Celo Sepolia Testnet (Chain ID: 11142220)

| Contract | Address | |----------|----------| | CeloReferEnhanced | 0xCCAddAC9Ac91D548ada36684dB2b3796A0c7Ea73 | | ReputationNFT | 0xe667437aF0424Ee9cb983b755Ccccf218779E37b | | cUSD | 0xdE9e4C3ce781b4bA68120d6261cbad65ce0aB00b |

Block Explorer: https://alfajores.celoscan.io

Badge System

The CeloRefer system includes a tiered badge system based on referral count:

| Tier | Name | Threshold | Level 1 Rate | Level 2 Rate | |------|------|-----------|--------------|---------------| | 0 | Bronze | 0+ | 5% | 2% | | 1 | Silver | 5+ | 6% | 2.5% | | 2 | Gold | 15+ | 7% | 3% | | 3 | Platinum | 50+ | 8% | 3.5% |

Benefits by Tier:

• Bronze: Starting tier for new users
• Silver: Improved reward rates + quest access
• Gold: Premium features + priority support
• Platinum: Elite status + maximum benefits + exclusive perks

Reward Structure

Multi-Level Referral System:

• Level 1 (Direct Referrer): Dynamic rate based on badge tier (5-8%)
• Level 2 (Grandparent): Dynamic rate based on badge tier (2-3.5%)

Platform Fee: 15% (goes to treasury for sustainability)

Reward Distribution:

1. User performs action (e.g., stakes 100 cUSD)
2. Platform fee deducted (15 cUSD to treasury)
3. Remaining 85 cUSD distributed:
   • Direct referrer gets their tier rate (e.g., 5% = 4.25 cUSD)
   • Level 2 referrer gets their tier rate (e.g., 2% = 1.7 cUSD)
   • Rest goes to user's activity

API Reference

Core User Management

| Method | Description | Returns | |--------|-------------|----------| | create(chain, walletClient?) | Create SDK instance | CeloReferSDK | | getUserInfo(address) | Get complete user info | UserInfo | | getUserStats(address) | Get user statistics | UserStats | | getBadgeTier(address) | Get user's badge tier | BadgeTier (0-3) | | registerUser(code, account?) | Register with referral | tx hash | | registerGenesisUser(code, account?) | Register as genesis | tx hash | | getReferralCode(address) | Get referral code | string | | generateReferralLink(code) | Create referral URL | string | | getBadgeInfo(tier) | Get badge details | badge info |

Quest System

| Method | Description | Returns | |--------|-------------|----------| | getQuest(questId) | Get quest details | Quest | | getUserQuestProgress(address, questId) | Get progress | UserQuestProgress | | claimQuestReward(questId) | Claim reward | tx hash | | listActiveQuests() | Get all active quests | Quest[] | | getQuestCount() | Get total quest count | number |

Seasonal Competitions

| Method | Description | Returns | |--------|-------------|----------| | getCurrentSeason() | Get active season | Season | | getCurrentSeasonId() | Get season ID | number | | getSeason(seasonId) | Get season by ID | Season | | getSeasonCount() | Get total seasons | number | | listSeasons() | Get all seasons | Season[] | | getSeasonUserStats(seasonId, address) | Get user season stats | SeasonUserStats |

Reputation NFT System

| Method | Description | Returns | |--------|-------------|----------| | mintReputationNFT(address) | Mint NFT | tx hash | | hasReputationNFT(address) | Check ownership | boolean | | getTokenIdByUser(address) | Get token ID | number | | getNFTTokenURI(tokenId) | Get metadata URI | string | | getNFTTotalSupply() | Get total supply | number | | getReputationNFTData(address) | Get NFT metadata | ReputationNFTData | | generateBadgeSVG(tier, refs, earnings, rank) | Create SVG badge | data URI |

Partner Integration

| Method | Description | Returns | |--------|-------------|----------| | recordAction(address, value) | Record user action | tx hash | | isAuthorizedPartner(address) | Check authorization | boolean | | getPartnerSubscription(address) | Get subscription | PartnerSubscription | | getPlatformFee() | Get fee in bps | number | | getTreasury() | Get treasury address | Address |

Rewards & Tokens

| Method | Description | Returns | |--------|-------------|----------| | getRewardRates(address) | Get dynamic rates | RewardRates | | bpsToPercentage(bps) | Convert to % | number | | getCUSDBalance(address) | Get cUSD balance | bigint | | approveCUSDCustom(amount, spender, account?) | Approve spending | tx hash | | stake(amount, code?, account?) | Stake cUSD | tx hash | | stakeWithGenesis(amount, code, account?) | Stake as genesis | tx hash | | getUserStakeInfo(address) | Get stake info | UserStakeInfo | | getContractStats() | Get contract stats | ContractStats |

Leaderboard

| Method | Description | Returns | |--------|-------------|----------| | getTopUsers(limit?) | Get top users | LeaderboardUser[] | | getUserRank(address) | Get user's rank | number | | getLeaderboardStats() | Get aggregate stats | LeaderboardStats |

Documentation

For comprehensive API documentation, tutorials, and guides, visit:

📚 Official Documentation: https://celoref.mintlify.app/api-reference/introduction

The documentation includes:

• Detailed API reference for all 70+ methods
• Step-by-step integration guides
• TypeScript type definitions
• Real-world usage examples
• Best practices and patterns
• Troubleshooting guides

Quick Links

• Getting Started
• User Management API
• Quest System Guide
• NFT Integration
• Partner Integration

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contact

For support or questions, please open an issue on the GitHub repository.