Liquidation Contract

The Liquidation Contract enables users to submit Terra stablecoin bids for a Cw20-compliant token. Bidders can specify the rate of premium they will receive on bid execution, and the maximum premium rate is set at 30%.

Upon execution of a bid, Cw20 tokens are sent to the bidder, while the bidder's Terra stablecoins are sent to the repay address (if not specified, sent to message sender). The oracle contract is responsible for providing the relevant Cw20 token prices.

Additionally, the Liquidation Contract serves as the point of calculation for partial collateral liquidations, where a loan position is liquidated until it reaches a safe borrow_amount / borrow_limit ratio. The required liquidation amount for each collateral is calculated based on the fed-in loan position's attributes.

Price data from the Oracle contract are only valid for 60 seconds (price_timeframe). The Liquidation contract disables bid executions until new price data is fed-in to the Oracle contract.

Config

Key

Type

Description

owner

CanonicalAddr

Address of contract owner that can update config

oracle_contract

CanonicalAddr

Contract address of Oracle

stable_denom

String

Native token denomination for bids

safe_ratio

Decimal256

A liability / borrow limit ratio of a loan deemed safe

bid_fee

Decimal256

Fee rate applied to all executed bids

max_premium_rate

Decimal256

Maximum rate of commission given to bidder of an executed bid

liquidation_threshold

Uint256

Threshold collateral value for partial collateral liquidations

price_timeframe

u64

Window of time before oracle price data is considered outdated [seconds]

InstantiateMsg

#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, JsonSchema)]
pub struct InstantiateMsg {
    pub owner: String, 
    pub oracle_contract: String, 
    pub stable_denom: String, 
    pub safe_ratio: Decimal256, 
    pub bid_fee: Decimal256, 
    pub max_premium_rate: Decimal256, 
    pub liquidation_threshold: Uint256, 
    pub price_timeframe: u64, 
}

Key

Type

Description

owner

String

Address of contract owner that can update config

oracle_contract

String

Contract address of Oracle

stable_denom

String

Native token denomination for bids

safe_ratio

Decimal256

A liability / borrow limit ratio of a loan deemed safe

bid_fee

Decimal256

Fee rate applied to executed bids

max_premium_rate

Decimal256

Maximum rate of commission given to the bidder of an executed bid

liquidation_threshold

Uint256

Threshold collateral value for triggering partial collateral liquidations

price_timeframe

u64

Window of time before oracle price data is considered outdated [seconds]

ExecuteMsg

Receive

Can be called during a CW20 token transfer when the Liquidation Contract is the recipient. Allows the token transfer to execute a Receive Hook as a subsequent action within the same transaction.

#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum ExecuteMsg {
    Receive {
        sender: String, 
        amount: Uint128, 
        msg: Binary, 
    }
}

Key

Type

Description

sender

String

Sender of the token transfer

amount

Uint128

Amount of tokens received

msg

Binary

Base64-encoded string of JSON of Receive Hook

UpdateConfig

Updates the Liquidation Contract's configuration. Can only be issued by the owner.

#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum ExecuteMsg { 
    UpdateConfig {
        owner: Option<String>, 
        oracle_contract: Option<String>, 
        stable_denom: Option<String>, 
        safe_ratio: Option<Decimal256>, 
        bid_fee: Option<Decimal256>, 
        max_premium_rate: Option<Decimal256>, 
        liquidation_threshold: Option<Uint256>, 
        price_timeframe: Option<u64>, 
    }
}

Key

Type

Description

owner*

String

Address of new owner

oracle_contract*

String

New oracle contract address

stable_denom*

String

New native token denomination for bids

safe_ratio*

Decimal256

New liability / borrow limit of a loan deemed safe

bid_fee*

Decimal256

New fee rate applied to executed bids

max_premium_rate*

Decimal256

New maximum rate of commission given to the bidder of an executed bid

liquidation_threshold*

Uint256

New threshold collateral value for triggering partial collateral liquidations

price_timeframe*

u64

New window of time before price data is considered outdated [seconds]

* = optional

SubmitBid

Submits a new bid for the specified Cw20 collateral with the specified premium rate. Requires Terra stablecoins to be sent beforehand.

#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum ExecuteMsg {
    SubmitBid {
        collateral_token: String, 
        premium_rate: Decimal256, 
    }
}

Key

Type

Description

collateral_token

String

Cw20 token contract address of bidding collateral

premium_rate

Decimal256

Rate of commission on executing this bid

RetractBid

Withdraws specified amount of stablecoins from the bid for the specified collateral. Withdraws the entire bid for the specified collateral if the amount field is not filled.

#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum ExecuteMsg {
    RetractBid {
        collateral_token: String, 
        amount: Option<Uint256>, 
    }
}

Key

Type

Description

collateral_token

String

Cw20 token contract address of bidding collateral

amount*

Uint256

Amount of stablecoins remove from bid

* = optional

Receive Hooks

ExecuteBid

Liquidates collateral by executing an existing bid for the received collateral. Requires the liquidator to have an existing bid. For Usage in Anchor, Custody issues this message with fee_address as Overseer's contract address and repay_address as Market's contract address, where stablecoins from the bid is sent to the Market contract to repay a borrower's loan and fees are sent to the Overseer contract to be added to the interest buffer.

#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum Cw20HookMsg {
    ExecuteBid {
        liquidator: String, 
        fee_address: Option<String>, // Filled as Overseer contract's address
        repay_address: Option<String>, // Filled as Market contract's address
    }
}

