mango-explorer/Liquidation.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "eleven-endorsement",
   "metadata": {},
   "source": [
    "# ⚠ Warning\n",
    "\n",
    "THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\n",
    "\n",
    "[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gl/OpinionatedGeek%2Fmango-explorer/HEAD?filepath=Liquidation.ipynb) _🏃‍♀️ To run this notebook press the ⏩ icon in the toolbar above._"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ordered-lincoln",
   "metadata": {},
   "source": [
    "# 🥭 Liquidation\n",
    "\n",
    "**This is incomplete - a Work In Progress. Do not rely on anything in here**\n",
    "\n",
    "Mango Markets margin accounts must hold more assets than liabilities.\n",
    "\n",
    "If a margin account doesn't hold assets worth more than 110% of its liabilities, anyone can 'pay off' some of the liabilities in that account. In return, that payer receives 105% of their tokens back.\n",
    "\n",
    "This process - called '_liquidation_' - continues until the remaining assets are worth more than 120% of the remaining liabilities, or until there are no more collateral tokens to return to liquidators.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "proved-brick",
   "metadata": {},
   "source": [
    "## Collateralisation Ratios\n",
    "\n",
    "When trading with leverage on Mango Markets, you start by adding assets to your margin account. Your margin account must hold assets worth more than 120% of the liabilities. This ratio of assets to liabilities is called your '_collateralisation ratio_'.\n",
    "\n",
    "If a new trade would mean your assets would be worth less 120% of the libilities - that your collateralisation ratio would be less than 120% - you will not be allowed to place the trade. No existing trades are closed, you just can't place any new orders.\n",
    "\n",
    "The value of assets and liabilities is derived from the prices from on-chain oracles.\n",
    "\n",
    "Prices change, so even if no new trades are made the value of assets can fall and the liabilities can increase, changing the collateralisation ratio.\n",
    "\n",
    "**If the collateralisation ratio falls below 110%, your margin account can be '_liquidated_', resulting in the loss of some or a all assets in the account.**\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "geological-throat",
   "metadata": {},
   "source": [
    "## Safety\n",
    "\n",
    "Liquidation is how Mango Markets protects accounts from systemic losses.\n",
    "\n",
    "If the collateralisation ratio were allowed to fall below 100%, that would represent a systemic risk to Mango Markets. Funds would have to be taken from the lending pools, affecting all lenders, which may in turn affect their collateralisation ratio and expose them to liquidation, possibly leading to a cascade of liquidations until the system stabilises.\n",
    "\n",
    "Liquidators promptly stepping in to 'buy' liquidatable accounts before they fall to less than 100% collateralisation prevent this instability.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "sixth-details",
   "metadata": {},
   "source": [
    "# Liquidation Process"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ordered-closer",
   "metadata": {},
   "source": [
    "## Steps\n",
    "\n",
    "The liquidation process involves paying off some or all of one of the liabilities in the under-collateralised margin account. Margin accounts can have liabilities in multiple tokens, but liquidation can only be performed on one token at a time.\n",
    "\n",
    "These are the basic steps to liquidate an account:\n",
    "1. Force cancellation of all outstanding orders for the margin account in that market.\n",
    "2. Build and send the `PartialLiquidate` instruction.\n",
    "3. Repeat step 2 (if necessary) with fresh tokens.\n",
    "\n",
    "But to actually run a liquidator, there are probably some additional steps:\n",
    "1. Find all liquidatable margin accounts.\n",
    "2. Pick the most appropriate of these margin accounts, based on that account's collatoralisation and the liquidator's token balances.\n",
    "3. Pick the market with the most value in the margin account's openorders accounts.\n",
    "4. Force cancellation of all outstanding orders for the margin account in that market.\n",
    "5. Pick the market with the highest borrows and lowest deposits for the account being liquidated.\n",
    "6. Build and send the `PartialLiquidate` instruction.\n",
    "7. Convert the received tokens to your desired tokens.\n",
    "8. Repeat from step 2 (if necessary) with fresh tokens.\n",
    "\n",
    "(This is probably not right - it depends on a polling loop. We'll probably have a websocket connection for prices and accounts. But then again it may apply on a price change.)\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "democratic-therapist",
   "metadata": {},
   "source": [
    "# Running"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "electronic-machine",
   "metadata": {},
   "outputs": [],
   "source": [
    "if __name__ == \"__main__\":\n",
    "    from Context import default_context\n",
    "\n",
    "    print(default_context)\n"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.8.6"
  },
  "toc": {
   "base_numbering": 1,
   "nav_menu": {},
   "number_sections": true,
   "sideBar": true,
   "skip_h1_title": false,
   "title_cell": "Table of Contents",
   "title_sidebar": "Contents",
   "toc_cell": false,
   "toc_position": {},
   "toc_section_display": true,
   "toc_window_display": true
  },
  "varInspector": {
   "cols": {
    "lenName": 16,
    "lenType": 16,
    "lenVar": 40
   },
   "kernels_config": {
    "python": {
     "delete_cmd_postfix": "",
     "delete_cmd_prefix": "del ",
     "library": "var_list.py",
     "varRefreshCmd": "print(var_dic_list())"
    },
    "r": {
     "delete_cmd_postfix": ") ",
     "delete_cmd_prefix": "rm(",
     "library": "var_list.r",
     "varRefreshCmd": "cat(var_dic_list()) "
    }
   },
   "types_to_exclude": [
    "module",
    "function",
    "builtin_function_or_method",
    "instance",
    "_Feature"
   ],
   "window_display": false
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}