V2 Liquidation Engine

V2 Liquidation Engine
source: https://lyra.finance

Partial liquidations are an essential aspect of the V2 overhaul - they swiftly remove risk from the system and ensure a maximally beneficial user experience for traders. The market impact of liquidations is reduced by closing over-extended positions incrementally, decreasing the likelihood of insolvency and cascading liquidations.

Liquidating positions incrementally allows traders to maintain a portion of their exposure. Staggering liquidations across price levels can reduce the risks of incurring costs as a result of depressed liquidity at any one particular price level.

The beauty of Lyra’s liquidation system is that anyone can act as a liquidator. This promotes decentralization of the protocol and adds even more security to the system. The process to become a liquidator is straightforward and outlined here.


Liquidation Overview: Liquidations are transparent, can be executed by anyone and occur at the protocol layer.

Partial Liquidations: Partial liquidations help preserve user positions by exchanging risk-bearing assets for USDC, promoting risk management.

Buffer Margin: Buffer margin provides a safety cushion over maintenance margin, thereby allowing users the opportunity to further de-risk or add more collateral in order to prevent being liquidated again if price moves against them.

Flagged Accounts: When a user falls below maintenance margin requirements, anyone can initiate the liquidation process, with the account owner restricted from further transactions.

Auction Process: Lyra V2 employs a two-phase auction process, starting with a solvent auction where liquidators can take a percentage of the subaccount at a discount, and if necessary, an insolvent auction where liquidators are paid to take on the portfolio.

Liquidator Cash Requirements: Liquidators in the auction process must have sufficient USDC in their wallet to cover the liquidated portfolio, collateral for their positions, and the buffer margin.

Liquidation Overview

In V2 liquidations and the associated logic are transparent and fully on-chain. The process of flagging a subaccount for liquidation is straightforward. Any user can check the risk of a subaccount in the system, and if it falls below its maintenance margin requirements, it becomes subject to partial liquidation.

During the liquidation process, the goal is to quickly reduce risk in the system while providing a good experience for the trader being liquidated. Here's how it works:

  • A percentage of all assets in the subaccount is put up for auction.
  • A fee, which is a small percentage of the portfolio's value, is charged to the user and goes to the security module.
  • Initially, the assets are offered for sale at a slightly lower price (95% of their current value).
  • This discount on the sale price increases rapidly, reaching a threshold of 30% within 15 minutes. Afterwards, it continues to increase gradually over 12 hours.
  • During this time, anyone can purchase a portion of the assets being sold, but there is a limit on how much they can buy. This limit is smaller when the account is close to meeting its margin requirements (e.g. may be 20%) and larger when the account is nearly insolvent (e.g. 100%).
  • If the mark-to-market value of the portfolio ever becomes negative, a special auction occurs where the security module pays a liquidator to take on the subaccount of a portfolio.

Partial Liquidations

Partial liquidations are advantageous in this context because they preserve a portion of the user's assets, preventing complete loss and promoting portfolio sustainability. Additionally, they encourage users to actively engage in risk management without the fear of losing all their holdings.

During a liquidation, a percentage of all (cash, base, perpetual, option) assets held by the subaccount are on offer for liquidators. By exchanging risk-bearing assets (short options, perpetuals) for USDC, the liquidated user is de-risked.

This process can be seen in the diagram below, portfolio assets start in white, and then once a liquidation event is triggered they are exchanged into green "reserved cash".

Subsequent liquidators get blue and orange assets. The liquidation stops when the portfolio is considered safe, defined by the "buffer margin" reaching zero.

The Buffer Margin

The Maintenance Margin for a solvent portfolio is the mark to market price of the portfolio plus a buffer margin. Partial liquidation requires a condition to cap the amount of the portfolio that can be liquidated. This means that the liquidated user has some buffer (hence the name), so that even if prices continue to move against them, they still have a chance to de-risk or add more collateral.

We recall that the maintenance margin (MM) is the mark-to-market (mtm) value plus some buffer, ie.


We define the buffer margin (BM) as follows:

Buffer Margin=MM+0.15×buffer

When a user is liquidated during the solvent auction, they are liquidated so that BM=0.

The Partial Liquidation Formula

When a liquidator wishes to liquidate a subaccount, they are able to take on any percentage of the subaccount up to the following cap:


  • d is the current percentage discount to the mark-to-market value.
  • mtm is the mark-to-market value of the entire portfolio defined above.
  • R is the reserved funds: the amount of cash received by the portfolio from all previous liquidations during the auction. It is necessary to ensure liquidators liquidating at the same price/discount pay the same price.
  • BM is the buffer margin of the current subaccount (including reserved funds)

Flagged accounts

When a user falls beneath their maintenance margin requirements (i.e. maintenance margin becomes negative), anyone can call a function to liquidate the account on-chain. The auction process then begins; the account owner is prohibited from conducting any transactions using the flagged account.

When flagged, an account is charged a fee given by

Liquidation Fee=0.10×mtm×BMBM−mtm

A note on portfolio margined accounts: To avoid excess computation done on chain, when a portfolio margined subaccount is flagged for liquidation, the flagger will also submit what they believe to be the worst case scenario (say, spot up 15%, IV static). This scenario, along with the static vol/spot and basis contingency scenarios, will be used to compute the margin requirements of the portfolio, as well as the buffer margin.

The Auction Process

Liquidating a solvent portfolio

After the liquidation fee is charged, the account is put up for a solvent auction. Liquidators can take on a percentage of the entire subaccount at discount to the mark-to-market value. This discount starts at 5%, increasing linearly to 30% over a period of 15 minutes. When a liquidator wishes to liquidate the subaccount, they are able to take on any percentage of the subaccount up to the cap derived above.

If a liquidator requests more than the cap, they are capped at the percentage shown above and the liquidation terminates.

