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
Rust
JSON
#[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, 
}
{
  "owner": "terra1..", 
  "oracle_contract": "terra1...", 
  "stable_denom": "uusd", 
  "safe_ratio": "0.8", 
  "bid_fee": "0.01", 
  "max_premium_rate": "0.05", 
  "liquidation_threshold": "500", 
  "price_timeframe": 60 
}
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.
Rust
JSON
#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum ExecuteMsg {
    Receive {
        sender: String, 
        amount: Uint128, 
        msg: Binary, 
    }
}
{
  "receive": {
    "sender": "terra1...", 
    "amount": "10000000", 
    "msg": "eyAiZXhlY3V0ZV9tc2ciOiAiYmluYXJ5IiB9" 
  }
}
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.
Rust
JSON
#[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>, 
    }
}
{
  "update_config": {
    "owner": "terra1...", 
    "oracle_contract": "terra1...", 
    "stable_denom": "uusd", 
    "safe_ratio": "0.8", 
    "bid_fee": "0.01", 
    "max_premium_rate": "0.05", 
    "liquidation_threshold": "200000000", 
    "price_timeframe": 60 
  }
}
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.
Rust
JSON
#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum ExecuteMsg {
    SubmitBid {
        collateral_token: String, 
        premium_rate: Decimal256, 
    }
}
{
  "submit_bid": {
    "collateral_token": "terra1...", 
    "premium_rate": "0.03" 
  }
}
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.
Rust
JSON
#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum ExecuteMsg {
    RetractBid {
        collateral_token: String, 
        amount: Option<Uint256>, 
    }
}
{
  "retract_bid": {
    "collateral_token": "terra1...", 
    "amount": "100000000" 
  }
}
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.
Rust
JSON
#[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
    }
}
{
  "execute_bid": {
    "liquidator": "terra1...", 
    "fee_address": "terra1...", // Filled as Overseer contract's address
    "repay_address": "terra1..." // 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.
Rust
JSON
#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum QueryMsg {
    Config {}
}
{
  "config": {}
}
Key
Type
Description
​
​
​
ConfigResponse
Rust
JSON
#[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, 
}
{
  "owner": "terra1...", 
  "oracle_contract": "terra1...", 
  "stable_denom": "uusd", 
  "safe_ratio": "0.8", 
  "bid_fee": "0.01", 
  "max_premium_rate": "0.05", 
  "liquidation_threshold": "200000000", 
  "price_timeframe": 60 
}
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.
Rust
JSON
#[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)>;
{
  "liquidation_amount": {
    "borrow_amount": "10000000", 
    "borrow_limit": "10000000", 
    "collaterals": [
      ["terra1...", "100000000"], // (Cw20 contract address, Locked amount)
      ["terra1...", "100000000"] 
    ], 
    "collateral_prices": [
      "123.456789", // Price of collateral
      "123.456789" 
    ]
  }
}
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
Rust
JSON
#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, JsonSchema)]
pub struct LiquidationAmountResponse {
    pub collaterals: TokensHuman, 
}
​
pub type TokensHuman = Vec<(String, Uint256)>;
{
  "collaterals": [
    ["terra1...", "100000000"], // (Cw20 Token address, Required liquidation amount to reach safe_ratio)
    ["terra1...", "100000000"] 
  ] 
}
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.
Rust
JSON
#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum QueryMsg {
    Bid {
        collateral_token: String, 
        bidder: String, 
    }
}
{
  "bid": {
    "collateral_token": "terra1...", 
    "bidder": "terra1..." 
  }
}
Key
Type
Description
collateral_token
String
Token contract address of bidding collateral
bidder
String
Address of bidder
BidResponse
Rust
JSON
#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, JsonSchema)]
pub struct BidResponse {
    pub collateral_token: String, 
    pub bidder: String, 
    pub amount: Uint256, 
    pub premium_rate: Decimal256, 
}
{
  "collateral_token": "terra1...", 
  "bidder": "terra1...", 
  "amount": "100000000", 
  "premium_rate": "0.03" 
}
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
Rust
JSON
#[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>, 
    }
}
{
  "bids_by_user": {
    "bidder": "terra1...", 
    "start_after": "terra1...", 
    "limit": 8 
  }
}
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
Rust
JSON
#[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, 
}
{
  "bids": [
    {
      "collateral_token": "terra1...", 
      "bidder": "terra1...", 
      "amount": "100000000", 
      "premium_rate": "0.03" 
    }, 
    {
      "collateral_token": "terra1...", 
      "bidder": "terra1...", 
      "amount": "100000000", 
      "premium_rate": "0.03" 
    }
  ]
}
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.
Rust
JSON
#[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>, 
    }
}
{
  "bids_by_collateral": {
    "collateral_token": "terra1...", 
    "start_after": "terra1...", 
    "limit": 10 
  }
}
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
Rust
JSON
#[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, 
}
{
  "bids": [
    {
      "collateral_token": "terra1...", 
      "bidder": "terra1...", 
      "amount": "100000000", 
      "premium_rate": "0.03" 
    }, 
    {
      "collateral_token": "terra1...", 
      "bidder": "terra1...", 
      "amount": "100000000", 
      "premium_rate": "0.03" 
    }
  ]
}
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 modified 1yr ago

Liquidation Contract

Config

InstantiateMsg

ExecuteMsg

`Receive`

`UpdateConfig`

`SubmitBid`

`RetractBid`

Receive Hooks

`ExecuteBid`

QueryMsg

`Config`

`ConfigResponse`

`LiquidationAmount`

`LiquidationAmountResponse`

`Bid`

`BidResponse`

`BidsByUser`

`BidsByUserResponse`

`BidsByCollateral`

`BidsByCollateralResponse`

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]

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

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]

Key	Type	Description
`collateral_token`	String	Cw20 token contract address of bidding collateral
`premium_rate`	Decimal256	Rate of commission on executing this bid

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

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)

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

Key	Type	Description
`bids`	Vec<BidResponse>	Vector of user's bid information