GitBook: [master] 18 pages modified

SUMMARY.md

@@ -27,7 +27,12 @@
 ## Mango V3
 
 * [Overview](mango-v3/overview.md)
-* [Liquidity Incentives](mango-v3/liquidity-incentives.md)
+* [Health](mango-v3/health.md)
+* [Liquidity Mining](mango-v3/liquidity-incentives.md)
 * [Market Making Bot \(python\)](mango-v3/market-making-bot-python.md)
 * [Mango Client API \(javascript\)](mango-v3/mango-client-api-javascript.md)
 
+## Key Concepts
+
+* [Untitled](key-concepts/untitled-1.md)
+

key-concepts/untitled-1.md

@@ -0,0 +1,2 @@
+# Untitled
+

mango-v3/health.md

@@ -0,0 +1,2 @@
+# Health
+

mango-v3/liquidity-incentives.md

@@ -1,4 +1,4 @@
-# Liquidity Incentives
+# Liquidity Mining
 
 ## Overview
 
@@ -13,13 +13,20 @@ near touch - best bid if the order is a bid, best ask if order is an ask
 best_initial - near touch when the order was placed
 best_final - near touch when the order was canceled
 time_initial - unix timestamp in seconds of when order was placed
-time_final - unix timestamp in seconds of when order was placed
+time_final - unix timestamp of when order is being executed/canceled
 
 max_depth_bps - the maximum depth behind near touch the program will reward
-scaler - some scaling constant
 price - the price of the order
-*/
 
+target_period_length - this is a param set by admin; It's how often we want
+    rate adjustments. Analogous to Bitcoin difficulty adjustment period of 2 weeks
+    
+mngo_per_period - How much MNGO to award per period. This is the threshold 
+    to determine when a period ends.
+    
+rate - this is the conversion MNGO per point. It's valid until mngo_per_period MNGO
+    is paid out. Then the rate adjusts. 
+*/
 
 let best = if order.is_bid {
     max(best_initial, best_final)
@@ -31,19 +38,40 @@ let dist_bps = abs(price - best) * 10000 / best;
 let reverse_dist = max(max_depth_bps - dist_bps, 0);
 let time_on_book = time_final - time_initial;
 
-let points = reverse_dist * reverse_dist * time_on_book * quantity * scaler
+let points = reverse_dist * reverse_dist * time_on_book * quantity
 
+let points_in_period = mngo_left_in_period * rate
+
+let mngo_earned = 0;
+
+// Check if this puts us over period threshold; If so rate adjust
+if points >= points_in_period {
+    user.mngo_accrued += mngo_left_in_period;
+    points -= points_in_period;
+    
+    // There's no more MNGO for this period
+    // Adjust rate (difficulty adjustment) and start new period
+    let rate_adj = clamp((time_final - period_start) / target_period_length, 1/4, 4);
+    rate = rate * rate_adj;
+    period_start = time_final;
+    mngo_left_in_period = mngo_per_period;
+}
+
+// Convert points to MNGO and award to user; limit to mngo_per_period
+mngo_earned = min(points * rate, mngo_per_period)
+mngo_left_in_period -= mngo_earned
+user.mngo_accrued += mngo_earned
 ```
 
-## Conversion
+## Explanation
 
-Liquidity points earned in the `MangoAccount` can be converted to MNGO at some rate. This piece has not yet been completed.
+This mechanism was inspired by the Bitcoin block rewards and difficulty mining adjustments that happen every 2016 blocks. In Bitcoin the target for 2016 blocks is 2 weeks. If it took longer than 2 weeks, then difficulty is adjusted down proportional to the time. If it took less than 2 weeks, difficulty is adjusted up. Similarly, we have a target time of 1 hour with a reward of 5,000 MNGO \(still TBD\). When 5000 MNGO is distributed in a period, the time it took is compared against the target time of 1 hour. The rate is adjusted down if it took less then 1 hour and it's adjusted down if it took more than 1 hour.
 
 ## Motivation
 
 This formula comes out of the intersection of our goals and technical limitations. Here are the goals:
 
-* trustless and decentralized - should work even if the Mango team disappears
+* trustless and decentralized - should work even if initial devs disappear
 * open and transparent - no special market maker agreements
 * liquidity - tight spread, thick book that rivals centralized exchanges, even if volume is low
 * easy to access - deploying the mango markets reference market maker should be profitable 

mango-v3/overview.md

@@ -7,6 +7,16 @@ description: >-
 
 # Overview
 
+## What?
+
+Mango v3 is designed to make life easier for market participants. Towards that end, Mango v3 will have these features:
+
+* Up to 16 different tokens to borrow, lend or margin trade with on Serum DEX
+* Up to 16 different perp contracts with leverage up to 10x initially
+* Plans to expand to 50+ markets and tokens after some anticipated Solana upgrades
+* All token deposits and perp positions are used as collateral by default
+* All the features of Solana, Serum and Mango v2
+
 ## Health
 
 The health of an account is used to determine if one can open a new position or if one can be liquidated. There are two types of health, initial health used for opening new positions and maintenance health used for liquidations. They are both calculated as a weighted sum of the assets minus the liabilities but the maint. health uses slightly larger weights for assets and slightly smaller weights for the liabilities. Zero is used as the bright line for both i.e. if your init health falls below zero, you cannot open new positions and if your maint. health falls below zero you will be liquidated. They are calculated as follows:
@@ -42,6 +52,32 @@ Suppose the BTC-PERP mark price moves to $9400, then:
 
 Since the maint\_health is below zero, this account can be liquidated until init health is above zero.
 
+## Liquidations
+
+Every `MangoAccount` must have a `maint_health` above zero. If it slips below zero, liquidators can start liquidating the account until the `init_health` is above zero. The liquidator may forcibly cancel all open orders and start paying off liabilities in the account and withdrawing the assets \(defined as positive perp balances or token deposits\) in the account. The liquidator earns the `liquidation_fee` which 
+
+If, at the end of a Liquidate instruction the account has no more assets , but still has liabilities, then the account is placed under bankruptcy. During bankruptcy, the liquidator continues offsetting liabilities, but receives USDC from the insurance fund. Finally, if there is no more USDC in the insurance fund, there will be a socialize loss event \(described below\). There are seven liquidation related instructions that can be called on Mango V3:
+
+* ForceCancelSpotOrders
+* ForceCancelPerpOrders
+* LiquidateTokenAndToken
+* LiquidateTokenAndPerp
+* LiquidatePerpMarket
+* ResolveTokenBankruptcy
+* ResolvePerpBankruptcy
+
+## Insurance Fund
+
+The Mango program will have some portion of the Mango DAO treasury as the insurance fund. When there are bankrupt accounts, the insurance fund will pay off losses incurred by token lenders or perps contract participants. 
+
+## Socialized Losses
+
+If an account still has liabilities but no more assets for liquidators to take, the account is bankrupt and insurance fund starts paying. Socialized loss only kicks in after the insurance fund owned by Mango v3 is depleted. We hope this is a rare event. 
+
+For losses among token borrowers \(i.e. margin traders\), socialized loss works the same way it works in V2. That is, the amount of the token borrow is disappears and that amount is subtracted proportionally from all depositors.
+
+For losses among perp market participants, the losses are spread equally among all other participants in that perp market.
+
 ## Settle Pnl
 
 In order to get USDC realized profits from unrealized profits on a perp contract, the trader must settle his profits by finding account\(s\) that have equivalent losses on the same contract and call the `SettlePnl` instruction on chain.