Otherwise, the liquidator receives their requested percentage of the current portfolio and pays

Liquidator Cost=Percentage Received by Liquidator×(mtm−R)×(1−d)

USDC to take on their chunk of the portfolio. The liquidation then continues. If the discount reaches 30% (or the liquidation has been going on for 15 minutes), then the auction continues with the discount decreasing to 100% over the next 12 hours. In order to execute a trade in the auction, the liquidator must have enough USDC in their wallet to cover the liquidated portfolio, the required collateral for their positions and the buffer margin.

The solvent auction does not execute if any of the following conditions are met:

  • The Buffer Margin is greater than 0 meaning the market has moved sufficiently in the trader's favour.
  • The discount hits 100% or the trader’s portfolio is insolvent. This triggers the start of the insolvent auction (see below)

Cash requirement for solvent auctions

During the solvent auction, liquidators are required to hold (in the liquidating cash account) at least the following amount of cash:


  • f is the percentage of the current portfolio the liquidator is taking on (say, 20%)
  • d is the current discount to the mtm (say, the bid price is 90% of the mtm)
  • mtm is the current mark-to-market value of the portfolio
  • R is the total reserved funds
  • BM is the buffer margin of the account.

The first term represents the cash the liquidator pays to take on the account (they have to have enough cash to buy it) while the second term represents the amount of extra USDC that must remain in the liquidator’s cash account to ensure the resulting portfolio has BM = 0.

I.e. it is required that the liquidator’s final cash + liquidated portfolio account to have BM = 0.


Consider Alice’s account which consists of:

  • 100 SHORT $1500 ETH calls
  • 20 LONG BTC perps
  • $50,000 USDC
  • 2 ETH

Suppose also that her portfolio has

  • Mark to Market = $40,000
  • Buffer Margin = -$30,000

The liquidation fee is first calculated. This is given by

Liquidation Fee=0.10×−30,000−30,000−40,000×40,000=$1714.29

Alice’s cash balance is the updated to 50,000-1714.29=$48285.7

Note that:

  • the Mark to Market value of her account decreases to $40,000-1,714.29=$38,285.7$.
  • The Buffer Margin of her account decreases to $-30,000-1,714.29=-31,714.29$.

At t=0, the discount begins at 5%. Let’s say Bob wants to liquidate 10% of Alice’s current portfolio at this discount. We compute the liquidation cap, given by (note there are no reserved funds so R=0)

I.e. Bob can liquidate up to 46.5799% of Alice’s current portfolio.

Bob’s desired percentage (10%) is less than the cap, so he is permitted to take on this amount. Bob pays

to purchase 10% of Alice’s portfolio.

In return, he receives:

  • 10 SHORT $1500 ETH calls
  • 2 LONG BTC perps
  • $4828.57 USDC
  • 0.2 ETH

Consequently, Alice’s portfolio is updated to

  • 90 SHORT $1500 ETH calls
  • 18 LONG BTC perps
  • $48285.7 x 0.9+3637.14=$ 47,094.3 USDC
  • 1.8 ETH

Alice’s buffer margin is still not 0, so the liquidation continues.

Bob also has a cash requirement, namely

In particular, we have


In other words, Bob requires at least $6808.57 USDC in his account to liquidate Alice.

Note that if Bob had liquidated 46.5799% of Alice’s current portfolio then Alice’s final Buffer Margin would be 0 and the liquidation would terminate.

Liquidating an insolvent portfolio

At the insolvent auction, offers start at the mark-to-market value of the portfolio and increase over the next hour to the current maintenance margin of the liquidated portfolio. Specifically, the offer at a given time t is given by


  • INSOLVENT_DURATION = 60 minutes.

All offers at the insolvent auction will also be negative indicating that the liquidator will be paid by the security module (SM) to take on the portfolio. Liquidators in an insolvent auction also have cash requirements to be able to cover the maintenance margin of the account less the cash received for liquidating the portfolio.

The percentage that can be taken on by the liquidator during the insolvent auction is always set to 100%. Offers which reach the maintenance score stay there indefinitely (note the price liquidators receive will continuously vary with the dynamic maintenance score of the portfolio).

The insolvent auction ends when either of the following conditions are met:

  • All of the portfolio has been liquidated
  • The portfolio regains value above the maintenance margin

Cash requirement for insolvent auctions

For the insolvent auction, similar logic yields as in the solvent example:


  • MM is the maintenance margin of the account (we are less stringent during the insolvent auction) and
  • Cash Received is given by Current Offer above (scaled by the percent received by the liquidator), i.e. Cash Received = f * |Current Offer|

Insolvent Auction Example

Alice’s portfolio becomes insolvent and the insolvent auction begins.

Suppose that t = 10 minutes into the insolvent auction process, Bob wants to liquidate Alice. At this point in time, her portfolio has

  • Mark to Market = -$4000
  • Maintenance Margin = -$15,000

Using the formula from the insolvent auction process, we have

Current Offer=−$5,833.33

In other words, Bob can take on 100% of the portfolio and receive an additional payout of $5833.33 from the Security Module. If Bob wants only 40%, then he receives 40% of the entire portfolio and is paid out

SM Payout=0.4×5833.33=$2333.33

from the SM. He is required to have

Cash Required=f×∣MM∣−Cash Received=0.4×∣−15,000∣−2333.33=$3666.67

USDC in his account in order to liquidate the account.


In conclusion, partial liquidations were a crucial part of the V2 overhaul, swiftly mitigating risk, enhancing the user experience, and preserving PnL by reducing market impact and optimizing capital deployment. We’re proud that anyone can participate in V2 Liquidation auctions and no compromises were made in terms of transparency and decentralization to achieve this.

The storm provides ⚡ ⛈️ 🌪️