{"id":26054951,"url":"https://github.com/morpho-org/morpho-blue-lltv-recommendation","last_synced_at":"2025-09-10T10:41:12.976Z","repository":{"id":223516158,"uuid":"670725334","full_name":"morpho-org/morpho-blue-lltv-recommendation","owner":"morpho-org","description":null,"archived":false,"fork":false,"pushed_at":"2024-02-22T13:21:02.000Z","size":1765,"stargazers_count":2,"open_issues_count":2,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-06-02T18:20:18.107Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/morpho-org.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2023-07-25T17:32:25.000Z","updated_at":"2024-02-20T15:15:07.000Z","dependencies_parsed_at":"2024-02-22T14:43:14.951Z","dependency_job_id":null,"html_url":"https://github.com/morpho-org/morpho-blue-lltv-recommendation","commit_stats":null,"previous_names":["morpho-org/morpho-blue-lltv-recommendation"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/morpho-org/morpho-blue-lltv-recommendation","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/morpho-org%2Fmorpho-blue-lltv-recommendation","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/morpho-org%2Fmorpho-blue-lltv-recommendation/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/morpho-org%2Fmorpho-blue-lltv-recommendation/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/morpho-org%2Fmorpho-blue-lltv-recommendation/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/morpho-org","download_url":"https://codeload.github.com/morpho-org/morpho-blue-lltv-recommendation/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/morpho-org%2Fmorpho-blue-lltv-recommendation/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":274447941,"owners_count":25287116,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-10T02:00:12.551Z","response_time":83,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-03-08T10:00:31.889Z","updated_at":"2025-09-10T10:41:12.904Z","avatar_url":"https://github.com/morpho-org.png","language":"Jupyter Notebook","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Morpho Blue \u003c\u003e Gauntlet Risk Tool \nGauntlet has developed a risk tool to allow potential lenders to Morpho Blue decide on a LLTV that suits their risk appetite. This tool comes in the form of a Python script that anyone can run on their own local machine. Simply run the following command:\n```bash\npython main.py --collateral {symbol or address} --borrow {token symbol or address}\n```\nFor instance, for a WETH collateral, USDC borrow market, we would run the following command:\n```\n# Using symbols\npython main.py --collateral weth --borrow usdc\n# Using addresses\npython main.py --collateral 0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2 --borrow 0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48\n```\nSee the Usage section below for further details on customizing the the risk tool parameters.\n\n*If any questions, please reach out to @gauntlet_xyz on Twitter.*\n\n## Contents\n1. Background\n1. Problem Statement\n1. Market Risk Factors\n1. Risk Tool Methodology\n1. Dependencies\n1. Installation\n1. Usage\n1. Disclaimer\n\n## Background\n\nMorpho Blue is lending protocol that consists of independent lending \"markets\". Each market is defined by:\n- a borrowable asset\n- a collateral asset\n- price feeds for the borrowable and collateral assets\n- a set of allowable liquidation loan-to-value parameters for lenders and borrowers to choose from\n\nBorrowers and lenders decide which LLTV tranche to borrow or supply into when they participate in a market.\n    \n### Liquidation Example\nSuppose we have a WETH collateral/USDC borrow market with a $0.75$ LLTV tranche. Larry (a lender) supplies $\\textdollar 100$ USDC into this $0.75$ LLTV tranche. Bob (a borrower) also wants to borrow from the $0.75$ LLTV tranche and supplies $\\textdollar 100$ WETH collateral to borrow $\\textdollar 60$ USDC. At this point, his LTV is $0.6$.\n\nIf the price of WETH drops by $20\\\\%$, Bob's collateral will be worth $\\textdollar 80$. Bob can now be liquidated as his loan to value ratio has hit his LLTV: $\\frac{\\text{Bob's debt}}{\\text{Bob's collateral}} = \\frac{60}{80} = 0.75$.\n\n\n\n## Problem Statement\nFor lenders entering a specific lending pair market on Morpho Blue, determining a suitable liquidation loan-to-value for their supply position can be a complex decision process. Different LLTV settings across different lending pair markets can lead to very different risk profiles. Our public tool aims to assist in this decision-making process by running simulations under various LLTV settings and price drawdown scenarios. Ultimately, **our tool will provide a recommended LLTV** according to a lender's assumptions about the sort of market downturns they want their position to remain solvent throughout.\n\n\n## Market Risk Factors\nWhat risk do users take on by borrowing or lending in Morpho Blue?\n\n### Borrower's Perspective\nAs with all lending protocols, borrowers face **liquidation risk**: if the ratio of their debt to collateral increases, such that it exceeds their chosen liquidation loan-to-value (LLTV), their entire borrow position may be liquidated. This can happen due to the value of their collateral declining and/or the value of their debt increasing. Careful management of a user's LTV is essential to keep their position safe from liquidations. Borrowers can actively manage their borrow position's health by depositing additional collateral or repaying a portion of their debt. These proactive measures build a buffer between their LTV and LLTV to avoid liquidation under adverse market conditions.\n\n### Lender's Perspective\nLenders in Morpho Blue face the risk of **bad debt**. Unlike borrowers who can mitigate their liquidation risk with careful account management, lenders are at the mercy of the market and may realize losses if borrowers in their tranche end up with undercollateralized borrow positions. Such a situation arises when a liquidation leaves a borrower with remaining debt but no collateral to back it. This is often referred to as bad debt or undercollateralized debt.\n\nWhen bad debt is generated in the aftermath of a liquidation, it is immediately accounted for as a loss by being proportionally distributed among all lenders in the affected tranche. By resolving the bad debt as it is accrued, the negative impact is confined to the present lenders.\n\n### Bad Debt Example\nSuppose we have a WETH collateral, USDC borrow lending market with the following:\n- Lenders Alice and Bob, and a borrower Eve are all in the $80\\\\%$ LLTV tranche.\n- The liquidation incentive is $10\\\\%$\n- Lenders Alice and Bob have both supplied $\\textdollar 100$ USDC each in this market and are the only suppliers in this tranche.\n- Borrower Eve provides $\\textdollar 200$ WETH in collateral to borrow $\\textdollar 160$ USDC. \n\nIf the value of WETH drops such that the value of Eve's collateral is worth $\\textdollar 165$. At this point, Eve's LTV is $\\frac{160}{165} = 0.969$, which is larger than her LLTV. This means she is eligible to be liquidated. A liquidator can repay $\\textdollar 150$ USDC of her debt to claim $\\textdollar 150 \\times (1 + 0.1) = \\textdollar 165$. At the end of this liquidation, Eve will have $\\textdollar 0$ in collateral and $\\textdollar 10$ in debt. Since this debt is undercollateralized, the debt is realized instantaneously and split between Alice and Bob equally since they both supplied the same amount to begin with. Their supply positions are now worth $\\textdollar 95$ USDC.\n\n### How Does Bad Debt Arise?\nBad debt accrues when a borrower has some amount of debt that is backed by 0 collateral.  An undercollateralized borrow position primarily stems from liquidations not occuring in a timely manner. Ideally, if the price of the collateral asset ever suffers a large price drop, liquidators would act swiftly to repay the borrower's debt and claim collateral once a borrower is eligible for liquidation, before the loan to value of the position reaches insolvency territory. Delays in liquidation can occur due to:\n\n**High Slippage on Borrow Asset or Collateral Asset Buy/Sells**\n- Liquidators may incur excessive slippage costs when\n    - buying the borrow asset (to repay the debt)\n    - or selling the collateral asset.\n If the slippage amount plus any transaction/gas fees is larger than the liquidation bonus, they likely will not liquidate a borrow position as it is no longer profitable to do so. If the collateral asset continues to decline in value (or conversely, the borrow asset increases in value), the borrow position will get closer to becoming undercollateralized and ultimately accrue bad debt.\n\n**Narrow Healthy Liquidation Window**\nIn a lending market, having a high LLTV (ex: $95\\\\%$ or higher) can create scenarios where the opportunity window for safe or \"healthy\" liquidations is extremely limited. If liquidators miss this brief opportunity, subsequent price changes can guarantee that liquidations result in bad debt.\n\nConsider an example involving a WETH/USDC lending market with a $97\\\\%$ LTV tranche and a $2\\\\%$ liquidation incentive. Here's what might happen:\n- A borrower supplies $100 WETH as collateral and borrows $97 USDC.\n- If the value of WETH drops, and the collateral is suddenly worth $\\textdollar 98.5$, an optimal liquidator could repay $\\frac{\\textdollar 98.5}{1.02} = \\textdollar 96.57$ to claim the entire $\\textdollar 98.5$ of WETH collateral.\n- This leaves $\\textdollar 0.43$ USDC debt unbacked, leading to bad debt accrual.\n\nThe above scenario illustrates how a high LTV ratio can create a very narrow window for healthy liquidations. In this example, a mere $1.06\\\\% = (1 - \\frac{LLTV}{1 + LI}) \\times 100\\\\%$ price buffer exists before bad debt is guaranteed, which is an incredibly tight margin. Given that the daily price of WETH/USDC often changes by more than $1.06\\\\%$, lenders in such a market should probably opt for a more conservative LTV tranche.\n\n\n\n\n## Risk Tool Methodology\nThis risk tool performs a simulation to assess the potential for bad debt within specific each potential LLTV tranche in a given collateral/borrow market. This simulation method models the behavior of a concentrated borrow position, examining how changes in the ratio of collateral asset to debt asset price might lead to insolvency or liquidation.\n\nIn essence, the risk tool recreates a dynamic market environment where it:\n- Initiates a concentrated borrow position: Reflecting certain market behaviors and conditions.\n- Manipulates the collateral-to-debt ratio, gradually decreasing this ratio at each time step, driving the account closer to insolvency.\n- Implements liquidation when applicable: When the account reaches a state where liquidation is justified, the tool liquidates part of the debt progressively.\n\n\n\n1. **Concentrated Borrow Position**\n\nThe simulation begins with the assumption of one concentrated borrower. This initial collateral position size is determined based on various factors about the collateral asset. In the current state of the tool, we set this position size slightly differently based on the specific lending market under consideration:\n- for larger market cap token markets: the larger of $\\textdollar 200$ million, the size of a $25\\\\%$ slippage sell order\n- for smaller market cap token markets: the larger of $\\textdollar 50$ million, the size of a $25\\\\%$ slippage sell order\n\nWe assume that the borrower takes out as much loan as the input LLTV allows (ex: if the LLTV under consideration is $0.80$, then the simulation sets the borrow amount to be $80\\\\%$ of the initial collateral).\n\n2. **Simulation Time Step**\n\nAfter we have initialized the concentrated borrow position, we proceed with simulation. At each timestep of the simulation, we apply:\n- **a constant percentage price decrease**: At each time step, a constant percentage decrease ($0.5\\\\%$) is applied to the ratio of the collateral asset to debt asset to bring the borrow position closer towards liquidations and insolvency. We set the max drawdown based on the 99th percentile monthly price drawdown.\nEx: If the ratio of the collateral asset to debt asset prices starts the month at 1.0 and reaches a minimum ratio of 0.5 at some point within a 30 day period, its maximum monthly percent drawdown is $50\\\\%$. Other time periods other than 1 month may be used, but typically, the distribution remains relatively unchanged beyond a 2-week horizon.\nSpecifically, we use:\n- for larger market cap token markets: the larger of $40\\\\%$ and the 99th percentile of monthly price drawdowns\n- for smaller market cap token markets: the larger of $60\\\\%$ and the 99th percentile of monthly price drawdowns\nThis drawdown parameter can be increased or decreased to suit the users' risk appetite. For instance, a more risk averse user may want to consider a larger price drawdown and set this parameter to say $0.7$ instead.\n\n- **liquidate a portion of the borrow position:** At the given timestep, if the borrower's debt to collateral ratio (LTV) is above their LLTV, we liquidate a portion of their position.\nWe repay an amount equal to the $0.5\\\\%$ price impact swap size of the collateral asset or borrow asset (whichever is smaller) as computed through CowSwap.\n\nEach of the parameters specified thus far is a parameter that the user can also input into the risk tool so as to conform to the assumptions they want to bake into the simulation. User can specify their chosen parameters through CLI arguments as we will demonstrate in the subsequent section.\n\n3. **Simulation Termination**\n\nThe simulation stops when the borrower has no more collateral, no more debt, or we have reached the maximum iteration count. Any undercollateralized debt that remains at the end of the simulation is insolvent debt.\n\nWe run this simulation LLTV values in the set: $\\\\{0.01, 0.02, \\ldots, 0.98, 0.99\\\\}$. The tool/script will recommend the largest LLTV value that incurs zero bad debt in these simulations.\n\n\n### Parameters \nA key feature of this risk tool is that users can customize all input parameters to tailor the simulation to their unique needs and adapt to current market conditions. The settings for the initial collateral position, repay amount, percent decrease, and max drawdown have been chosen based on extensive experimentation but might not be optimal under different market conditions.\n\n\n- `initial_collateral_usd`: The initial value of the whale collateral position, determined heuristically based on market cap size.\n- `repay_amount_usd`: The amount of USD being repaid at each time step if the account is liquidatable.\n- `max_drawdown`: The largest allowed decrease in collateral value during the simulation.\n- `pct_decrease`: Proportion to decrease the collateral price by at each time step. The default value is $0.005$.\n- `min_liq_bonus`: The minimum liquidation bonus. Currently the liquidation incentive(bonus) is determined by the formula:\n    $$LI  = \\min\\big(M, \\frac{1}{\\beta \\times LLTV + (1-\\beta)} - 1\\big)\n$$ \n    In some cases, the resulting liquidation incentive may be too small (ex: less than $1\\%$), so we ensure that the liquidation bonus is no smaller than this value:\n    $$LI  = \\max(\\min\\big(M, \\frac{1}{\\beta \\times LLTV + (1-\\beta)} - 1\\big), \\text{min liq bonus}).$$\n    \n## Dependencies\n### Data Dependencies\nThe risk tool uses data from the following APIs:\n- [**CoinGecko**](https://www.coingecko.com/en/api): for historical price data of the collateral and borrow assets of a lending market\n- [**CowSwap**](https://docs.cow.fi/off-chain-services/api): for price impact swap sizes (ex: what is the size of swap from token `X` to `Y` that incurs roughly $0.5\\\\%$ price impact?)\n\n### Library Dependencies\nThe risk tool is intended to have minimal dependencies. The main software dependencies are standard libraries from the scientific computing/data science ecosystem such as\n- Pandas\n- NumPy\n- matplotlib.\n\nSee the `requirements.txt` file in the repo for more details.\n\n## Installation\nClone the respository and run the setup script like so:\n```\ngit clone https://github.com/GauntletNetworks/morpho\nsh setup.sh\n```\nThe setup script will create a python virtual environment and install the requirements.\n\n## Usage\nThe risk tool is provided as a python script in this repository. To see all the parameters, run the following:\n```bash\n~/morpho:~$ python main.py --help\nusage: main.py [-h] [-b BORROW] [-c COLLATERAL] [--pct_decrease PCT_DECREASE] [--initial_collateral_usd INITIAL_COLLATERAL_USD] [--collateral_price COLLATERAL_PRICE] [--debt_price DEBT_PRICE]\n                   [--repay_amount_usd REPAY_AMOUNT_USD] [--max_drawdown MAX_DRAWDOWN] [--m M] [--beta BETA] [--min_liq_bonus MIN_LIQ_BONUS]\n\noptional arguments:\n  -h, --help            show this help message and exit\n  -b BORROW, --borrow BORROW\n                        symbol or address of the borrowable asset\n  -c COLLATERAL, --collateral COLLATERAL\n                        symbol or address of the collateral asset\n  --pct_decrease PCT_DECREASE\n                        Per iter percent drop of the collateral price to debt price\n  --initial_collateral_usd INITIAL_COLLATERAL_USD\n                        Size of collateral position to liquidate in the simulation\n  --collateral_price COLLATERAL_PRICE\n                        [Optional] Price of collateral asset. If this is not provided, the simulation uses the current price\n  --debt_price DEBT_PRICE\n                        [Optional] Price of the borrowable asset. If this is not provided, the simulation uses the current price.\n  --repay_amount_usd REPAY_AMOUNT_USD\n                        [Optional] Amount of debt that is repaid during the simulation\n  --max_drawdown MAX_DRAWDOWN\n                        [Optional] The maximum proportion the collateral price to debt price can drop during the simulation\n  --m M                 Liquidation incentive parameter that determines the largest liquidation incentive allowed\n  --beta BETA           Liquidation incentive parameter\n  --min_liq_bonus MIN_LIQ_BONUS\n                        Minimum liquidation bonus\n```\n\nFor instance, if we wanted to get a recommended LLTV for the following:\n- `WSTETH` collateral\n- `WETH` borrow\n- assuming that the ratio of WSETH/WETH does not decrease from their current prices by more than 5 percent\n- liquidators repay in chunk sizes of $10 million\n- price decrease of 1% at each timestep\n- price ratio of WSTETH/WETH does not decrease by more than 5%\n- an initial concentrated borrow position of $400 million\n\nThen we would run the following command for such a simulation:\n\n```bash\npython main.py \\\n --collateral wsteth                    \\\n --borrow weth                          \\\n --max_drawdown 0.05                    \\\n --pct_decrease 0.01                    \\\n --initial_collateral_usd 400000000     \\\n --repay_amount_usd 10000000\n```\n\nBy default, we use cached drawdown and cached price impact numbers that have been pre-computed. We do this because querying CoinGecko and CowSwap for some of this data can take more time than a user may be willing to wait (on the order of 10-20 seconds). The downside of this is that if certain market conditions change, or if a market event occurs that has a large impact on price or liquidity of an asset, then the cached price impact and drawdown numbers may no longer be relevant and the resulting simulation results may give a misleading recommendation for LLTV. The user can instead run the risk tool script with the `--update_cache` flag to ensure that fresh drawdown and price impact numbers are fetched:\n```bash\npython main.py \\\n --collateral wsteth                 \\\n --borrow weth                       \\\n --max_drawdown 0.5                  \\\n --update_cache\n```\nUsers can also pass in token addresses for the `--collateral` and `--borrow` tokens like so. For instance, to get the recommended LLTV for a LINK collateral/DAI borrow market, we can do:\n```\npython main.py \\\n --collateral 0x514910771af9ca656af840dff83e8264ecf986ca        \\\n --borrow 0x6b175474e89094c44da98b954eedeac495271d0f\n```\nThe risk tool currently only allows users to enter Ethereum tokens/token addresses.\n\nWhile creating this tool, we aimed to provide a reasonable set of default methods for setting parameters such as max drawdown, per iteration percent decrease, repay amount, and initial borrow position. However, specific assets may exhibit unique properties that render these default settings less suitable. In these markets, users have the flexibility to override these settings and manually specify the parameters to better align with the assets' characteristics. We encourage users to explore and experiment with these adjustable parameters to tailor the tool to their particular needs and risk tolerance. The demo notebook shows experiments on the various parameters of the simulation and how they might affect the recommended LLTV values.\n\n## Disclaimer\nThis risk tool is designed with a specific focus of simulating bad debt within different LLTV buckets under very specific assumptions about the collateral and borrow assets. While it offers flexibility and adaptability within its scope, it is essential to recognize its limitations and the scenarios it does not cover:\n- **Oracle Mispricing Risk**: The tool does not capture risks associated with incorrect or manipulated price feeds from oracles, which could impact the actual market price.\n- **Smart Contract Risk**: Risks stemming from vulnerabilities or errors within the underlying smart contracts, such as coding errors or potential exploits, are outside the scope of this model.\n\nUsers should recognize the tool's specific focus and limitations, employing it for its intended purpose while seeking supplementary risk assessment methods for scenarios not covered.\n\nThis tool is provided “as is”, at your own risk, and without warranties of any kind. No developer or entity involved in creating the tool will be liable for any claims or damages whatsoever associated with your use, inability to use, or your interaction with other users of, the tool, including any direct, indirect, incidental, special, exemplary, punitive or consequential damages, or loss of profits, cryptocurrencies, tokens, or anything else of value.\n\n## Contact\n\n*If any questions, please reach out to @gauntlet_xyz on Twitter. For more information,  visit our website at www.gauntlet.xyz.*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmorpho-org%2Fmorpho-blue-lltv-recommendation","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmorpho-org%2Fmorpho-blue-lltv-recommendation","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmorpho-org%2Fmorpho-blue-lltv-recommendation/lists"}