# Pay Off Debt Learn how to pay off debts in Marginly ### About A vital instrument of portfolio management. ### Step-by-step guide 1. Select your position on the main screen of the app 2. Click “Pay Off” button
| User | ETH+ | ETH- | USDC+ | USDC- | NetPos | Leverage |
|---|---|---|---|---|---|---|
| 1 | 1 | 0 | 0 | 0 | 1000 | 1 |
| 2 | 0 | 1 | 1100 | 0 | 100 | 11 |
| User | ETH+ | ETH- | USDC+ | USDC- | NetPos | Leverage |
|---|---|---|---|---|---|---|
| 1 | 1 | 0 | 0 | 0 | 1000 | 1 |
| 2 | 0 | 1 | 1100 | 0 | 100 | 11 |
| 3 | 1.2 | 0 | 0 | 1000 | 200 | 6 |
| Parameter | Description |
|---|---|
| Base Collateral | Sum of all ETH collateral in the system. |
| Quote Collateral | Sum of all USDC collateral in the system. |
| Base Debt | Discounted total debt in ETH. |
| Quote Debt | Discounted total debt in USDC. |
| Long leverage | This is leverage of all long positions in the protocol. Longs borrow USDC against ETH to buy more ETH. |
| Short leverage | This is leverage of all short positions in the protocol. Shorts borrow ETH against USDC to sell it for more USDC |
| Base Debt Coef | Total accrued interest from the inception. Recalculated every time any user performs any action. Tracks debt accrual in the system: |
| Quote Debt Coeff | Total accrued interest from the inception. Recalculated every time any user performs any action. Tracks debt accrual in the system: |
| Base Collateral Coef | This is the collateral coefficient for ETH liquidity. It increases every time the interest rate from ETH shorts is accrued. It also increases every time shorts are liquidated with the surplus. It may decrease when liquidated position has negative net difference. |
| Quote Collateral Coef | This is the mToken price for the USDC liquidity. It increases every time the interest rate from USDC shorts is accrued. It also increases every time ETH longs are liquidated with the surplus. It may decrease when liquidated position has negative net difference. |
| Base Deleverage Coef | Coefficient used in base collateral calculations after deleverage |
| Quote Deleverage Coef | Coefficient used in quote collateral calculations after deleverage |
| Parameter | Description |
|---|---|
| max leverage | maximum allowable leverage. by default = 20 |
| interest rate | The proportion of a loan that is charged as interest to the borrower. interest rate = Coef * var(ETH)var(ETH) - historical long-term average ETH volatility, which we initially set to be 6% or 0.06 per day. Subject to periodical reassessment by Marginly governance. Coef - scaling coefficient which governs the steepness of the interest rate curve, the default value is 15 |
| swap fee | 0.1% by default. When users take leverage, they pay 0.1% on the notional borrow amount. |
| fee | 2% by default. Extra annual interest rate added to debt with every reinit. |
| position min amount | Minimum amount (in base token) to open a Short or Long position. By default = 0.001 ETH |
| price seconds ago | Parameter for Uniswap TWAP Oracle. Number of seconds in the past from which to calculate the time-weighted-average-price. By default = 900 seconds. |
| position slippage | Maximum allowable slippage when managing a position. By default = 2% of the current (last) AMM price. |
| margin call slippage | Maximum allowable slippage when liquidating a position. By default = 5% of the current (last) AMM price. |
| base asset limit | Maximum allowable balance of the base asset in the pool. |
| quote asset limit | Maximum allowable balance of the quote asset in the pool. |
| Parameter | Description |
|---|---|
| Base amount | User’s ETH collateral: or User’s discounted ETH debt: |
| Quote amount | User’s USDC collateral: or User’s discounted USDC debt: |
| Type | Type of position:
|
| Heap position | Index of position in leverage heap (short or long). By default, 0 (meaning the id doesn’t exist in any leverage heaps). Otherwise, the index of the heap equals heap position minus 1. |
| Function | Parameter | Description |
|---|---|---|
| deposit base | account_id qty | deposit ETH:
|
| deposit quote | account_id qty | deposit USDC:
|
| withdraw base | account_id qty | withdraw ETH:
|
| withdraw quote | account_id qty | withdraw USDC:
|
| Long | account_id qty (L) | This is an atomic sequence of actions: if one of the steps fails, all of the transaction is reverted:
|
| Short | account_id qty (L) | This is an atomic sequence of actions: if one of the steps fails, all of the transaction is reverted:
|
| close position | account_id | This is an atomic sequence of actions: if one of the steps fails, all of the transaction is reverted:
|
| reinit | Accrue interest rates, syncs balances and liquidate riskiest position if needed: Marginly tracks leverages of user long and short positions sorted from highest to lowest (using heaps), each time interest rates are accrued, system checks if the leverage of the most risky position (heap root) is above max leverage it gets liquidated automatically. All of the collateral is sold and the liquidated user effectively pays a penalty of <=5%. All the penalty is distributed to liquidity providers This function is free for any user to call as it's in the best interest of the pool participants to call it to collect liquidation fees. This function is called automatically inside any user facing function. | |
| Receive position | account_id | Provide liquidity and absorb liquidated position, effectively realising its net position value. This function is useful when there is no collateral to sell in the system, but liquidations still need to happen. |
| Emergency withdraw | Available when the system parameter mode is EmergencyShort or EmergencyLong. Theses scenarios are only possible in the system when there is not enough ETH collateral to cover USDC debt and vice versa: not enough USDC collateral to cover ETH debt. Emergency Short mode: There is no liquidity in the system and the insurance pool to liquidate bad short positions. In that mode all positions of type Lend and Long could withdraw their collateral minus amounts needed to reduce short positions debts. Emergency Long mode: There is no liquidity in the system and the insurance pool to liquidate bad long positions. In that mode all positions of type Lend and Short could withdraw their collateral minus amounts needed to reduce short positions debts. |
| Error | Description | User action | Display message |
|---|---|---|---|
| AccessDenied(); | Pool Factory error if someone invokes owner methods | ||
| ExceedsLimit(); | As a result of user action token limits will be exceeded | Deposit Long Short | Pool asset limit reached. Try again later. Learn more about limits here (TBD). |
| EmergencyMode(); | Only withdrawals are allowed. Action is shut down | Any action except for emergency withdraw | The Pool is in shutdown mode. Only emergency withdrawals are allowed. Learn more about the shutdown here |
| Forbidden(); | Pool Factory error. Generic error e.g. when setting parameters | ||
| LongEmergency(); | Withdraw from short position in emergency mode | Any action except for emergency withdraw | The Pool is in shutdown mode. Only emergency withdrawals are allowed. Learn more about the shutdown here |
| Locked(); | Protection from reentrancy smart contract attack. Prevents smart contract from invoking itself | ||
| LessThanMinimalAmount(); | Amount is less than minimum allowed position size | Deposit Long Short | Asset quantity has to be greater than <%limit%> <%token%> |
| BadLeverage(); | Leverage exceeds maximum allowed | Long Short Withdraw | Max leverage of <%leverage%> exceeded. Please adjust trade parameters and try again. |
| NotLiquidatable(); | Keeper fails to receiveposition() with normal leverage | ||
| NotOwner(); | pool error: non-owner invokes owner methods | ||
| NotWETH9(); | When the asset is not from WETH9 contract. Can appear during wrap/unwrap | ||
| PoolAlreadyCreated(); | This pool already exists | ||
| PositionInitialized(); | Appears only in the receiveposition() | ||
| ShortEmergency(); | Withdraw from long position in emergency mode | Any action except for emergency withdraw | The Pool is in shutdown mode. Only emergency withdrawals are allowed. Learn more about the shutdown here |
| SlippageLimit(); | exchange exceeded the slippage limit. can trigger other router errors: - InsufficientAmount: swapexactinput with bad price - TooMuchRequested: swapexactoutput with bad price | Long Short Close Liquidate | Slippage limit of <%slippage%> exceeded. Please adjust the trade parameters and try again. |
| NotEmergency(); | emergency withdrawal when not in shutdown. | ||
| UninitializedPosition(); | when withdrawing from an empty position | ||
| UniswapPoolNotFound(); | pool factory error: there is no corresponding uniswap pool | ||
| UnknownCall(); | decoding-related error | ||
| WrongIndex(); | heap access error | ||
| WrongPositionType(); | long/short/withdraw/close using unsupported collateral | Long Short Withdraw Close | Can’t long <base_token> with <quote_token as margin> Can’t short <base_token> with <base_token as margin> Can’t withdraw debt. |
| WrongValue(); | pool factory: wrong parameter value when creating a pool | ||
| ZeroAmount(); | when depositing/withdrawing 0 amount router: when exchange amount is 0 | Can’t deposit/withdraw/exchange 0 tokens. | |
| STF | safe transfer if no approval or insufficient balance. router: not enough money in marginly pool | Insufficient pool balance to perform the transaction. | |
| ST | pool doesn’t have a balance. router: dex is sending wrong amounts | Insufficient pool balance to perform the transaction. | |
| STE | same as ST but for ETH. | Insufficient pool balance to perform the transaction. | |
| UnknownDex | router can’t find dex | ||
| Forbidden | generic error when setting router parameters. | ||
| UnknownPool | router error: no Pool on target DEX with specified tokens | ||
| WrongAmountOut | router error: dex amount doesn't match expected amount |
| Risk | Description |
|---|---|
| Volatility Risk | The higher the volatility of the ETH, the less likely pool is to recover the full loan amount in the event of default. Marginally incorporates volatility into the interest rate calculation, so traders pay more for the risk when the market volatility is high. Governance has a dashboard to monitor volatility and changes the interest rate parameter on-chain. ETH price may experience sharp jumps, with intraday returns swinging as much as 25% on both sides. Imagine an example where the ETH price jumped lower, and there are a lot of leveraged long positions in the system holding ETH as collateral. Highly leveraged positions will be at risk of getting insolvent: market panic, multiple accounts being liquidated, blockchain network congestion, and liquidity drying out on Uniswap, all in conjunction, will lead to the inability to recover the full loan amount when liquidating. Marginly uses the insurance pool as a liquidity of last resort to cover possible protocol losses in such scenarios. System participants / Marginly DAO will have a dashboard to monitor system solvency and the pace of asset accumulation in the insurance pool. |
| Liquidity Risk | The lower the liquidity depth in the ETH/USDC uniswap pool, the less likely the pool to recover the full loan amount in the event of default. Expected shortfall (ES) shows what is the average worst 1% return ETH may demonstrate during a single day. It is then used to calculate how much collateral is at risk of liquidation. This collateral’s realizable value depends on the liquidity depth in uniswap. System participants have a dashboard to monitor uniswap liquidity and effective realisable price given current liquidity conditions. |
# Keeper contract architecture ### MarginlyKeeper Contract helper for Marginly position liquidators. *It makes liquidations utilizing AAVE flashloans* #### Profit ```solidity event Profit(address liquidatedPosition, address token, uint256 amount) ``` *Emitted when liquidation occurs* **Parameters** | Name | Type | Description | | ------------------ | ------- | ------------------- | | liquidatedPosition | address | liquidated position | | token | address | profit token | | amount | uint256 | profit amount | #### LiquidationParams ```solidity struct LiquidationParams { address marginlyPool; address positionToLiquidate; address liquidator; uint256 minProfit; } ``` #### ADDRESSES\_PROVIDER ```solidity contract IPoolAddressesProvider ADDRESSES_PROVIDER ``` #### POOL ```solidity contract IPool POOL ``` #### constructor ```solidity constructor(address addressesProvider) public ``` #### flashLoan ```solidity function flashLoan(address asset, uint256 amount, uint16 referralCode, address marginlyPool, address positionToLiquidate, uint256 minProfit) external ``` Takes a simple flashloan in AAVE v3 protocol to liquidate a position in Marginly **Parameters** | Name | Type | Description | | ------------------- | ------- | ------------------------------------------------- | | asset | address | borrow asset | | amount | uint256 | borrow amount | | referralCode | uint16 | referral code to get rewards in AAVE | | marginlyPool | address | address of marginly pool | | positionToLiquidate | address | address of liquidatable position in Marginly pool | | minProfit | uint256 | amount of minimum profit worth in borrow asset | #### executeOperation ```solidity function executeOperation(address asset, uint256 amount, uint256 premium, address initiator, bytes data) external returns (bool) ``` Executes an operation after receiving the flash-borrowed asset *Ensure that the contract can return the debt + premium, e.g., has enough funds to repay and has approved the Pool to pull the total amount* **Parameters** | Name | Type | Description | | --------- | ------- | --------------------------------------- | | asset | address | The address of the flash-borrowed asset | | amount | uint256 | The amount of the flash-borrowed asset | | premium | uint256 | The fee of the flash-borrowed asset | | initiator | address | The address of the flashloan initiator | | data | bytes | | **Return Values** | Name | Type | Description | | ---- | ---- | ---------------------------------------------------------------- | | \[0] | bool | True if the execution of the operation succeeds, false otherwise | # Liquidations and Deleveraging This page describes mechanics behind Marginly's liquidations and deleveraging As we described in the [Trading](/protocol-mechanics/trading) section the maximum leverage available both for longs and shorts in Marginly is 20x. So what happens when the user's position exceeds this threshold? There are two possible outcomes which we describe below. ### Liquidations Liquidation flow is straightforward: sell liquidating position's collateral on Uniswap, use proceeds to repay liquidating position's debt, put excess (if any) back to the pool. With such an approach the entire pool enjoys an additional stream of revenues in a form of 5% penalty ( 1 / max leverage) on every position liquidation that occurs in the system. To better understand the mechanics, let's consider a simple example we've seen before when we discussed [trading mechanics](https://docs.marginly.com/protocol-mechanics/trading#margin-and-leverage):
| User | ETH+ | ETH- | USDC+ | USDC- | NetPos | Leverage |
|---|---|---|---|---|---|---|
| 1 | 1 | 0 | 0 | 0 | 1000 | 1 |
| 2 | 0 | 1 | 1100 | 0 | 100 | 11 |
| User | ETH+ | ETH- | USDC+ | USDC- | NetPos | Leverage |
|---|---|---|---|---|---|---|
| 1 | 1.0526 | 0 | 0 | 0 | 1100 | 1 |
| 2 | 0 | 0 | 0 | 0 | 0 | N/A |
| User | ETH+ | ETH- | USDC+ | USDC- | NetPos | Leverage |
|---|---|---|---|---|---|---|
| 1 | 4 | 0 | 0 | 3000 | 1000 | 4 |
| 2 | 2 | 0 | 0 | 0 | 2000 | 1 |
| 3 | 0 | 5 | 6000 | 0 | 1000 | 6 |
| 4 | 0 | 1 | 6000 | 0 | 5000 | 1.2 |
| User | ETH+ | ETH- | USDC+ | USDC- | NetPos | Leverage |
|---|---|---|---|---|---|---|
| 1 | 0 | 0 | 0 | 0 | 0 | N/A |
| 2 | 2 | 0 | 0 | 0 | 2000 | 1 |
| 3 | 0 | 1.667 | 3500 | 0 | 1833.33 | 1.0909 |
| 4 | 0 | 0.333 | 5500 | 0 | 5166.67 | 1.0645 |
| Approach | Pros | Cons |
|---|---|---|
| Setup a risk framework to periodically set the volatility parameter via governance. |
|
|
| Calculate volatility on-chain using oracle and / or on-chain AMM prices. |
|
|
| Fetch volatility from oracle or 3rd party protocols. |
|
|
- Borrower interest
- Liquidation penalties
- Swap fees
- Bootstrap insurance pool
- Reward integration partners
- Reward the team
- Reward long-term liquidity providers
The best way to mitigate counterparty risk is to follow a strict process in developing and testing the smart contract logic and code.\ \ At Marginly we cover all of the smart contract methods with unit tests that must be passed before any functionality gets updated. We also run [integrational scenarios](https://github.com/eq-lab/marginly/tree/contest-deploy/packages/int-tests) that involve testnet deployment and trading emulation with testnet tokens and Uniswap v3 mock.\ \ Additionally, the audit must be performed by 3rd party professionals on close-to-live scenarios by deploying and playing with the smart contracts to blockchain testnets. The audit report has to be publicly available. [Quantstamp will audit Marginly](https://marginly.medium.com/marginly-set-to-undergo-an-audit-with-quantstamp-ahead-of-protocol-launch-bf09025d06d) v1 contracts.\ \ Finally, when the Marginly protocol is live, there will be a dedicated Marginly token allocation for the bug bounty programs, so white hackers may do their business! ### Technical risk This risk entails everything that is related to the proper functioning of Marginly interfaces, [Walletconnect](https://walletconnect.com/) provider, and the wallet you use to sign blockchain transactions. In case anything goes wrong with the abovementioned components due to software bugs or poor internet connection, you may temporarily lose access to your Marginly position and thus fail to act timely on your portfolio. We run testnets and contests and allow people to participate and interact with the app so we can catch all the interface and connection errors and minimize their occurrence. Our QA team follows scenarios of common user flows and makes sure interfaces and wallet management run smoothly in different browsers and on different devices. We have created more than 100 manual tests for regression testing with specialized testing software. We run these tests once a month to assess the overall app behavior. We also collect extensive user feedback from our Discord server and categorize it so we can prioritize our future work. We are working on the desktop version of the app at the moment, yet we recommend using the mobile version as we envision the mobile-first app future. We observed stable behavior and smooth running of the Marginly web app on the following operational systems and several cell phone devices: **iOS**: version 15.4 or higher. Safari or Chrome browser, walletconnect with Metamask wallet.\ **Android**: Android 11 or higher. Chrome or Firefox browser, walletconnect with Metamask wallet. To mitigate the technical risk we recommend using the Marginly app only with a stable internet connection. Please don’t hesitate to report UX bugs so that the dev team can fix them in a timely manner. You can reach out to us in Marginly’s [discord](https://discord.com/invite/tCTYwTzM8h) and [twitter](https://twitter.com/marginlycom). We will additionally consider bug bounty programs to motivate people to find non-critical technical bugs that impede the normal functioning of the app. ### Market risk This is the one risk we can analyze extensively using several statistical methods at our disposal. Market risk is important in the context of leveraged trading because it is closely related to the maximum leverage a trader should take and to the concept of liquidation prices. The higher the volatility of the underlying tradeable asset, the less likely the pool is to recover the full loan amount in the event of default. Marginly incorporates volatility into the interest rate calculation, so traders pay more for the risk when the market volatility is high. Marginly runs a [risk dashboard](https://dashboard.marginly.com/) to monitor volatility and possible risks on-chain. Using the [Marginly dashboard](https://dashboard.marginly.com/) users can quickly assess the current market regime and define their drawdown tolerance given the historical volatility distribution and simulated returns histogram. Let’s consider an example: I want to long ETH and would love to know the safe level of leverage I can take. Here’s the approximate algorithm I would use with the Marginly risk dashboard:\ \ 1\. Assess current and historical volatility measures:
* [Interest rate:](https://docs.marginly.com/protocol-mechanics/loan-pricing) this parameter is scaled by leverage, in particular, the interest rate is proportional to the overall long or short leverage and the current volatility level of the underlying: \
Now imagine that the protocol needs to liquidate the position which is 50K in size. This would move the pool price significantly more than the 5% (max leverage = 20) liquidation threshold. This is a good illustration of the external liquidity risk. Bear in mind that this risk is exacerbated when the market is in turmoil as LP providers start leaving the Uniswap pool. Now let us consider the *internal* liquidity risk.\ \ We’ve covered one possible scenario in detail in our docs on [Marginly deleveraging mechanics](https://app.gitbook.com/o/-LqAeCvM12bCwSTs3V-o/s/QiFBW4qPpAjrKQaezZ3s/protocol-mechanics/risk-management/liquidations-and-deleveraging#deleveraging). Basically, liquidity may be absent in the pool when the protocol needs to liquidate an underwater position. Consider the following pool state as an example:
# Trading Contest FAQ ### Q: Can I use the faucet more than once? A: No. The initial portfolio of virtual assets can be requested from the faucet once per address. ### Q: Will inactive members be excluded from the leaderboards? A: They won’t, as it can affect the accurate qualification schedule. For example, this measure would exclude traders who choose to swap everything for USDC and hold until the end of the contest. Such passive strategies are perfectly viable, and traders who employ them can expect to have their place on the leaderboard. ### Q: Will there be a trade history page? A: Yes, we are working on it. Follow us on [Twitter](https://twitter.com/marginlycom) for upcoming dev updates to get notified when it's live. ### Q: Wen rewards? A: All contest winners will get special NFT badges in three weeks after we wrap up the contest on the specific network. These badges make users eligible for a share of the future airdrop conducted by Marginly. The airdrop will happen after Marginly mainnet launch, the exact date is TBA. ### Q: What's the difference between all these NFTs in Galxe? Please briefly explain which is needed for what. A: There are 3 NFTs and an OAT available on Marginly Galxe.\ **Marginly Paper Plane** is a basic NFT badge to award for following Marginly socials. This badge is a mandatory requirement to be eligible for trading contest prizes. **Marginly Airplane** is a more senior badge to award for completing the on-chain task in the Marginly app beta. It’s required for getting Marginly Rocket. **Marginly Rocket** is the rarest Marginly NFT badge. This badge is to award team captains for their active participation in trading contests and to be raffled among especially distinguished users in other Marginly campaigns on Galxe. This badge entitles holders to a share in the future Marginly airdrop. **Marginly Paper Plane OAT** is similar to the Marginly Paper Plane. The only difference is that users don’t have to pay for gas when they get it. ### Q: I want to swap assets in my portfolio. Is there a way to do that? A: Sure! You can swap assets directly on the trade screen. Select desired pool and click "Swap".
