# Fees

## Introduction

Liquidity Book introduces dynamic fees to allow for surge pricing during high market volatility.

Traders pay a swap fee to liquidity providers when performing a swap. The total swap fee (𝑓𝚜) will have two components: a **base fee** (𝑓b) and a **variable fee** (𝑓v), which is a function of instantaneous price volatility. The fee rate will be applied to the swap amount in each liquidity bin and distributed proportionally to the liquidity providers in that bin.

* In V2.0, fees will be held separate from liquidity and claimable by liquidity providers.
* In V2.1, fees are added to existing positions and held in reserve. Liquidity providers may claim them when withdrawing from liquidity pools.

## Base Fee

The base fee of a market is configured by the protocol owner and determined by the **base factor** (𝐵) and the **bin step** (s):

$$
f\_b = B \cdot s
$$

## Variable Fee

The variable fee on the other hand depends on the volatility of the market. It will be affected by the frequency of the swaps, but doing large swaps accross many bins (on large price movements) will also increase it. Fees are calculated and distributed *per bin*, to allow a fair distribution of the fee to the liquidity providers of the bin crossed.

Fees are calculated iteratively as each bin is crossed (if the swap is large enough). In other words, if a large swap crosses 𝓃 bins, then the total swap fee is calculated per bin 𝚔 (such that 0 ⪯  𝚔 ⪯ 𝓃), where 𝚔 is the difference in bin IDs from the initial bin where the swap originated and the current bin in which it is being calculated.

Example - take SEI/USDC. The active bin before swap is $100. A large buy order is made that pushes the price up to $103. The values of 𝚔 for each bin is listed below (note: bin prices are simplified for this example):

$100 bin - ID = 1844; 𝚔 = 0

$101 bin - ID = 1845; 𝚔 = 1

$102 bin - ID = 1846; 𝚔 = 2

$103 bin - ID = 1847; 𝚔 = 3

𝚔 can also be negative if it pushes the price downwards.

The variable fee for a bin 𝑓v(𝚔) will be calculated using the **variable fee control** parameter (𝐴), bin step (s) and the **volatility accumulator** (**𝓿**𝑎(𝚔)):

$$
f\_v(k) = A(v\_a(k) \cdot s) ^ 2
$$

### Volatility Accumulator

The **volatility accumulator** (**𝓿**𝑎(𝚔)) is the witness of the current volatility of the pair. This value will be kept in memory between each calculation step. It will be calculated during a swap and will depend on two factors: the **volatility reference** (**𝓿**ᵣ) from the previous swaps, and the **introduced volatility** (|𝑖ᵣ - (activeId + 𝚔)|):

$$
v\_a(k) = v\_r + |i\_r - (activeId + k)|
$$

(Note: activeId is the ID of the active bin **before** the swap is made.)

The **volatility reference** (**𝓿**ᵣ) depends on the time elapsed since the last transaction (𝑡). We define a window which has an upper and lower bound. If 𝑡 is smaller than the lower bound defined by **filter period** (𝑡𝑓) (i.e. high frequency of transactions occurring), then **𝓿**ᵣ stays the same. If 𝑡 is greater than the upper bound defined by **decay period** (𝑡𝒹) (i.e. low frequency of transactions occurring), then **𝓿**ᵣ is reset to 0. If 𝑡 is within the window, then it takes the previous **𝓿**𝑎 decayed by a factor 𝘙.

$$
v\_r = \begin{cases} v\_r, & t < t\_f \ R \cdot v\_a, & t\_f <= t < t\_d \ 0 , & t\_d <= t \end{cases}
$$

This means that high frequency trades will stack up volatility, while low frequency trades will slowly reduce the volatility, or even reset it after a long moment has passed without any trade.

Now that the **volatility reference** is calculated, it is time to calculate the volatility introduced by the trade. Another variable, the **index reference** (𝑖ᵣ), is introduced. In most cases, 𝑖ᵣ will simply be the ID of the active bin before the swap is made. But in times of high frequency transactions, 𝑖ᵣ will keep its old value instead. This is to prevent people from manipulating fees by making small lots of small transactions that increase and decrease price.

$$
i\_r = \begin{cases} i\_r, & t < t\_f \ activeId, & t\_f <= t \end{cases}
$$

The **volatility accumulated** for the bin 𝚔 will then be used to calculate the fees generated by swapping through this bin and be allocated to the liquidity providers of the bin.

The final fee for the bin 𝚔 will be: fee = (swap amount)𝚔 ⋅ (𝑓b + 𝑓v)𝚔

### Volatility Accumulator Example

All that was probably extremely confusing so we outline an example of how the volatility accumulator will look as swaps are made.

Let 𝑡𝑓 = 1 sec, 𝑡𝑑 = 5 secs, 𝘙 = 0.5 secs and active bin ID is 100.

#### Swap 1

You make a trade that crosses +3 bins to 103. So 0 ⪯ 𝚔 ⪯ 3:

$$
i\_r = 100
$$

$$
v\_r = 0
$$

$$
v\_a(0) = 0 + |100 - (100 + 0)| = 0
$$

$$
v\_a(1) = 0 + |100 - (100 + 1)| = 1
$$

$$
v\_a(2) = 0 + |100 - (100 + 2)| = 2
$$

$$
v\_a(3) = 0 + |100 - (100 + 3)| = 3
$$

#### Swap 2

Alice makes a trade 4 secs later that crosses +5 bins to 108. So 0⪯ 𝚔 ⪯ 5:

$$
i\_r = 103
$$

$$
v\_r = 0.5 \cdot 3 = 1.5
$$

$$
v\_a(0) = 1.5 + |103 - (103 + 0)| = 1.5
$$

$$
v\_a(1) = 1.5 + |103 - (103 + 1)| = 2.5
$$

$$
v\_a(2) = 1.5 + |103 - (103 + 2)| = 3.5
$$

$$
...
$$

$$
v\_a(5) = 1.5 + |103 - (103 + 5)| = 6.5
$$

#### Swap 3

Bob makes a trade 0.3 secs later that crosses -2 bins to 106. So -2 ⪯ 𝚔 ⪯ 0:

Note: **𝓿**ᵣ  and  𝑖ᵣ do not update as the transaction was less than the filter period.

$$
i\_r = 103
$$

$$
v\_r = 1.5
$$

$$
v\_a(0) = 1.5 + |103 - (108 + 0)| = 6.5
$$

$$
v\_a(-1) = 1.5 + |103 - (108 - 1)| = 5.5
$$

$$
v\_a(-2) = 1.5 + |103 - (108 - 2)| = 4.5
$$

Notice that the volatility accumulator is decreasing despite high frequency of transactions.

## Protocol Fees

A share of all the fees is also taken by the protocol and distributed to SEIP token holders via the StableSeipStaking contract. It is expressed as a variable, `protocolShare`, which is a percentage of the total swap fee. The maximum possible is 25%.
