updated boros docs (#264)

Author: HubertHalim

docs/boros-docs/about-boros/funding-rate-settlement.md

@@ -0,0 +1,49 @@
+# Funding Rate Settlement
+
+## How Boros Positions Work
+
+Every position on Boros is an interest rate swap: you exchange one interest stream for another until maturity.
+
+- **Long (Pay Fixed, Receive Floating):** You lock in a fixed APR at entry and receive the underlying floating rate at each settlement. You profit when the floating rate exceeds your fixed rate.
+- **Short (Pay Floating, Receive Fixed):** You receive your locked-in fixed APR and pay the underlying floating rate at each settlement. You profit when the floating rate stays below your fixed rate.
+
+![FR Settlement](/boros-docs/imgs/image2.png "FR Settlement")
+
+Your fixed APR is set at the moment your order fills. It is the average implied APR of the filled order.
+
+## Periodic Settlement
+
+A settlement occurs when the underlying exchange charges its funding rate payments. At each settlement interval, Boros fetches the actual underlying funding rate from its oracle and realises the net difference between the floating and fixed rate into your collateral.
+
+Settlement intervals mirror the underlying market:
+
+- **Binance markets:** every 8 hours
+- **Hyperliquid markets:** every 1 hour
+
+The net cash flow per settlement:
+
+> **Long:** Settlement = Position Size × (Floating Rate − Fixed Rate) × Settlement Period
+> **Short:** Settlement = Position Size × (Fixed Rate − Floating Rate) × Settlement Period
+
+A positive / negative result adds / reduces to your collateral respectively.
+
+## How Settlement Affects Margin
+
+Each settlement period, two things happen:
+
+1. **Collateral changes** by the net rate differential (positive or negative).
+2. **Margin requirement declines** as time to maturity shrinks. The remaining yield stream is smaller, so less margin is required to hold the same position size.
+
+A position that is persistently out of the money will see collateral eroded each period. If sustained, this can push a position toward liquidation even without any change in the mark rate.
+
+At maturity, rate sensitivity reaches zero, all margin is freed, and collateral reflects the cumulative net of every settlement over the position's life.
+
+## The Underlying Rate Oracle
+
+The underlying rate used in each settlement is sourced independently, not derived from Boros's order book. The pipeline:
+
+1. An off-chain bot fetches the actual funding rate from the relevant CEX / perp DEX at each epoch boundary
+2. The rate is submitted to a **FundingRateVerifier**, validated against one of three independent oracle sources (Chainlink Data Streams, ChaosLabs Risk Oracle, or Pendle's oracle)
+3. Once validated, it is forwarded to the **FIndex Oracle**, which accumulates it into a cumulative index that the market reads at settlement
+
+Every submitted rate is validated for correct sequencing, **no funding rate settlement can be skipped**. If the bot misses an update window, a short grace period allows catch-up; after that, a manual admin override merges the missed epochs into the next valid update.

docs/boros-docs/about-boros/implied-apr-and-position-sizing.md

@@ -0,0 +1,89 @@
+# Implied APR and Position Sizing
+
+## Implied APR and Fixed APR
+
+**Implied APR is the market price of a YU position, expressed as an annualised rate.** It reflects the market's collective expectation of an asset's future funding rate and is the rate at which traders enter positions.
+
+When you open a position, the prevailing implied APR locks in as your **fixed APR,** the rate you will pay (long) or receive (short) through to maturity. It does not change after entry.
+
+Implied APR is also the primary driver of unrealised PnL:
+
+- Rising implied APR benefits long positions, hurts short positions
+- Falling implied APR benefits short positions, hurts long positions
+
+
+### Long YU
+
+**Pay fixed APR, receive floating APR.**
+
+Going long is a bet that the underlying funding rate will exceed your fixed APR, or that implied APR will rise after entry (increasing the mark-to-market value of your position).
+
+A long position profits when:
+
+1. Underlying rate > fixed rate (positive settlement cash flows)
+2. Implied APR rises after entry (unrealised PnL improves)
+
+Both can occur simultaneously, and either alone is sufficient to generate a profit.
+
+
+### Short YU
+
+**Pay floating APR, receive fixed APR.**
+
+Going short is a bet that the underlying funding rate will stay below your fixed APR, or that implied APR will fall after entry.
+
+A short position profits when:
+
+1. Underlying rate < fixed rate (positive settlement cash flows)
+2. Implied APR falls after entry (unrealised PnL improves)
+
+
+## Rate Sensitivity and Position Sizing
+
+Unlike spot or perp trading, YU positions are not sized by collateral leverage in the traditional sense. The relevant measure is **Rate Sensitivity,** how much your collateral changes for every 1% move in implied APR.
+
+> **Rate Sensitivity = Position Size × Time to Maturity (years) × 1%**
+
+![Rate Sens](/boros-docs/imgs/rate-sensitivity.png "Rate Sensitivity")
+
+For example, A 250 ETH YU **short** position with 17 days to maturity has a rate sensitivity of ~0.122 ETH per 1% move ($200 at the time of writing):
+
+- 1% increase in implied APR (adverse move) costs you 0.122 ETH
+- 1% decline in implied APR (favourable move) earns you 0.122 ETH
+
+Rate sensitivity declines naturally as maturity approaches, since the same position has less exposure with, for instance, 10 days remaining vs 180 days.
+
+**Using Rate Sensitivity to assess risk:**
+
+Your effective risk buffer is:
+
+> **Buffer = Margin / Rate Sensitivity**
+
+This tells you how many percentage points implied APR can move against you before you approach liquidation. Compare this against **Daily Volatility** (the 7-day moving average of daily implied APR range) to gauge whether your margin is adequate for current market conditions.
+
+For example: $1000 margin with a rate sensitivity of $200 gives a buffer of ~5%. If daily volatility is running >5%, your position can be wiped out in a single day's move and could a signal to reduce size or top up collateral.
+
+The levers for managing your rate sensitivity (risks) are straightforward:
+
+- **Reduce position size** → lower rate sensitivity
+- **Choose a shorter-dated market** → lower rate sensitivity for same notional size
+- **Add collateral** → widens your buffer without changing rate sensitivity
+
+
+## Opening a Position
+
+1. Select a market and deposit collateral into the relevant zone
+2. Enter position size and direction (long or short)
+3. Execute a market order for immediate fill, or place a limit order at your target implied APR
+4. Position is live once the order fills
+
+
+## Closing a Position
+
+Closing works by executing the opposite trade against your existing position. A long is closed by going short for the equivalent size, and vice versa. The floating rate legs cancel out, leaving a net fixed APR cash flow to maturity, which Boros immediately settles into your collateral rather than requiring you to hold to expiry.
+
+![Closing Position](/boros-docs/imgs/image5.png "Closing Position")
+
+You can close partially by entering a smaller opposing size than your current position. The remainder stays open at your original fixed APR.
+
+**Caution:** Limit orders are independent of open positions. If you place a limit order to close 1,000 YU and then manually close 250 YU via market order, the original limit order for 1,000 YU remains active. If it fills, it will close your remaining 750 YU and open a new 250 YU position in the opposite direction. Always cancel or adjust limit orders when manually managing positions.

docs/boros-docs/boros-systems/fees.md

@@ -0,0 +1,51 @@
+# Fees
+
+Boros charges four types of fees. All fees are denominated in the collateral asset of the relevant market and deducted directly from your collateral balance.
+
+Fee rate can differ by markets, check out the market details for specific information on the respective markets.
+
+![Market Info](/boros-docs/imgs/market-info.png "Market Info")
+
+## 1. Taker Fee (Swap Fee)
+
+Charged when your order executes against a resting order on the book (Market Order). **Maker orders (limit orders that rest on the book) are never charged a fee,** the fee falls entirely on the taker at the point of fill.
+
+The fee scales with position size and time to maturity:
+
+> **Fee = Position Size × Fee Rate × Time to Maturity (in years)**
+
+So a larger position or a longer-dated market incurs a proportionally higher fee. For example, at a 0.05% fee rate, opening a position 90 days before maturity costs roughly 0.012% of notional (0.05% × 90/365).
+
+The practical implication: your position needs implied APR to move by at least **2× the taker fee** in your favor to be profitable on a round-trip (open + close), assuming no yield settlement income in between and both trades were done via market order (taker).
+
+## 2. Settlement Fee (Open Interest Fee)
+
+Charged on all open positions at each periodic settlement. This is the carrying cost of holding a position.
+
+> **Settlement Fee = Position Size × Settlement Fee Rate × Settlement Period (in years)**
+
+At an 0.2% annualized settlement fee rate, the cost per 8-hour period is approximately 0.000183% of your position size — small per cycle, but it accumulates over the life of a position. This is analogous to a funding fee on perpetuals.
+
+The settlement fee applies regardless of whether the position is long or short.
+
+## 3. Market Entrance Fee
+
+A one-time fee charged the first time you interact with a given market. It is approximately **$1 USD** equivalent, denominated in the market's base asset:
+
+- BTC markets: ~0.000008 BTC
+- ETH markets: ~0.00027 ETH
+
+This fee is charged once per market and is not repeated on subsequent interactions.
+
+## 4. Liquidation Fee
+
+Fee is charged on the liquidated position size and collected by the protocol. This is separate from the incentive paid to the liquidator. Like the taker fee, it scales with position size and time to maturity remaining at the point of liquidation.
+
+## Fee Summary
+
+| Fee | When | Maker / Taker | Discountable |
+| --- | --- | --- | --- |
+| Taker fee | On order fill | Taker only | Yes (Referral Discount) |
+| Settlement fee | Every settlement on open positions | Both sides | No |
+| Market entrance fee | First interaction per market | — | No |
+| Liquidation fee | On liquidation | — | No |

docs/boros-docs/boros-systems/margin-and-liquidations.md

@@ -0,0 +1,83 @@
+# Margin & Liquidations
+
+## Understanding Your Position's Risk
+
+Boros uses three linked metrics to characterise a position's exposure and margin requirements:
+
+**Rate Sensitivity** is how much PnL your position gains or loses for every 1% move in implied APR. It's the primary lens for understanding exposure, equivalent to 100 × DV01 in TradFi interest rate swap conventions.
+
+> Rate Sensitivity = Notional Size × (Days to Maturity / 365) × 1%
+
+**Daily Volatility** is the 7-day moving average of the daily implied APR range, how much the rate swings in a typical day.
+
+> Rate Sensitivity × Daily Volatility = Daily P&L Range
+
+This gives you a practical sense of how much your position can gain or lose on any given day under recent conditions. More volatile assets require proportionally higher margin for the same rate sensitivity.
+
+**Margin** is the collateral used to back your position, your buffer against adverse rate moves.
+
+
+## Net Balance
+
+Your **Net Balance** determines whether a position remains healthy or is eligible for liquidation:
+
+> Net Balance = Collateral + Unrealized PnL
+
+**Collateral** is adjusted at every settlement period (every 8 hours), when the difference between the fixed rate and the underlying rate is cash-settled into your collateral. A short position, for example, will see its collateral erode if the underlying rate stays persistently above the fixed rate it receives.
+
+**Unrealized PnL** moves with the mark implied APR. A long position sees unrealized losses as the mark rate falls, and vice versa.
+
+Monitor your Net Balance closely, add collateral if your margin ratio is trending low.
+
+
+## Margin Modes
+
+**Cross Margin** allows a single collateral deposit to back multiple positions within the same collateral zone (e.g. all BTC-denominated markets share one BTC collateral pool). Unrealized profits in one position offset margin requirements across the zone. Liquidations in one zone do not affect positions in other zones.
+
+**Isolated Margin** confines collateral to a single market. Losses in an isolated position cannot spill over to other positions.
+
+
+## Initial Margin
+
+Initial margin is the collateral required to open a position. It scales with notional size, time to maturity, and the implied APR at which the position is opened — floored at the market's Margin Floor (see below):
+
+> IM = IM Factor × |Notional Size| × max(Time to Maturity, Time Floor) × max(|Mark Rate|, Rate Floor)
+
+Once consumed, initial margin is locked and cannot be reused to back other positions. Any remaining collateral beyond the initial margin is your **Available Margin**, which increases with unrealized profits and decreases with unrealized losses. Your collateral balance then increases or decreases by the settlement PnL.
+
+
+## Maintenance Margin
+
+Maintenance margin is the minimum Net Balance required to keep a position open. It uses the same formula as initial margin but with a lower factor:
+
+> MM = MM Factor × |Notional Size| × max(Time to Maturity, Time Floor) × max(|Mark Rate|, Rate Floor)
+
+As maturity approaches and periodic settlements reduce the position's residual yield exposure, both rate sensitivity and maintenance margin decline in tandem. At maturity, both reach zero and the full position is settled into collateral.
+
+A position becomes eligible for liquidation when its **Net Balance falls below its Maintenance Margin**.
+
+
+## Margin Floor
+
+The Margin Floor sets a minimum rate (implied APR) and minimum time-to-maturity used in margin calculations, ensuring positions are never backed by trivially small collateral. There are two components:
+
+**Rate Floor:** Because initial margin scales linearly with implied APR, a position opened near 0% (or negative) rates would require near-zero margin, creating bad debt risk. The Rate Floor enforces a minimum APR for margin calculation purposes. For example, in a market with an 8% Rate Floor, any position opened between -8% and +8% is margined as if it were opened at 8%.
+
+**Time Floor (Near-Maturity Floor):** As maturity approaches, required margin shrinks. Without a floor, positions in the final days before maturity would be backed by negligible collateral, leaving the protocol exposed to sharp last-minute rate swings. The Time Floor prevents margin from decaying below the equivalent of a position with a set number of days remaining (e.g. 7 days). Any position opened inside that window is margined as if it still had 7 days to maturity.
+
+Each market applies the **higher** of the two floors.
+
+
+## Liquidation
+
+When a position's Net Balance falls below its Maintenance Margin, it becomes eligible for liquidation. The position is closed at the current mark rate, and a **liquidation penalty** is deducted from the user's remaining collateral:
+
+> Liquidation Penalty = k × Maintenance Margin of Liquidated Position
+
+**k** starts at **25%** when the position first becomes liquidatable (health ratio = 1.0) and scales linearly up to **50%** as the position becomes progressively more distressed. This escalating penalty incentivises liquidators to act promptly and compensates them for taking on the position. **k** figure can change when a market is in distress or when the team deems necessary to adapt to certain situation.
+
+A protocol liquidation fee is also charged on top of the liquidator incentive (see [Fees](/docs/boros-docs/boros-systems/fees.md)).
+
+Margin figures and requirements can differ by markets, check out the market details for specific information on the respective markets.
+
+![Market Info Popup](/boros-docs/imgs/market-info-popup.png "Market Info Popup")