[Audit] Multi-Level Referral Contract #100
Description
🎯 Objective
Audit the Multi-Level Referral Smart Contract, a Soroban-based system designed to manage multi-tier referrals, dynamic user levels, KYC-based verification, and commission-based rewards. The contract supports automatic distribution, user progression, and system-wide tracking, while embedding strong security controls to prevent abuse and ensure integrity.
🏗 Contract Structure
referral-contract/src/
lib.rs // Contract entry and dispatcher
admin.rs // Admin setup and control logic
referral.rs // Core referral tracking (3 levels)
rewards.rs // Commission and reward management
verification.rs // KYC and verification workflow
level.rs // Tiered user level logic
types.rs // Data models and enums
helpers.rs // Utility functions
test.rs // Unit tests🔍 Audit Scope by Component
1️⃣ Referral System
-
Core functions:
register_with_referral, internal tracking inreferral.rs -
Checks:
- Max depth of 3 levels strictly enforced
- Valid and verified referrer required
- Prevent registration loops or self-referral
- Accurate commission routing across referral tree
- Team size tracking correctly scoped by level
- Ensure no overwrites on re-registration attempts
2️⃣ User Levels & Progression
-
Core functions: logic in
level.rs, configured viaset_level_requirements -
Checks:
- Automatic level progression from Basic → Silver → Gold → Platinum
- Progression based on: direct referrals, team size, and total earned rewards
- No skipped levels or regression unless explicitly allowed
- Access to level-based benefits must reflect current level accurately
3️⃣ Reward Management
-
Core functions:
claim_rewards, distribution logic inrewards.rs -
Checks:
- Configurable tiered rates: Level 1 (5%), Level 2 (2%), Level 3 (1%)
- Milestone bonuses and reward caps enforced per referral
- Prevent double claims or outdated reward calculations
- Ensure atomic distribution: all or nothing
- Rewards must only be claimable by verified users
4️⃣ Verification System
-
Core functions:
submit_verification,get_verification_status, logic inverification.rs -
Checks:
- Identity proof must be attached and stored securely
- Only admins can approve verification status
- State transition (unverified → verified) must be irreversible unless by admin
- All user actions gated behind verification status where required
- Verify off-chain identity handling (hashes? signatures?) is secure and non-reversible
5️⃣ Admin Controls
-
Core functions:
initialize,set_reward_rates,set_level_requirements,pause_contract,resume_contract -
Checks:
- Admin-only access enforced for all configuration actions
pause_contractandresume_contractmust immediately disable/enable critical user operations- Admin address should be immutable post-initialization or strictly updatable via secure logic
- Validate that reward tokens are set correctly and only once (if immutable)
🔐 Security Considerations
-
Authorization: All sensitive functions must check sender authority
-
Replay/Duplication Prevention:
- No double reward claims
- No self-referral or circular trees
-
System Pause Mechanism:
- Must disable all user-initiated state mutations
-
KYC and Identity:
- Store identity proofs safely (off-chain links must be hashed/signed)
-
Testnet/Deployment Safety:
- Ensure initialization logic cannot be rerun
- Prevent contract configuration drift during deployment
📊 Data & Metrics Tracking
- Track total user count and user levels over time
- Record total commissions paid per level and per user
- Ensure analytics are non-blocking and cost-effective
- Confirm that tracking logic does not interfere with core flows
📋 Recommended Tests
- Register multiple users and trace reward propagation through 3 levels
- Validate incorrect referrals (unverified or nonexistent) are rejected
- Test reward claiming under caps, with multiple referrals, and paused contract state
- Simulate level upgrades with real referral volume and reward conditions
- Attempt unauthorized admin actions or verification bypasses
- Ensure identity proof is required and enforced before benefits apply
📌 Additional Notes
- Future feature: referral dashboards, cross-contract data sharing for loyalty systems
- Consider zero-knowledge-based KYC integrations for privacy
- Allow for dynamic reward token switching with security limits
- Explore protection against Sybil attacks with minimum stake or referral approval delay