# Protocol Maths

## POOL STRUCTURE MATHS 

### Bin limits

Nitro Finance uses $$128.128$$ binary fixed-point representation, where the left 128 bits represent integers and the right 128 bits represent fractional parts. The upper limit of the price is constrained by $$2^{128}$$, a significant value that ensures a broad range for asset pricing.

**how many bins could we possibly have?**

* Bin prices follow a geometric sequence, denoted as $$(1+s)^i$$. We now need to find the maximum integer for $$i$$ such that the entire value is less than the upper limit of price, $$2^{128}$$This can be  expressed as the formula $$((1+s)^i<2^{128})$$.

Taking the smallest possible value of  bin step($$s$$) which is 1 basis point, we can solve this as follows:

* $$(1+0.0001)^i<2^{128}$$n
* $$log\_2 (1.0001)^i < log\_2 (2^{128})$$
* $$i⋅log2 (1.0001)<128$$
* $$i<\dfrac{128}{log2 (1.0001)} ≈ 887,273$$,<br>
* $$i=887,273$$

The above equation shows how many bins are needed to cover the entire range when $$i$$ is a positive integer, so we account for when it is negative by doubling it which equals to $$2\times887,272=1,774,544$$ bins.

### Bin Indexing

the Nitro Finance system uses the uint24 data type. It's sufficient to cover the range of possible bins,

&#x20;`uint24` is $$2^{24}-1 =16,777,215$$&#x20;

* **Range**: 0 to **16,777,215**&#x20;
* **Minimum Value**: 0
* **Maximum Value**: 16,777,215

Every bin is assigned a unique identifier (bin ID) based on a mathematical relationship between the bin's price and a fixed reference point within the system.

* $$\text{Reference Point} = \dfrac{(16,777,215 - 0) + 1}{2} = \dfrac{16,777,216}{2} = 8,388,608$$

$$\text{bin Id} =  \dfrac{log\text{(Price)}}{log(1 + \frac{\text{bin Step}}{10000})}  + 8388608$$

* bin Step(s) is in basis points, converted to a decimal.
* Price is the specific price level for calculating the bin ID.
* 8388608 is the **midpoint** of the range.

### Bin pricing

The price of each bin is a function of the pair’s bin step and the bin’s index, The bin step parameter determines the constant percentage increase or decrease in price between each incremental bin.

* $$8388608=$$ reference point
* $$Price\_{\text{bin}} = (1 + \text{bin step})^{(\text{bin index} - 8388608)}$$

## LIQUIDITY STRUCTURE MATHS

### Bin liquidity

The total liquidity in a bin: $$P.(X+Z\_x)+(Y+Z\_y)=L\_T$$&#x20;

Available liquidity in a bin:  $$P.(X)+(Y)=L\_A$$

{% hint style="success" %}
$$P$$= price in terms of Y\
$$X$$= base asset\
$$Y$$= quote asset \
$$Zy$$= collateralized quote asset\
$$Zx$$= collateralized base asset
{% endhint %}

### Bin composition

**The Liquidity Composition factor (Lc)** determines the ratio of the base asset to the quote asset. $$Lc=\dfrac{X}{Y}$$

**The debt composition factor (Dc)** determines the debt ratio.&#x20;

&#x20;  $$Dc=\dfrac{Zy + (P.Z\_x)}{L\_T}$$

* Dc = 0: There is no debt in the bin
* Dc > 1: There is debt in the bin&#x20;

## BASIC INTERACTION MATHS

### Adding liquidity

Adding liquidity to a bin will conserve the (Lc) of the bin. If a certain quantity of X (base asset) is determined, it is possible to compute the associated amount of Y (quote asset) to be added, and vice versa.

**Liquidity added** (L) = $${P.∆x} + {∆y}$$

**Bin Shares Received (B):**

When adding, you will receive bin shares representing the liquidity added.\
$$B = \dfrac{L \times TBS}{L\_T}$$&#x20;

### **Removing liquidity**

Removing liquidity results in the burning of Bin shares(B) which results in the receipt of assets X, and Y from the pool, and the minting of B (bin shares) associated with debt.

$$X, Y, B = \dfrac{B \times (Rx, Ry, Dc \times TBS)}{TBS}$$

