Skip to content

Commit 8cc9c1b

Browse files
olujimiAdebakinolujimiAdebakin
authored
Merge pull request #7 from olujimiAdebakin/feature/baobab-library
Feature/baobab library
2 parents 14589e0 + f9ece72 commit 8cc9c1b

11 files changed

Lines changed: 2111 additions & 142 deletions

File tree

‎docs/architecture/07-mmr.md‎

Lines changed: 207 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,207 @@
1+
# Maintenance Margin Rate (MMR)
2+
3+
## What is MMR?
4+
5+
**MMR is the safety cushion that keeps your position alive.** It's the minimum percentage of your position value you must maintain as collateral to avoid liquidation.
6+
7+
Think of it like this: If you take a 10x leveraged position, you're borrowing 9x from the protocol. MMR ensures there's always enough collateral to cover that debt, even when the market moves against you.
8+
9+
## The Simple Math
10+
11+
### Risk Buffer (What Protects You)
12+
```
13+
Risk Buffer = (1 / Leverage) - MMR
14+
```
15+
16+
**Example:** 10x leverage with 0.5% MMR
17+
- Initial margin: 10% (1/10)
18+
- MMR: 0.5%
19+
- Risk buffer: 10% - 0.5% = **9.5%**
20+
21+
This means the market can move 9.5% against you before liquidation.
22+
23+
### Liquidation Price
24+
25+
**LONG Position:**
26+
```
27+
Liquidation Price = Entry Price × (1 - Risk Buffer)
28+
```
29+
30+
**SHORT Position:**
31+
```
32+
Liquidation Price = Entry Price × (1 + Risk Buffer)
33+
```
34+
35+
## BAOBAB's MMR Tiers
36+
37+
We use different MMR rates based on market risk:
38+
39+
### Tier 1: Global Markets (0.5% MMR)
40+
**Markets:** ETH-USD, BTC-USD, USDT-USD
41+
42+
**Why 0.5%?** These are highly liquid markets with tight spreads and predictable execution. Industry standard that matches Binance, Bybit, and other major platforms.
43+
44+
### Tier 2: African Markets (1.0% MMR)
45+
**Markets:** DANGCEM-NG, MTNN-NG, NGN-USD, GHS-USD
46+
47+
**Why 1.0%?** Lower liquidity, wider spreads, and higher volatility. The extra 0.5% protects both you and the protocol from execution risks unique to emerging markets.
48+
49+
### Tier 3: Event Markets (1.5% MMR)
50+
**Markets:** NIGERIA-ELECTION, CBN-RATE-DECISION
51+
52+
**Why 1.5%?** Binary outcomes create extreme volatility. These markets can gap significantly in seconds.
53+
54+
## Real-World Examples
55+
56+
### Example 1: Trading ETH (0.5% MMR)
57+
58+
**Your Position:**
59+
- Collateral: $10,000
60+
- Leverage: 10x
61+
- Entry: $3,000 ETH
62+
- Direction: LONG
63+
64+
**Calculations:**
65+
- Position size: $100,000
66+
- Risk buffer: 9.5%
67+
- **Liquidation price: $2,715**
68+
69+
The market can drop 9.5% ($285) before liquidation.
70+
71+
### Example 2: Trading Dangote Cement (1.0% MMR)
72+
73+
**Your Position:**
74+
- Collateral: $10,000
75+
- Leverage: 10x
76+
- Entry: ₦500 per share
77+
- Direction: LONG
78+
79+
**Calculations:**
80+
- Position size: $100,000
81+
- Risk buffer: 9.0%
82+
- **Liquidation price: ₦455**
83+
84+
The market can drop 9.0% (₦45) before liquidation. Notice you have 0.5% less buffer due to higher market risk.
85+
86+
## Impact Across Leverage Levels
87+
88+
### Standard Markets (0.5% MMR)
89+
90+
| Leverage | Your Capital | Borrowed | Risk Buffer | Liquidation Move |
91+
|----------|--------------|----------|-------------|------------------|
92+
| 2x | 50% | 50% | 49.5% | -49.5% |
93+
| 5x | 20% | 80% | 19.5% | -19.5% |
94+
| 10x | 10% | 90% | 9.5% | -9.5% |
95+
| 20x | 5% | 95% | 4.5% | -4.5% |
96+
| 50x | 2% | 98% | 1.5% | -1.5% |
97+
98+
### Elevated Risk Markets (1.0% MMR)
99+
100+
| Leverage | Your Capital | Borrowed | Risk Buffer | Liquidation Move |
101+
|----------|--------------|----------|-------------|------------------|
102+
| 2x | 50% | 50% | 49.0% | -49.0% |
103+
| 5x | 20% | 80% | 19.0% | -19.0% |
104+
| 10x | 10% | 90% | 9.0% | -9.0% |
105+
| 20x | 5% | 95% | 4.0% | -4.0% |
106+
| 50x | 2% | 98% | 1.0% | -1.0% |
107+
108+
**Key Insight:** At 50x leverage on African markets, you only have 1% room before liquidation. This is why understanding MMR matters.
109+
110+
## What Does MMR Actually Cover?
111+
112+
The MMR percentage pays for real costs when liquidating a position:
113+
114+
### 0.5% MMR Breakdown (Global Markets)
115+
- **Slippage:** 0.2-0.3% (moving the market when liquidating)
116+
- **Price movement:** 0.1-0.15% (market moves during execution)
117+
- **Oracle differences:** 0.05% (mark price vs actual execution)
118+
- **Execution costs:** 0.05-0.1% (gas, keeper fees)
119+
- **Buffer:** ~0.0% (minimal safety margin)
120+
121+
### 1.0% MMR Breakdown (African Markets)
122+
Everything above **PLUS:**
123+
- **Additional volatility buffer:** 0.5%
124+
- **Lower liquidity premium:** Coverage for wider spreads
125+
- **Market-specific risks:** Off-hours volatility, currency fluctuations
126+
127+
## Why Dynamic MMR?
128+
129+
**Old Way (Static MMR):** One rate for all markets. Either too risky for emerging markets or too expensive for liquid markets.
130+
131+
**BAOBAB's Way (Dynamic MMR):** Match the MMR to actual market conditions.
132+
133+
This lets us:
134+
- Compete with Binance/Bybit on BTC/ETH (0.5%)
135+
- Responsibly pioneer African markets (1.0%)
136+
- Protect users on volatile event derivatives (1.5%)
137+
138+
## How MMR Changes
139+
140+
### Governance Process
141+
1. **Initial Setting:** Protocol team analyzes market data
142+
2. **DAO Voting:** Community can propose changes
143+
3. **Automatic Adjustments:** Based on measured volatility/liquidity
144+
4. **Emergency Override:** Admin can adjust during extreme events
145+
146+
### Automatic Triggers (Example)
147+
```javascript
148+
// If 30-day volatility exceeds 100%, increase MMR
149+
if (volatility30d > 100%) {
150+
increaseMMR(marketId, 0.25%);
151+
}
152+
153+
// If average spread exceeds 0.1%, increase MMR
154+
if (averageSpread > 0.1%) {
155+
increaseMMR(marketId, 0.15%);
156+
}
157+
```
158+
159+
## Technical Implementation
160+
161+
### Decimal Notation
162+
- 0.5% MMR = `0.005` in calculations
163+
- 1.0% MMR = `0.010` in calculations
164+
- In Solidity: `50` (basis points) or `5e15` (wei)
165+
166+
### Smart Contract Structure
167+
```solidity
168+
struct MarketConfig {
169+
bytes32 marketId;
170+
uint16 maintenanceMargin; // 50 = 0.5%, 100 = 1.0%
171+
uint256 maxLeverage;
172+
bool isActive;
173+
}
174+
175+
function calculateLiquidationPrice(
176+
bytes32 marketId,
177+
Side side,
178+
uint256 entryPrice,
179+
uint16 leverage
180+
) external view returns (uint256) {
181+
// Get market-specific MMR
182+
uint256 MMR = getMMR(marketId);
183+
184+
// Calculate risk buffer
185+
uint256 initialMargin = 1e18 / leverage;
186+
uint256 riskBuffer = initialMargin - MMR;
187+
188+
// Return liquidation price based on direction
189+
if (side == LONG) {
190+
return entryPrice * (1e18 - riskBuffer) / 1e18;
191+
} else {
192+
return entryPrice * (1e18 + riskBuffer) / 1e18;
193+
}
194+
}
195+
```
196+
197+
## Bottom Line
198+
199+
**MMR isn't arbitrary—it's calculated insurance.**
200+
201+
- **0.5% for BTC/ETH:** Match global standards, attract volume
202+
- **1.0% for African markets:** Cover real execution risks
203+
- **1.5% for events:** Protect against binary volatility
204+
205+
This tiered approach lets BAOBAB be both **competitively aggressive** on liquid markets and **responsibly conservative** on emerging ones.
206+
207+
The result? You get industry-standard rates where markets support it, and appropriate protection where they don't.

‎foundry.toml‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,11 @@ libs = ["lib"]
88
optimizer = true
99
optimizer_runs = 1000000
1010
via_ir = true
11+
# "settings": {
12+
# "optimizer": { "enabled": true, "runs": 200 },
13+
# "viaIR": true
14+
# }
15+
1116

1217
[rpc_endpoints]
1318
arbitrum = "${ARBITRUM_RPC_URL}"

0 commit comments

Comments
 (0)