# Margin Trading on Burrow
Repo is [here](https://github.com/burrowHQ/burrowland/tree/accumulated-updates).
## Basic Concepts
### Open Position
There are <**baseToken**, **quoteToken**> pairs, and margin users can establish margin positions agianst them.
For example, let's take <near, usdc> as the pair, and the near price is now 5 usdc.
Alice is now creating her margin position to long near:
1. She puts 100 usdc in as collateral, collateral value (CV) is 100 usd;
2. She borrows 300 usd valued usdc (leverage rate: 3) to buy near on ref dex, debt value (DV) is 300 usd;
3. She buys 60 near. the position token, the position value (PV) is 300 usd;

All 3 steps above is a long position creation process, which the protocol will ensure in one TX. And these 3 assets (collateral, dbet, position) will all be locked in one margin position structure, can NOT be withdraw or used for other purpose.

On the contrary, for a short position, it looks like:
- collateral asset is quoteToken,
- debt asset is baseToken,
- position asset is quoteToken.

In summary, in a position, we have following elements:
- $CV$ = **collateral value**,
It's user's margin, always in the form of quote token;
- $PV$ = **position value**,
It is base token for long positions, quote token for short positions;
- $DV$ = **debt value**,
It is what the user borrowed from the protocol, quote token for long positions and base token for short positions;
- $X=\frac{DV}{CV}$, is the current leverage rate.
- $PnL=PV-DV$, where $PV$ and $DV$ are under current market condition.

### Close Position
Once the market goes along the user's expectation, he can close the position to realise the profit.
Once the market goes in the opposite direction, the user can also close the position to prevent further loss.
To colse a position, a user would:
- sell **position** asset to debt asset;
- sell **collateral** asset to debt asset if necessary;
- repay all **debt** in the margin position;
- the margin position removed,
- the user gets remaining collateral back;
- the user gets remaining position asset as profit;

All steps above is ensured by the protocol to be in one TX.

## About Fee and Interests
### Open Fee
Open fee is proportional to collateral token amount, and will be charged once the position is successfully established.
Open fee rate is configured protocol-wise, and effective to all positions.
### Holding Position Fee
Holding position fee is calculated at runtime on the debt token along the time. It looks like an additional part of the debt in the margin position.
Holding position fee rate is subject to each debt asset, so can be configured independently on each asset.
### Borrow Interest
The debt in the margin position also has a borrow interest.
Generally, it shares the same borrow rate with regular debt, but there is a protocol-wide margin debt discount that can be configured to reduce some interests for margin users.

## About ForceClose and Liquidation

### ForceClose
For a margin position, $CV+PV$ is what it has, $DV$ is what it owes.
Apparently, when $CV+PV<DV$, the position should be force closed:
$$ForceCloseFactor = \frac{DV}{CV+PV}$$
If $ForceCloseFactor>1$, the position should be force closed:
- sell position token to debt token,
- sell collateral token to debt token if necessary,
- repay debt in the position,
- repay remainning debt using the reserve pool of the debt asset,
- the position is then force closed.

All steps above is ensured by the protocol to be in one TX.

### Liquidation
Define $S$ as a discount on $(CV+PV)$, then:
$$ LiqFactor = \frac{DV}{(1-S)(CV+PV)} $$,
If $LiqFactor>1$, the position can be fully liquidated:
- sell position token to debt token,
- sell collateral token to debt token if necessary,
- repay all debt in the position,
- the liquidator and the protocol share the remaining assets in the position,
- the position is then liquidated and colsed.

All steps above is ensured by the protocol to be in one TX.
For example, if we set $S=10\%$, then, the following table shows the liquidation conditions under different market price fluctuation situations:
*Assuming the open price is 1.0*
|LeverageX|liq on Long|force on Long|liq on Short|froce on Short|
|--|--|--|--|--|
|2|0.6111|0.5|1.35|1.5|
|3|0.7778|0.6667|1.2|1.3333|
|4|0.8611|0.75|1.125|1.25|
|5|0.9111|0.8|1.08|1.2|

if S=0.15
|LeverageX|liq on Long|force on Long|liq on Short|froce on Short|
|--|--|--|--|--|
|2|0.6765|0.5|1.275|1.5|
|3|0.8431|0.6667|1.1333|1.3333|
|4|0.9265|0.75|1.0625|1.25|
|5|0.9765|0.8|1.02|1.2|

if S=0.20
|LeverageX|liq on Long|force on Long|liq on Short|froce on Short|
|--|--|--|--|--|
|2|0.75|0.5|1.2|1.5|
|3|0.9167|0.6667|1.0667|1.3333|

if S=0.25
|LeverageX|liq on Long|force on Long|liq on Short|froce on Short|
|--|--|--|--|--|
|2|0.8333|0.5|1.125|1.5|

Note: Fees and interests are not considered here for simplicity.

## Trail Enviroment
We have already established a triail version on mainnet. It is composed of an uniformed frontend and two independent smart contract sets. One for <Near, Usdc> pair on Private mainnet burrow system and the other for <Meme, Usdc> pairs on Meme burrow system.

### Frontend and backends
The uniformed frontend is [here](https://margin.burrow.finance/).
Contract IDs for Meme Burrow:
- burrow: `meme-burrow.ref-labs.near`
- oracle: `meme-priceoracle.ref-labs.near`

Contract IDs for Private Burrow:
- burrow: `burrow.private-mainnet.ref-dev-team.near`
- oracle: `pyth-oracle.near`

### Register Whitelist
The trail enviroment is limited to manipulate by a whitelist, (but fully free to view). Please send email with your near account to [Marco](mailto:[e-mail]), [Zero](mailto:[e-mail]) or [Willa](mailto:[e-mail]) for whitelist registration.

### liquidation bot
Repo is [here](https://github.com/burrowHQ/burrowland-liquidation-bot/tree/margin_trading_crypto_v3)
Check out the readme file and corresponding examples for usage instruction.
And also check out the following Appendix for margin router files need when you want to participate in margin position liquidation and forceclose.

# Appendix

## safety buffer $S$ and leverage rate $l$

we have liquidation threshold:
$$ DV = (1 - S)(CV + PV) $$,
Consider $DV=l*CV$, then:
$$ DV = (1-S)(\frac{DV}{l} + PV) $$

### For opening a long position
we have $PV=DV$ at opening time and then $PV=x*DV$ if $x$ is the current base token price (assume price equals 1.0 at opening time).
Then, liquidation threshold goes:
$$ DV = (1-S)(\frac{DV}{l} + x*DV) $$
That is:
$$ 1 = (1-S)(1/l + x) $$

### For opening a short position
we have $PV=DV$ at opening time and then $DV=x*PV$ if $x$ is the current base token price (assume price equals 1.0 at opening time).
Then, liquidation threshold goes:
$$ x*PV = (1-S)(\frac{PV}{l} + PV) $$
That is:
$$ x = (1-S)(1 + 1/l) $$

## Margin Router for <near, usdc> pair on Private
private_margin_router.json

{
  "17208628f84f5d6ad33f0da3bbbeb27ffcb398eac501a31bd6ad2011e36133a1&wrap.near": {
    "dex_type": 1,
    "dex_id": "v2.ref-finance.near",
    "pool_ids": ["5515|17208628f84f5d6ad33f0da3bbbeb27ffcb398eac501a31bd6ad2011e36133a1|wrap.near"]
  }, 
  "wrap.near&17208628f84f5d6ad33f0da3bbbeb27ffcb398eac501a31bd6ad2011e36133a1": {
    "dex_type": 1,
    "dex_id": "v2.ref-finance.near",
    "pool_ids": ["5515|wrap.near|17208628f84f5d6ad33f0da3bbbeb27ffcb398eac501a31bd6ad2011e36133a1"]
  }
}

## Margin Router for <meme, usdc> pair on Meme
meme_margin_router.json

{
  "17208628f84f5d6ad33f0da3bbbeb27ffcb398eac501a31bd6ad2011e36133a1&token.burrow.near": {
    "dex_type": 1,
    "dex_id": "v2.ref-finance.near",
    "pool_ids": [
      "5515|17208628f84f5d6ad33f0da3bbbeb27ffcb398eac501a31bd6ad2011e36133a1|wrap.near",
      "3474|wrap.near|token.burrow.near"
    ]
  },
  "token.burrow.near&17208628f84f5d6ad33f0da3bbbeb27ffcb398eac501a31bd6ad2011e36133a1": {
    "dex_type": 1,
    "dex_id": "v2.ref-finance.near",
    "pool_ids": [
      "3474|token.burrow.near|wrap.near",
      "5515|wrap.near|17208628f84f5d6ad33f0da3bbbeb27ffcb398eac501a31bd6ad2011e36133a1"
    ]
  },

  "17208628f84f5d6ad33f0da3bbbeb27ffcb398eac501a31bd6ad2011e36133a1&blackdragon.tkn.near": {
    "dex_type": 1,
    "dex_id": "v2.ref-finance.near",
    "pool_ids": [
      "5515|17208628f84f5d6ad33f0da3bbbeb27ffcb398eac501a31bd6ad2011e36133a1|wrap.near",
      "4276|wrap.near|blackdragon.tkn.near"
    ]
  },
  "blackdragon.tkn.near&17208628f84f5d6ad33f0da3bbbeb27ffcb398eac501a31bd6ad2011e36133a1": {
    "dex_type": 1,
    "dex_id": "v2.ref-finance.near",
    "pool_ids": [
      "4276|blackdragon.tkn.near|wrap.near",
      "5515|wrap.near|17208628f84f5d6ad33f0da3bbbeb27ffcb398eac501a31bd6ad2011e36133a1"
    ]
  },

  "17208628f84f5d6ad33f0da3bbbeb27ffcb398eac501a31bd6ad2011e36133a1&token.lonkingnearbackto2024.near": {
    "dex_type": 1,
    "dex_id": "v2.ref-finance.near",
    "pool_ids": [
      "5515|17208628f84f5d6ad33f0da3bbbeb27ffcb398eac501a31bd6ad2011e36133a1|wrap.near",
      "4314|wrap.near|token.lonkingnearbackto2024.near"
    ]
  },
  "token.lonkingnearbackto2024.near&17208628f84f5d6ad33f0da3bbbeb27ffcb398eac501a31bd6ad2011e36133a1": {
    "dex_type": 1,
    "dex_id": "v2.ref-finance.near",
    "pool_ids": [
      "4314|token.lonkingnearbackto2024.near|wrap.near",
      "5515|wrap.near|17208628f84f5d6ad33f0da3bbbeb27ffcb398eac501a31bd6ad2011e36133a1"
    ]
  },

  "17208628f84f5d6ad33f0da3bbbeb27ffcb398eac501a31bd6ad2011e36133a1&ftv2.nekotoken.near": {
    "dex_type": 1,
    "dex_id": "v2.ref-finance.near",
    "pool_ids": [
      "5515|17208628f84f5d6ad33f0da3bbbeb27ffcb398eac501a31bd6ad2011e36133a1|wrap.near",
      "3807|wrap.near|ftv2.nekotoken.near"
    ]
  },
  "ftv2.nekotoken.near&17208628f84f5d6ad33f0da3bbbeb27ffcb398eac501a31bd6ad2011e36133a1": {
    "dex_type": 1,
    "dex_id": "v2.ref-finance.near",
    "pool_ids": [
      "3807|ftv2.nekotoken.near|wrap.near",
      "5515|wrap.near|17208628f84f5d6ad33f0da3bbbeb27ffcb398eac501a31bd6ad2011e36133a1"
    ]
  },

  "17208628f84f5d6ad33f0da3bbbeb27ffcb398eac501a31bd6ad2011e36133a1&token.0xshitzu.near": {
    "dex_type": 1,
    "dex_id": "v2.ref-finance.near",
    "pool_ids": [
      "5515|17208628f84f5d6ad33f0da3bbbeb27ffcb398eac501a31bd6ad2011e36133a1|wrap.near",
      "4369|wrap.near|token.0xshitzu.near"
    ]
  },
  "token.0xshitzu.near&17208628f84f5d6ad33f0da3bbbeb27ffcb398eac501a31bd6ad2011e36133a1": {
    "dex_type": 1,
    "dex_id": "v2.ref-finance.near",
    "pool_ids": [
      "4369|token.0xshitzu.near|wrap.near",
      "5515|wrap.near|17208628f84f5d6ad33f0da3bbbeb27ffcb398eac501a31bd6ad2011e36133a1"
    ]
  },

  "17208628f84f5d6ad33f0da3bbbeb27ffcb398eac501a31bd6ad2011e36133a1&gear.enleap.near": {
    "dex_type": 1,
    "dex_id": "v2.ref-finance.near",
    "pool_ids": [
      "5515|17208628f84f5d6ad33f0da3bbbeb27ffcb398eac501a31bd6ad2011e36133a1|wrap.near",
      "3411|wrap.near|gear.enleap.near"
    ]
  },
  "gear.enleap.near&17208628f84f5d6ad33f0da3bbbeb27ffcb398eac501a31bd6ad2011e36133a1": {
    "dex_type": 1,
    "dex_id": "v2.ref-finance.near",
    "pool_ids": [
      "3411|gear.enleap.near|wrap.near",
      "5515|wrap.near|17208628f84f5d6ad33f0da3bbbeb27ffcb398eac501a31bd6ad2011e36133a1"
    ]
  },

  "17208628f84f5d6ad33f0da3bbbeb27ffcb398eac501a31bd6ad2011e36133a1&purge-558.meme-cooking.near": {
    "dex_type": 1,
    "dex_id": "v2.ref-finance.near",
    "pool_ids": [
      "5515|17208628f84f5d6ad33f0da3bbbeb27ffcb398eac501a31bd6ad2011e36133a1|wrap.near",
      "5650|wrap.near|purge-558.meme-cooking.near"
    ]
  },
  "purge-558.meme-cooking.near&17208628f84f5d6ad33f0da3bbbeb27ffcb398eac501a31bd6ad2011e36133a1": {
    "dex_type": 1,
    "dex_id": "v2.ref-finance.near",
    "pool_ids": [
      "5650|purge-558.meme-cooking.near|wrap.near",
      "5515|wrap.near|17208628f84f5d6ad33f0da3bbbeb27ffcb398eac501a31bd6ad2011e36133a1"
    ]
  },

  "17208628f84f5d6ad33f0da3bbbeb27ffcb398eac501a31bd6ad2011e36133a1&abg-966.meme-cooking.near": {
    "dex_type": 1,
    "dex_id": "v2.ref-finance.near",
    "pool_ids": [
      "5515|17208628f84f5d6ad33f0da3bbbeb27ffcb398eac501a31bd6ad2011e36133a1|wrap.near",
      "5720|wrap.near|abg-966.meme-cooking.near"
    ]
  },
  "abg-966.meme-cooking.near&17208628f84f5d6ad33f0da3bbbeb27ffcb398eac501a31bd6ad2011e36133a1": {
    "dex_type": 1,
    "dex_id": "v2.ref-finance.near",
    "pool_ids": [
      "5720|abg-966.meme-cooking.near|wrap.near",
      "5515|wrap.near|17208628f84f5d6ad33f0da3bbbeb27ffcb398eac501a31bd6ad2011e36133a1"
    ]
  }
}