On-chain guardian contract

The idea behind the on-chain guardian is straightforward: on-chain liquidation mechanics significantly speeds up the entire process of buying out the liquidated collateral, as well as burning of EOSDT “bad debt” on the liquidator smart contract. In order to achieve this, we’ve made some amendments to our contract logic. Let’s get into the specifics:

Updates to positions contract related to on-chain liquidations

  • New table ltvratios on eosdtcntract

    The entries (table rows) in this table are updated every time someone interacts with EOSDT smart contracts by calling some action or transferring tokens to the system. The table contains the most up-to-date information on all position collateralization ratios.

    Parameter

    Type

    Description

    position_id

    int64

    ID of user position in Equilibrium framework on the main smart contract.

    ltv_ratio

    float64

    The ratio of EOS collateral to EOST generated for given position_id.

  • Refactored eosdtcntract margincall actions.

    Action

    Parameters

    Rejections

    Example

    margincall liquidates a position for given position_id

    position_id (type int64) the id of the position to liquidate.

    When position_id does not exist.

    When for given position_id ltv_ratio > critical_ltv ratio - it can’t liquidate a good position.

    When there are no positions to liquidate. (No entries in ltvratios table with ltv_ratio below critical for current price).

    cleos push action eosdtcntract margincall '{"position_id": "30"}' -p user

    margincalpos liquidates multiple positions by sorting the ltvratios table in order of ascending ltv_ratio.

    N/A

    When there are no positions to liquidate. (No entries in ltvratios table with ltv_ratio below critical for current price).

    cleos push action eosdtcntract margincallpos -p user

    margincalldeffer an internal method that gets called when the oracle service calls our contract with a rates update. If there are positions to be liquidated, deferred margin calls will be created and positions will be liquidated in the next blockchain transaction.

    N/A

    N/A

A new guardian contract

We initially intended to make this contract a liquidity pool, as in people supply EOSDT or EOS to the guardian contract, which constantly monitors the state of the liquidator. If there are non-zero balances on the liquidator, the guardian performs the necessary actions to buy out non-zero balances from liquidator.

But to speed up the process and give our community something useful early on, we decided to provide a basic functionality: the contract will accept EOSDT transfers, will try to liquidate bad debt, then go to exchanges to convert purchased collateral back into EOSDT, returning it (and the profit) to the caller.

The guardian contract is pretty simple under the hood:

if EOSDT is transferred
if bad debt on eosdtliqdatr > 0
transfer EOSDT to liquidator (collateral auction)
receive liquidated EOS
go to DEX, sell EOS for EOSDT
EOSDT received >= EOSDT paid? YES: proceed. NO: revert
end
end

From the user’s perspective, the process looks like transferring EOSDT to the smart contract and receiving the transferred amount back (assuming there’s no “bad debt” to buy out from liquidator, or there wasn’t enough liquidity on the DEX to convert purchased EOS collateral back into EOSDT) or more EOSDT.

We will update the guardian contract to act as a liquidity pool for performing liquidations in the nearest future.

As a friendly reminder, the liquidator contract works as follows. All interactions with liquidator contract are done via transfers from any EOS account:

  • Transfer EOSDT when there is a non-zero amount of "bad debt" in the liquidator contract and get EOS collateral at a 3% discount.

  • Transfer NUT when nut_collat_balance is non-zero to buy out excess EOS collateral at a 6% discount.

  • Transfer EOS when surplus_debt is non-zero (non-zero equilibrium fee, which is not the case right now) on the liquidator contract to buy out EOSDT at a 3% discount.

New guardian.js bot

Thanks to on-chain margin calls and the new guardian contract, interacting with the liquidator contract has never been easier: guardian.js is now basically a script that handles user accounts and transfers EOSDT to the guardian contract.