Key

Type

Description

liquidator

String

Address of collateral liquidator

fee_address*

String

Address to receive bid_fee from liquidation

repay_address*

String

Address to receive bid stablecoins from liquidation

* = optional

QueryMsg

Config

Gets the Liquidation Contract's configuration.

#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum QueryMsg {
    Config {}
}

Key

Type

Description

ConfigResponse

#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, JsonSchema)]
pub struct ConfigResponse {
    pub owner: String, 
    pub oracle_contract: String, 
    pub stable_denom: String, 
    pub safe_ratio: Decimal256, 
    pub bid_fee: Decimal256, 
    pub max_premium_rate: Decimal256, 
    pub liquidation_threshold: Uint256, 
    pub price_timeframe: u64, 
}

Key

Type

Description

owner

String

Address of contract owner that can update config

oracle_contract

String

Contract address of Oracle

stable_denom

String

Native token denomination for bids

safe_ratio

Decimal256

A liability / borrow limit ratio of a loan deemed safe

bid_fee

Decimal256

Fee rate applied to all executed bids

max_premium_rate

Decimal256

Maximum rate of commission given to bidder of an executed bid

liquidation_threshold

Uint256

Threshold collateral value for partial collateral liquidations

price_timeframe

u64

Window of time before price data is considered outdated [seconds]

LiquidationAmount

Gets the amount of collaterals that needs to be liquidated in order for the borrower's loan to reach safe_ratio, based on the fed in borrower's status.

#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum QueryMsg {
    LiquidationAmount {
        borrow_amount: Uint256, 
        borrow_limit: Uint256, 
        collaterals: TokensHuman, 
        collateral_prices: Vec<Decimal>, 
    }
}

pub type TokensHuman = Vec<(String, Uint256)>;

Key

Type

Description

borrow_amount

Uint256

Liability of borrower

borrow_limit

Uint256

Borrow limit of borrower

collaterals

TokensHuman

Held collaterals and locked amounts

collateral_prices

Vec<Decimal>

Vector of collateral prices

Key

Type

Description

TokensHuman

Vec<(String, Uint256)>

Vector of (Collateral's token address, Amount of collateral locked by borrower)

LiquidationAmountResponse

#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, JsonSchema)]
pub struct LiquidationAmountResponse {
    pub collaterals: TokensHuman, 
}

pub type TokensHuman = Vec<(String, Uint256)>;

Key

Type

Description

collaterals

TokensHuman

Calculated amount of collaterals to liquidate

Key

Type

Description

TokensHuman

Vec<(String, Uint256)>

Vector of (Collateral's token address, Amount that has to be liquidated)

Bid

Gets information about the specified bidder's bid for the specified collateral.

#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum QueryMsg {
    Bid {
        collateral_token: String, 
        bidder: String, 
    }
}

Key

Type

Description

collateral_token

String

Token contract address of bidding collateral

bidder

String

Address of bidder

BidResponse

#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, JsonSchema)]
pub struct BidResponse {
    pub collateral_token: String, 
    pub bidder: String, 
    pub amount: Uint256, 
    pub premium_rate: Decimal256, 
}

Key

Type

Description

collateral_token

String

Token contract address of bidding collateral

bidder

String

Address of bidder

amount

Uint256

Amount of stablecoins put up in bid

premium_rate

Decimal256

Rate of commission taken by bidder upon bid execution

BidsByUser

Gets information for all bids submitted by the specified bidder

#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum QueryMsg {
    BidsByUser {
        bidder: String, 
        start_after: Option<String>, 
        limit: Option<u32>, 
    }
}

Key

Type

Description

bidder

String

Address of bidder

start_after*

String

Token contract address of collateral to start query

limit*

u32

Maximum number of query entries

BidsByUserResponse

#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, JsonSchema)]
pub struct BidsResponse {
    pub bids: Vec<BidResponse>, 
}

pub struct BidResponse {
    pub collateral_token: String, 
    pub bidder: String, 
    pub amount: Uint256, 
    pub premium_rate: Decimal256, 
}

Key

Type

Description

bids

Vec<BidResponse>

Vector of user's bid information

Key

Type

Description

collateral_token

String

Token contract address of bidding collateral

bidder

String

Address of bidder

amount

Uint256

Amount of stablecoins put up in bid

premium_rate

Decimal256

Rate of commission taken by bidder upon bid execution

BidsByCollateral

Gets bid information for all bids submitted for the specified collateral.

#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum QueryMsg {
    BidsByCollateral {
        collateral_token: String, 
        start_after: Option<String>, 
        limit: Option<u32>, 
    }
}

Key

Type

Description

collateral_token

String

Token contract address of collateral

start_after*

String

Token contract address of collateral to start query

limit*

u32

Maximum number of query entries

* = optional

BidsByCollateralResponse

#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, JsonSchema)]
pub struct BidsResponse {
    pub bids: Vec<BidResponse>, 
}

pub struct BidResponse {
    pub collateral_token: String, 
    pub bidder: String, 
    pub amount: Uint256, 
    pub premium_rate: Decimal256, 
}

Key

Type

Description

bids

Vec<BidResponse>

Vector of user's bid information

Key

Type

Description

collateral_token

String

Token contract address of bidding collateral

bidder

String

Address of bidder

amount

Uint256

Amount of stablecoins put up in bid

premium_rate

Decimal256

Rate of commission taken by bidder upon bid execution

Last updated