{% hint style="success" %}
$$L$$ = liquidity added\
$$B$$ = bin shares \
$$TBS$$ = total bin shares\
$$L\_T$$= total liquidity \
$$Dc$$ = debt composition \
$$Rx$$= X reserve.  hhh\
$$Ry$$ = Y reserve
{% endhint %}

### Swaps&#x20;

* Selling Base Asset (X) for Quote Asset (Y): $$∆y=P\times∆x$$
* Buying Base Asset (X) with Quote Asset (Y): $$∆x=\dfrac{∆y}{P}$$

## DEBT INTERACTION MATHS&#x20;

### Borrowing:

**Below Active Bin:**

* Collateralize base asset (X), borrow quote asset (Y).
* $$∆y=P\times∆Z\_x$$

**Above Active Bin:**

* Collateralize quote asset (Y), borrow base asset (X).
* $$∆x=\dfrac{∆Z\_y}{P}$$

### Repaying:

**Below Active Bin:**

* Return borrowed Y, retrieve collateralized X.
* $$∆Z\_x=\dfrac{∆y}{P}$$
* Active Bin ID ≤ Borrow Bin ID ⇒ Repayment ≠ Possible

**Above Active Bin:**

* Return borrowed X, retrieve collateralized Y.
* $$∆Z\_y=P\times∆x$$
* Active Bin ID ≥ Borrow Bin ID ⇒ Repayment ≠ Possible

### Debt rollover

Extends the lifespan of a debt to its default duration $$(T\_{d})$$

* $$T\_d$$ = Default debt lifespan (7 days in this case)
* $$T\_{rem}$$= Remaining time to expiry
* $$T\_{roll}$$= New lifespan of the debt after rollover

**Debt rollover is represented as:**

* $$T\_{rollover} = T\_{default}$$

regardless of $$T\_{rem}$$=*Time remaining*, the lifespan is reset to $$T\_d$$= default time once a rollover occurs.

### Blacklist (Auto debt recovery)

When the remaining time of a debt reaches zero, the debt is **blacklisted** and becomes liquidatable.

$$T\_{rem}$$= 0 ⇒ Blacklist⇒ Liquidatable

Blacklisted debts automatically absorb the collateral into the liquidity pool.

### Buffer Range:

Buffer Range: $$±bins$$, indicating the range on either side of the active bin functioning as a safeguard to preserve liquidity for swaps and prevent liquidity depletion due to borrowing activities

$$±bins=\dfrac{B\_P}{s}$$

* Buffer percent $$(B\_p)$$: A predetermined percentage.
* Bin Step (s): The rate of price change between each bin.

**Implications:**

* Borrow and Debt Rollover:

&#x20;$$\text{Allowed} = \begin{cases} 0, & \text{if within buffer range ((\pm \text{bins}))} \ 1, & \text{otherwise} \end{cases}$$

* Repayment and Liquidation:

$$\text{Always Allowed} = 1$$

## FEE MATHS

### **Swap Fee (F):**

The **Swap Fee** applies to all token exchanges within the liquidity pool.

&#x20;$$\text F=\text{Base factor} \times \text{Bin step}$$

* **Base Factor**: A multiplier set by the protocol to adjust the fee rate as needed.
* **Bin Step**: The percentage price difference between consecutive bins.

### **Borrow Fee (Bf)**

The **Borrow Fee** is incurred when initiating a borrowing position.

&#x20;$$Bf =  \text F \times {Borrow factor}$$

* **Borrow Factor**: A multiplier set by the protocol to control borrowing costs independently of swap fees.
* **Streaming of Borrow Fee:**\
  $$\dfrac{\text{Bin fee reserve}}{\text{seconds in 7-days of debt}}=  λ$$
  * Where $$λ$$ is the per-second fee allocation from the bin's fee reserve.

### Repay Fee (Rf):&#x20;

The **Repay Fee** compensates LPs for the opportunity cost of inactive liquidity due to debt.

$$(\text{Bin activation index- Debt activation index}) \times \text{F}$$

Bin Activation Index:

* The number of times a bin was activated

Debt Activation Index:

* Set when borrowing, matching the Bin Activation Index of the bin at that time.

### Debt Rollover Fee:

The **Debt Rollover Fee** applies when a borrower extends their debt's lifespan.&#x20;

$$DRF=\text F +\text Rf$$

* **F**: The Swap Fee.
* **Rf​**: The Repay Fee.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://nitro-finance.gitbook.io/ftl/protocol-overview/protocol-maths.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.