feat: referral

[notJoon]

Description

This PR introduces a referral system that allows authorized contracts to manage referral relationships between addresses. The system enables tracking and managing referrer-referee relationships.

Structure

classDiagram
	class ReferralKeeper {
		<<interface>>
		+register(addr, refAddr std.Address)
		+update(addr, newAddr std.Address)
		+remove(addr std.Address)
		+has(addr std.Address)
		+get(addr std.Address)
	}
	class Keeper {
		-store *avl.Tree
		+register(addr, refAddr std.Address)
		+update(addr, newRefAddr std.Address)
		+remove(addr std.Address)
		+has(addr std.Address)
		+get(addr std.Address)
	}
	class Referral {
		-keeper ReferralKeeper
		+Register(addr, refAddr std.Address)
		+Update(addr, newRefAddr std.Address)
		+Remove(addr std.Address)
		+Has(addr std.Address)
		+Get(addr std.Address)
	}
	
	Referral --> ReferralKeeper : uses
	Keeper ..|> ReferralKeeper : implements

Loading

Implementation Details

The referral system consists of the following components:

1. Core Components:

   • ReferralKeeper interface: Defines the fundamental operations for referral management
   • AVL Tree-based storage: Efficiently stores referral relationships

2. Main Operations:

   • Register: Create new referral relationships
   • Update: Modify existing referrals
   • Remove: Delete referral relationships
   • Query (Get, Has): Check existence and get referral information

3. Security:

   • Strict caller validation through a lookup table
   • Address format validation
   • Zero address handling for removal operations

Permissions

Only the following addresses can modify referral data:

• Governance contracts
• Router
• Position
• Staker

[onlyhyde]

Referral Contract requires a book that manages Caller Address -> Referral Address.

[dongwon8247]

One question: Thinking about preventing people from registering their other wallets as a referral, to manipulate the system (getting more points). We only use this referral contract to know the referral-referee relationships and point calculation/prevention will be on our back-end side, correct?

[notJoon]

One question: Thinking about preventing people from registering their other wallets as a referral, to manipulate the system (getting more points). We only use this referral contract to know the referral-referee relationships and point calculation/prevention will be on our back-end side, correct?

@dongwon8247 Yes, that's correct. This package only stores referral-referee relationships and I believe that's how it should be.

[notJoon]

@onlyhyde

Referral Contract requires a book that manages Caller Address -> Referral Address.

The store field of the keeper handles that role.

[sonarqubecloud]

Quality Gate passed

Issues
4 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[dongwon8247]

Well done. LGTM