Referral

The referral system lets existing traders recruit new users and earn a share of the trading fees generated by their referrals. When a referred user trades, a portion of the fee — after the protocol treasury has taken its cut — is distributed to the direct referrer and up to four additional upstream referrers in the referral chain.

1. Overview

Three roles participate in a referral commission:

Referee — the user who was referred and is paying trading fees.
Direct referrer (level 1) — the user who referred the referee. Earns a commission on the referee’s fees and may share a portion of it back with the referee.
Upstream referrers (levels 2–5) — referrers further up the chain. Each receives only the marginal increase in commission rate beyond what lower levels already captured.

Commissions are taken from the trading fee after the protocol treasury has claimed its share. The system can be disabled globally by setting $active = false$ in the referral parameters, which causes the commission pass to be skipped entirely.

Referral commissions are applied whenever an order is filled and trading fees are collected. Exception: liquidation fills (both for the taker and the maker) use zero trading fees, so no referral commissions occur during liquidation.

2. Key concepts

Two rates govern how referral fees are distributed:

Commission rate ( $cr$ ) — the fraction of the post-protocol-cut fee that the referral system distributes at a given level. This rate is tiered: it increases as the referrer’s direct referees accumulate more 30-day rolling trading volume (see §6b). The chain owner can also set a per-user override (see §6a).
Fee share ratio ( $sr$ ) — the fraction of the level-1 commission that the direct referrer gives back to the referee as a rebate. For example, if the commission rate is 20 % and the share ratio is 50 %, the referee receives 10 % and the referrer keeps 10 %. The share ratio is capped at 50 % and can only increase once set.

3. Registration

3a. Becoming a referrer

A user opts in as a referrer by calling SetFeeShareRatio with a $shareRatio$ value. The share ratio determines what fraction of the level-1 commission the referrer gives back to the referee (see §5a).

Eligibility: the user must have accumulated enough lifetime trading volume:

$lifetimeVolume \geq volumeToBeReferrer$

Users who have a commission rate override (see §6a) bypass this volume requirement.

Constraints:

$shareRatio \leq 50%$ — the maximum share ratio a referrer can set.
The share ratio can only increase once set. A subsequent call must supply a value $\geq$ the current ratio.

3b. Registering a referee

A referee is linked to a referrer through one of two paths:

During account creation — the RegisterUser message on the account factory accepts an optional referrer field. If provided, the factory forwards a SetReferral message to the perps contract.
After account creation — the referee (or an account they own) calls SetReferral directly on the perps contract.

Constraints:

A user cannot refer themselves ( $referrer \neq = referee$ ).
The referrer must already have a fee share ratio set (i.e. has opted in as a referrer).
The referral relationship is immutable once stored — a referee can never change or remove their referrer.

When a referral is registered, a per-referee statistics record is initialised for the (referrer, referee) pair, and the referrer’s $refereeCount$ is incremented in today’s cumulative data bucket.

4. Fee split recap

For every fill, a trading fee is computed per Order matching §8:

$fee = ∣ fillSize ∣ \times fillPrice \times feeRate$

The fee is then split between the protocol treasury and the vault:

$protocolFee = fee \times protocolFeeRate$

$vaultFee = fee - protocolFee$

The protocol fee is routed to the treasury and is not affected by referrals. Referral commissions are computed against $vaultFee$ — i.e. the remainder of the fee after the protocol has taken its cut.

5. Commission distribution

After PnL settlement and fee collection, the contract distributes referral commissions for every fee-paying user who has a referrer. Commissions are drawn from the post-protocol-cut fee and credited to the recipients’ margins.

5a. Level 1 — direct referrer

Let $cr_{1}$ be the commission rate of the direct referrer (see §6) and $sr$ be that referrer’s fee share ratio.

The referee (fee payer) receives:

$refereeShare = vaultFee \times cr_{1} \times sr$

The direct referrer receives:

$referrerCommission = vaultFee \times cr_{1} \times (1 - sr)$

Equivalently, the total level-1 commission is $vaultFee \times cr_{1}$ , split between referee and referrer by the share ratio.

5b. Levels 2–5 — upstream referrers

The algorithm walks up the referral chain from the direct referrer. At each level $n$ ( $2 \leq n \leq 5$ ), let $cr_{n}$ be the commission rate of the $n$ -th referrer and $maxCr$ be the maximum commission rate seen at any prior level (initialised to $cr_{1}$ ).

$marginal_{n} = max (0, cr_{n} - maxCr)$

$commission_{n} = vaultFee \times marginal_{n}$

After computing $commission_{n}$ , update:

$maxCr \leftarrow max (maxCr, cr_{n})$

If $cr_{n} \leq maxCr$ , the referrer at level $n$ receives nothing. The chain walk stops early if a referrer at level $n$ has no referrer of their own, or after level 5.

Upstream referrers do not use a share ratio — the entire marginal commission goes to the upstream referrer.

5c. Vault deduction

After processing all fee-paying users, the total of all commissions is deducted from the fee that would otherwise have accrued to the vault:

$vaultMargin - = \sum commissions$

5d. Worked example

Setup. Five users form a referral chain, each with a commission rate override. User C has a fee share ratio of 40 %:

