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
2. Referral ID: Suppliers include your referral ID when supplying liquidity
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

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 grow
• When a supplier withdraws, your referral's shares decrease accordingly

API

Following are the functions for managing supply referrals.

<details> <summary>Mint a `SupplyReferral`</summary>

Create a new supply referral for earning fees from referred suppliers. The returned SupplyReferral object is transferable and can be used to claim accumulated fees.

<ImportContent source="packages/deepbook_margin/sources/margin_pool.move" mode="code" org="MystenLabs" repo="deepbookv3" fun="mint_supply_referral" />

</details> <details> <summary>Supply with referral</summary>

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.

<ImportContent source="packages/deepbook_margin/sources/margin_pool.move" mode="code" org="MystenLabs" repo="deepbookv3" fun="supply" />

</details> <details> <summary>Withdraw referral fees</summary>

Withdraw accumulated referral fees. Only the owner of the SupplyReferral object can claim its fees.

<ImportContent source="packages/deepbook_margin/sources/margin_pool.move" mode="code" org="MystenLabs" repo="deepbookv3" fun="withdraw_referral_fees" />

</details> <details> <summary>Query referral tracker</summary>

Query the current shares and unclaimed fees for a referral.

<ImportContent source="packages/deepbook_margin/sources/margin_pool/protocol_fees.move" mode="code" org="MystenLabs" repo="deepbookv3" fun="referral_tracker" />

</details>

Events

<details> <summary>`SupplyReferralMinted`</summary>

Emitted when a new supply referral is created.

<ImportContent source="packages/deepbook_margin/sources/margin_pool.move" mode="code" org="MystenLabs" repo="deepbookv3" struct="SupplyReferralMinted" />

</details> <details> <summary>`ReferralFeesClaimed`</summary>

Emitted when referral fees are claimed by the referral owner.

<ImportContent source="packages/deepbook_margin/sources/margin_pool/protocol_fees.move" mode="code" org="MystenLabs" repo="deepbookv3" struct="ReferralFeesClaimedEvent" />

</details>

Fee distribution

The referral spread parameter (typically 20%) determines what portion of protocol fees goes to referrers. For example:

• Without referral: 100% of protocol fees go to the protocol
• With referral: 80% to protocol, 20% to referrer (at 20% referral spread)

The referral spread is configured per margin pool and can be viewed in the Contract Information.