Skip to main content

Referral System

Bunni v2 incorporates a robust referral system that incentivizes users to bring liquidity to the protocol. This system is built into the core of the BunniToken contract and provides a mechanism for tracking referrals and distributing rewards.

Overview​

The referral system in Bunni v2 allows users to be associated with a referrer when they provide liquidity. Referrers earn rewards based on the amount of liquidity their referrals contribute to the pool. This system is designed to be gas-efficient and seamlessly integrated with other features of the protocol.

Key Components​

  1. Referrer ID: Each referrer is identified by a uint24 ID, allowing for up to 8,388,607 unique referrers.
  2. Referrer Score: The sum of all balances of accounts that have the referrer as their referrer. Specific to each Bunni pool.
  3. Referral Rewards: Rewards distributed to referrers, denominated in both token0 and token1 of the pool.
  4. Reward Distribution: A mechanism for distributing rewards to referrers based on their score and the fees generated by the pool.

How It Works​

Referrer Assignment​

When a user provides liquidity to a Bunni v2 pool, they can specify a referrer ID. The referrer's score will increase as a result of the liquidity addition. Each user is associated with a single referrer, and if the user adds liquidity using a different referrer ID then the score will be transferred to the new referrer.

The address associated with each referrer ID is set by governance. There will be an approval process for onboarding referrers.

Referrer Score Calculation​

The referrer's score is updated whenever LP tokens are transferred, minted, or burned. The score represents the total amount of liquidity provided by all users associated with that referrer.

Reward Distribution​

Rewards are distributed to referrers based on their score. A portion of protocol fees, which are taken from swap fees, is distributed to referrers after each swap. The portion of protocol fees distributed this way is determined by governance.

The distribution process is triggered by calling the BunniToken.distributeReferralRewards function, which is typically called by the hook contract after a swap but can be called by anyone to distribute extra rewards to referrers.

Claiming Rewards​

Referrers can claim their accumulated rewards by calling the BunniToken.claimReferralRewards function on the Bunni pool's BunniToken contract. This function calculates the unclaimed rewards for both token0 and token1 and transfers them to the referrer.

Gas Efficiency​

The referral system is designed to be gas-efficient:

  1. Referrer IDs are stored in the upper 24 bits of the balance slot of each user, so no extra storage is used.
  2. Rewards are accumulated over time and only transferred when claimed, reducing gas costs for frequent updates.
  3. The system uses assembly for low-level storage operations, further optimizing gas usage.

Integration with Other Features​

The referral system is integrated with other Bunni v2 features:

  1. Liquidity Provision: Referrer IDs are specified when adding liquidity.
  2. Token Transfers: Referrer scores are updated on all BunniToken transfers.
  3. Swaps: A portion of protocol fees (generated from swap fees) can be allocated to referral rewards.

Important Considerations​

  1. Maximum Referrer ID: The maximum valid referrer ID is 8,388,607 (2^23 - 1). Any ID above this will be treated as 0 (no referrer).
  2. Reward Calculation: Rewards are calculated based on the referrer's score relative to the total supply of BunniTokens.

Usage Example​

Here's an example of how a user might interact with the referral system:

  1. Alice provides liquidity to a Bunni v2 pool, specifying Bob's referrer ID.
  2. The pool generates fees from swaps.
  3. The hook contract calls distributeReferralRewards to allocate a portion of these fees to referrers.
  4. Bob calls claimReferralRewards to receive his share of the rewards based on Alice's (and any other referred users') liquidity.

By implementing this referral system, Bunni v2 creates an incentive structure that can help grow liquidity in the protocol while rewarding users who bring in new liquidity providers.