## Liquidation Queue

### Roles:
- **Borrower:** Entities that create collateralized loan positions to borrow stablecoins from the Bamboo money market.
- **Liquidators:**: Observe and liquidate loans with a borrow amount above the allowed borrowing limit.
- **Bidder:** Account that has submitted the bid. When the bid is executed, liquidated collaterals are credited to this account, made available for withdrawal.

### Terminology
- **Bid ID:** Bid's unique identifier.
- **Asset:** Collateral that the bidder is hoping to purchase.
- **Premium slot:** Rate of premium that the bidder is demanding upon bid execution. Bids with lower premiums are given a higher execution priority, thus being executed first during liquidation events. Bids with matching premiums are pooled together to have the same execution priority. *For now, values are between 0% and 30% at an increments of 1%*
- **Activation Time:** Block timestamp when the bid becomes eligible for activation. Bid execution can only occur for activated bids.
- **Tax Rate:** Protocol fee applied to stablecoins transfer that occur on the Persistence blockchain.
- **Liquidation Threshold:** Threshold collateral value for partial collateral liquidations.
- **Bid Threshold:** Bid amount threshold under which bids will be activated upon submission.
- **Bid Fee:** Fee rate applied to all executed liquidations.
- **Liquidator Fee:** Fee rate given to liquidator.
- **Waiting Period** Time after submitted bids can be activated.
- **Price Timeframe:** Window of time before oracle price data is considered outdated.
- **Borrow amount:** Total amount of stablecoin borrowered by borrower.
- **Borrow Limit:** Maximum stablecoin value borrowable by borrower on provided collaterals.
- **Safe Ratio / Health Factor:** (Borrow amount / Borrow limit) ratio value that signals borrowers loan position's liquidation riskiness.

## Liquidation Flow

### Submit Bid
Bidder can submits a bid for the specified Cw20 collateral with specified premium slot, along with stablecoins to be sent beforehand. This return a bid_idx which can be used later to activate the bid.

  "submit_bid": {
    "collateral_token": "cATOM", 
    "premium_slot": 5
  }

### Activate Bid
Activates the list of bid_idx(s) for the specified collateral_token. Activates all bids with expired waiting period.

 "activate_bids": {
    "collateral_token": "cATOM",
    "bids_idx": ["1","2"], 
  }

### Retract Bid
Withdraws specified amount of stablecoins from the specified bid_idx.
Withdraws the entire remaining bid if the amount field is not filled.

 "retract_bid": {
    "bid_idx": "1", 
    "amount": "10000" 
  }

### Execute Bid
Liquidates the sent collateral using the active bids on the bid pools, consuming bids with lower premium rates first.

"execute_bid": {
    "liquidator": "liquidator0000", 
    "fee_address": "fee_addr0000",
    "repay_address": "repay_addr0000"
  }

- The liquidator_fee is sent to the liquidator address that originally triggered the liquidation.
- fee_address needs to be decided. This will recieve bid_fee from liquidation.
- repay_address will be Bamboo money market's contract address.

### Claim Liquidations
Claim the liquidated collateral accrued by the specified list of bid_idx(s).
Claims all the pending collateral from bidder submitted bids if the bids_idx field is not filled.

"claim_liquidations": {
    "collateral_token": "cATOM",
    "bids_idx": ["1","2"],  
  }

## Liquidation Example
User **BOB** has some asset **ATOM**. He deposits **ATOM** and mints **cATOM**(CW20 Token), which he can collateralize to borrow stablecoins **USDC**.

### Non Partial Liquidation

*Fixed parmas:*

safe_ratio = 80%
bid_fee = 0%
liquidator_fee = 0%
liquidation_threshold = 1000000
tax_rate = 0
max_ltv = 50%

Since liquidation_threshold is 1000000 any USDC loan below will have full liquidation.

Bidder **ALICE** submits bid for **cATOM** with bid amount **3000 USDC** at premium slot 5. This returns **```bid_idx = 1```**

After waiting period expires, **bid_idx 1** is eligible for activation

**BOB** has deposited **20000 cATOM** as collateral to Bamboo money market

BOB's current borrow amount is **1200 USDC**

Based on Oracle feed, the exchange rate between **ATOM and USDC is 0.1**. Hence the **cATOM** deposited is valued at **2000 USD**

The current borrow limit is **1000 USDC (max 50% LTV)**.

As current collateral value is less than liquidation threshold, it's safe ratio becomes 0%, hence this is eligible for full liquidation.

Safe borrow = safe ratio * borrow limit = 0

The liquidation amount is a function of f(x) and g(x)

> The amount of collateral to be liquidated depends on the status of the bid pools for each collateral. To find out how much collateral should be liquidated we find the intersection between f(x) and g(x) where, x = liquidated collateral f(x) determines the liquidation amount at which the safe ratio is satisfied g(x) gives the repay amount based on the collateral being liquidated, which takes into account the available bids at different premiums.

Reference: https://docs.anchorprotocol.com/protocol/loan-liquidation

We get **liquidation amount** from this function is 12643 **cATOM**(1264.3 **USDC**).

Execute Liquidation is initiated by sending the 12643 **cATOM** to the liquidation contract from the market contract that is just enough to liquidate the collateral to reach safe_ratio.

Placed activated bids are executed in order of their premium slots until safe_ratio is attained and then repay amount is calculated which is then sent to market.

Now calculate repay amount:
- For each collateral, iteral over slots(bid pool), until required liquidate amounts get liquidated
- We get 1201 **USDC** as total stablecoins required to liquidate. This is repay amount.

**Note**: From this liquidation amount 1264 **USDC**, tax rate, bid fee and liquidation fee will get deducted and the repay amount comes at 1201 **USDC**.

ALICE can claim liquidation for bid_idx 1.

Here, BOB has no loan position left. He had a loan of 1200 **USDC**, ALICE paid 1201 **USDC** to market, and gets 12643 **cATOM**(1264 **USDC**). Since the bid premium was 5% and BOB has 7357 cATOM as collateral.

### Partial Liquidation

*Fixed parmas:*

safe_ratio = 80%
bid_fee = 0%
liquidator_fee = 0%
liquidation_threshold = 0 
tax_rate = 0
max_ltv = 50%

Since liquidation_threshold is 0 any USDC loan below will have full liquidation.

Bidder ALICE submits bid for **cATOM** with bid amount **3000 USDC** at premium slot 5. This returns **```bid_idx = 1```**

After waiting period expires, **bid_idx 1** is eligible for activation

BOB has deposited **20000 cATOM** as collateral to Bamboo money market

BOB's current borrow amount is **1200 USDC**

Based on Oracle feed, the exchange rate between **ATOM and USDC is 0.1**. Hence the **cATOM** deposited is valued at **2000 USD**

The current borrow limit is **1000 USDC (max 50% LTV)**.

As current collateral value is greater than liquidation threshold, it's safe ratio will remain same, hence this is eligible for partial liquidation.

Safe borrow = safe ratio * borrow limit = 800

Similary as above, We get liquidation amount from the function is 7291 **cATOM**(729.1 **USDC**).

Execute Liquidation is initiated by sending the 7291 **cATOM** to the liquidation contract from the market contract that is just enough to liquidate the collateral to reach safe_ratio.

And, repay amount after executing liquidation is 692 **USDC**.

ALICE can claim liquidation for **bid_idx 1**.

Here, BOB had a loan of 1200 **USDC**, ALICE paid 692 **USDC** to market. ALICE gets 7291 **cATOM**. BOB still has a loan of 508 **USDC** and collateral of 12709 **cATOM**.