> For the complete documentation index, see [llms.txt](https://nitro-finance.gitbook.io/ftl/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://nitro-finance.gitbook.io/ftl/protocol-overview/protocol-maths.md). # 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$$,
* $$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, `uint24` is $$2^{24}-1 =16,777,215$$ * **Range**: 0 to **16,777,215** * **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$$ 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. $$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 ## 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}$$ ### **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 * 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 ### 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: $$\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. $$\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. $$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): 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. $$DRF=\text F +\text Rf$$ * **F**: The Swap Fee. * **Rf​**: The Repay Fee.