# Liquidators

## Overview

This document serves as a guide for actors looking to build liquidation bots for Arcadia Finance. Liquidators play a crucial role in maintaining the solvency of the system by participating in auctions when an Arcadia Account falls below its required margin. Arcadia uses a three-step liquidation mechanism, ensuring fairness and efficiency in the liquidation process.

## Liquidation Process

### Step 1: Initiating Liquidation

The liquidation of an Account is triggered in the **Liquidator** contract when an account fails to meet its margin requirement. Any user can act as an **initiator** and trigger liquidation. The initiator receives an **initiator fee** as an incentive for starting the liquidation process. Once liquidation is initiated, an **auction is launched**, allowing other users (liquidators) to bid on the account's assets.

### Step 2: Bidding on an Ongoing Auction

Once an auction is live, liquidators can **submit bids** to purchase a portion of the account's assets. Arcadia supports **partial liquidations**, meaning that a liquidator does not have to buy all the assets at once, but can choose a portion of the assets to acquire. The auction mechanism ensures that assets are sold at fair market prices, protecting both the account owner and the liquidators.

### Step 3: Ending the Auction

The auction can only be **finalized** once the account is restored to a **healthy state** (i.e., the remaining assets sufficiently cover the outstanding liabilities). A separate **end-liquidation reward** is distributed to the user who successfully triggers the auction's completion. This mechanism ensures that liquidators remain incentivized to follow through until the auction is resolved.

## Technical Implementation of the Liquidation Steps

### Step 1: Initiating Liquidation

To start the liquidation process, a liquidation initiator should call the [`liquidateAccount()`](https://github.com/arcadia-finance/lending-v2/blob/main/src/Liquidator.sol#L256) function in `Liquidator.sol`.

The liquidation will only be initiated if the account does not meet the margin requirements. Specifically, the **liquidation value** must be smaller than the **used margin**, where:

* `usedMargin = openDebt + minimumMargin_`

To get the **liquidation value**, you can call `getLiquidationValue()` on the Account. Additionally, you can easily check if an account is liquidatable by calling `isAccountLiquidatable()` on the Account. Additionally, to determine the **initiator weight** and **termination weight**, you can fetch the liquidation parameters from the creditor. These values are used to compute the initiator and terminator fees based on the open debt.

For more details on reward calculations, refer to the [`_calculateRewards()`](https://github.com/arcadia-finance/lending-v2/blob/main/src/LendingPool.sol#L1162) function in `LendingPool.sol`.

### Step 2: Bidding on an Ongoing Auction

Once an auction is live, liquidators can participate by calling the [`bid()`](https://github.com/arcadia-finance/lending-v2/blob/main/src/Liquidator.sol#L375) function in `Liquidator.sol`. This function allows liquidators to purchase a portion of the liquidated assets at the current auction price.

#### How to Place a Bid

* A liquidator calls `bid()` with the desired amount of assets to purchase.
* The contract calculates the **current auction price** based on the exponential decay model.
* If the bid is valid, the liquidator receives the purchased assets, and the bid amount is used to cover the account’s outstanding liabilities.
* The bidding continues until either the full liquidation amount is covered, the auction reaches the cutoff time, or a user manually ends the auction if the account is brought back to a healthy state.

#### Key Considerations for Bidding

* **Partial liquidations** are supported, meaning liquidators can bid on only a portion of assets instead of the entire liquidated position.
* Once the **cutoff time** is reached, any remaining assets are transferred to the protocol owner for manual liquidation.

### Step 3: Ending the Auction

To finalize the auction, an actor must call the [`endAuction()`](https://github.com/arcadia-finance/lending-v2/blob/main/src/Liquidator.sol#L532) function in `Liquidator.sol`. This function ensures that the account is returned to a **healthy state** before the auction is officially closed.

#### Conditions for Ending the Auction

* The auction can only be ended if:
  * The **collateral value** is greater than or equal to the **used margin**.
  * These values can be retrieved from the account contract:

    ```
    account.getCollateralValue();
    account.getUsedMargin();
    ```

#### Reward for Ending the Auction

* A **termination reward** is distributed to the actor who successfully ends the auction.
* To calculate the **termination fee**, refer to the same [`_calculateRewards()`](https://github.com/arcadia-finance/lending-v2/blob/main/src/LendingPool.sol#L1162) function in `LendingPool.sol` as outlined in Step 1.

By executing `endAuction()`, the liquidator ensures that the account has recovered, any unsold assets are handled properly, and the liquidation process is successfully completed.