User	Commission rate ( $cr$ )	Fee share ratio ( $sr$ )	Referrer
A	30 %	—	—
B	20 %	—	A
C	15 %	40 %	B
D	—	—	C
E	40 %	—	D

Trade. User D trades $10 m taker volume, pays $1,000 in fees. Assume $protocolFeeRate = 0$ so $vaultFee = $1, 000$ .

Level	User	$cr$	$maxCr$	Receives
1 (referee D)	D	—	—	$$1, 000 \times cr \times sr = $60$
1 (referrer C)	C	15 %	—	$$1, 000 \times cr \times (1 - sr) = $90$
2	B	20 %	15 %	$$1, 000 \times (cr - maxCr) = $50$
3	A	30 %	20 %	$$1, 000 \times (cr - maxCr) = $100$

Total referral commissions = $300, equal to the highest commission rate in the chain (A’s 30 %) applied to the fee after the protocol cut.

Counter-example. Now User F signs up under User E (40 % commission rate) and trades. Since E’s 40 % exceeds every upstream referrer, no upstream commissions are paid — only E and F split the level-1 commission of $vaultFee \times 40%$ .

6. Commission rate

The commission rate $cr$ for a referrer determines the fraction of the post-protocol-cut fee that the referral system distributes at that level.

6a. Override

The chain owner can set (or remove) a per-user override via SetCommissionRateOverride. When present, this value is used directly, bypassing the volume-tiered lookup. Users with an override also bypass the $volumeToBeReferrer$ requirement when calling SetFeeShareRatio.

6b. Volume-tiered lookup

When no override exists, $cr$ is derived from the referrer’s direct referees’ 30-day rolling trading volume:

Load the referrer’s latest cumulative referral data; let $V_{now}$ be its $refereesVolume$ field.
Load the cumulative data at $t_{now} - 30 days$ ; let $V_{start}$ be its $refereesVolume$ field.
Compute the windowed volume:

$windowRefereesVolume = V_{now} - V_{start}$
Walk the $commissionRatesByVolume$ map and select the entry with the highest volume threshold $\leq windowRefereesVolume$ .
If no tier qualifies, use $commissionRateDefault$ .

Cumulative data is bucketed by day (see §7a), so the lookup loads the nearest bucket at or before the start of the window.

7. Data tracking

7a. Cumulative daily buckets

Each user has a UserReferralData record keyed by (user, day). The day is the block timestamp rounded down to midnight. Fields are cumulative (monotonically increasing), so a rolling window is computed by differencing two buckets.

Field	Type	Description
`volume`	`UsdValue`	User’s own cumulative trading volume.
`commission_shared_by_referrer`	`UsdValue`	Total commission shared by this user’s referrer.
`referee_count`	`u32`	Number of direct referees.
`referees_volume`	`UsdValue`	Cumulative trading volume of direct referees.
`commission_earned_from_referees`	`UsdValue`	Total commission earned from direct referees’ trades.
`cumulative_active_referees`	`u32`	Cumulative count of daily active direct referees. Difference two buckets to get a windowed count.

When a referred user trades:

The referee’s bucket: $volume$ and $commissionSharedByReferrer$ increment.
The direct referrer’s bucket: $refereesVolume$ and $commissionEarnedFromReferees$ increment.
Upstream referrers: only $commissionEarnedFromReferees$ increments (and only if they received a non-zero commission).

7b. Per-referee statistics

For every (referrer, referee) pair, a RefereeStats record tracks:

Field	Type	Description
`registered_at`	`Timestamp`	When the referral was established.
`volume`	`UsdValue`	Referee’s total trading volume.
`commission_earned`	`UsdValue`	Commission earned by referrer from this referee.
`last_day_active`	`Timestamp`	Last day (rounded to midnight) the referee traded.

These records are multi-indexed for sorted queries by registered_at, volume, or commission_earned.

7c. Daily active direct referees

On the first trade of each day by a given direct referee, the referrer’s $cumulativeActiveReferees$ field in today’s cumulative bucket is incremented. Subsequent trades by the same referee on the same day do not increment it again. This is tracked via the $lastDayActive$ field on RefereeStats: if $lastDayActive \neq = today$ , it is a new active day.

8. Parameters

These fields are part of the top-level Param struct (not a separate nested struct):

Field	Type	Description
`referral_active`	`bool`	Master switch. When `false`, referral commissions are skipped entirely.
`min_referrer_volume`	`UsdValue`	Minimum lifetime trading volume to call `SetFeeShareRatio`. Bypassed for users with a commission rate override.
`referrer_commission_rates`	`RateSchedule`	Volume-tiered commission rates. `base` = fallback rate; `tiers` = map of 30-day referees volume threshold → rate. Highest qualifying tier wins.

Constants:

Name	Value	Description
`MAX_FEE_SHARE_RATIO`	50 %	Maximum share ratio a referrer can set.
`MAX_REFERRAL_CHAIN_DEPTH`	5	Maximum levels of upstream referrers walked during commission distribution.
`COMMISSION_LOOKBACK_DAYS`	30	Rolling-window length (days) for the volume-tiered commission lookup.

Keyboard shortcuts

The Dango Book