Skip to main content

Supply Referral

The supply referral system allows users to earn a portion of the protocol fees generated by liquidity suppliers they refer. When a supplier deposits assets using your referral ID, you earn fees proportional to interest paid over time.

How it works​

  1. Create a referral: Mint a SupplyReferral object for a specific margin pool with mint_supply_referral
  2. Referral ID: Suppliers include your referral ID when supplying liquidity with supply. The referral ID is optional; suppliers can supply without one, in which case the position's shares count toward the default referral described in Fee distribution
  3. Earn fees: As referred suppliers earn interest, a portion of protocol fees accrues to your referral
  4. Claim fees: Withdraw accumulated referral fees at any time with withdraw_referral_fees

The referral system uses a shares-based tracking mechanism. When a supplier deposits with your referral:

  • Your referral's shares increase proportionally to the supplier's position
  • As interest accrues and protocol fees are collected, your claimable fees (accumulated referral fees you have not yet withdrawn) grow
  • When a supplier withdraws, your referral's shares decrease accordingly

API​

Following are the functions for managing supply referrals. Each section describes what the function does, followed by its source from the deepbookv3 repository.

Click to open
Mint a SupplyReferral

Create a new supply referral for earning fees from referred suppliers. The function shares a new SupplyReferral object, records the caller as its owner, and returns its ID for suppliers to pass to supply. Each referral applies to the specific margin pool you mint it for.

Click to open
Supply with referral

Supply assets to a margin pool with an optional referral ID. When a referral ID is provided, the referrer earns a portion of protocol fees from the supplier's position.

Click to open
Withdraw referral fees

Withdraw accumulated referral fees. Only the address that minted the SupplyReferral, recorded in its owner field, can claim its fees. You can withdraw accumulated fees at any time.

Click to open
Query referral tracker

Query the current shares and unclaimed fees for a referral. Use this function to check how many shares a referral holds and how many fees it can claim with withdraw_referral_fees.

Events​

Following are the events emitted by the supply referral functions. Each section describes when the event is emitted, followed by the event struct from the deepbookv3 repository.

Click to open
SupplyReferralMinted

The system emits this event when you create a new supply referral.

Click to open
ReferralFeesClaimed

The system emits this event when the referral owner claims referral fees.

Fee distribution​

There is no separate referral spread parameter. Each margin pool sets a protocol spread, capped at 20% by the contract, that determines what portion of borrower interest the pool keeps as protocol fees instead of paying out to suppliers. The Mainnet SUI margin pool, for example, uses a 20% protocol spread.

Each time fees accrue, the pool splits them pool-wide in proportions that the contract fixes. Unlike the protocol spread, a pool does not configure these proportions:

  • Protocol: 1/4 of the accrued fees
  • Maintainer: 1/4 of the accrued fees
  • Referrals: the remaining 1/2, divided among referrals in proportion to the supply shares each one referred

The pool converts the referral half into a fees-per-share increase over its total supply shares, so a referral's claimable fees grow with the shares it referred relative to all shares in the pool. Shares supplied without a referral ID count toward a default referral (address 0x0) whose fees only the admin can withdraw with admin_withdraw_default_referral_fees. If the pool has no supply shares when fees accrue, the referral half goes to the maintainer and the protocol instead.

You can view the protocol spread for each margin pool in the Contract Information.