[Audit] Multi-Level Referral Contract

[aguilar1x]

🎯 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 in referral.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 via set_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 in rewards.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 in verification.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_contract and resume_contract must 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

---

[KoxyG]

Hi Reviewer,

I’m interested in auditing the Multi-Level Referral Smart Contract. With my experience in the Stellar ecosystem and Soroban, I’m confident in my ability to help ensure the contract functions securely and as intended.

I will focus on:

Referral System: Ensuring correct commission routing and preventing issues like self-referrals.
User Levels: Verifying that users progress correctly through levels based on referrals and rewards.
Reward Management: Testing claim functions and ensuring no double claims.
Verification: Checking that identity proofs are handled securely and that state transitions are correct.
Admin Controls: Ensuring only authorized users can change key settings.
Security: Preventing replay attacks and ensuring sensitive data is stored securely.
I’ll perform thorough testing, including user registration, reward claims, and verifying that the contract behaves as expected in different scenarios.

Looking forward to working on this project.

[aguilar1x]

Hi, the issue has been assigned to you, you can start working on it now. You have to report your progress in less than 2 days, this in order to be aware that the contributor is developing the issue.

If you have any questions, don't hesitate to ask! 🚀

@KoxyG

[aguilar1x]

Any updates?

[KoxyG]

I am working on it.

[Nathy-bajo]

@KoxyG @aguilar1x Let me take a stab at this?

[KoxyG]

@KoxyG @aguilar1x Let me take a stab at this?

I am on it.

[KoxyG]

#122

[aguilar1x]

any updates?, otherwise I will have to unassign the issue

@KoxyG

[KoxyG]

#122

I already created an issue for this, where all issues will be updated and posted here. I will finish it by Sunday. @aguilar1x

[Nathy-bajo]

#122

I already created an issue for this, where all issues will be updated and posted here. I will finish it by Sunday. @aguilar1x

For what reason?

[KoxyG]

Audit done #123

@aguilar1x