Core
The margin engine contract which imposes margin requirements and coordinates liquidations, manages margin accounts and their collateral holdings
createAccount
Creates a margin account for the given address, returns its id. An address can have multiple margin accounts in order to separate exposure and margin.
activateFirstMarketForAccount
This function is used to register an account to a collateral pool. In order to trade or to be a liquidator, the account needs to be registered to a collateral pool. This is set implicitly for trading but not for liquidations.
getUsdNodeMarginInfo
Get the margin requirements and collateral balance for the entire account denoted in USD terms with 18 decimals precision. This means the balance in different collaterals is aggregated and the current exchange rate is used (with a small risk haircut applied). The real balance represents the net balance (deposits and withdrawals) plus the realised PnL, while the margin balance also includes the unrealised PnL. The delta represents the distance until the respective risk/liquidation threshold is hit (represented in USD as well). The liquidation margin requirement is the threshold for liquidation. If the margin balance depreciates under this value, the account will be liquidated.
getNodeMarginInfo
This function returns the same values as the getUsdNodeMarginInfo
when the collateral is rUSD.
getTokenMarginInfo
This function returns the margin information in the given token with its respective decimal precision. Passing rUSD as collateral would result in the same value as getNodeMarginInfo if the account does not have margin in other tokens (e.g. sUSDe). If the account has margin in other tokens, it will aggregate the net margin and return the same values as getUsdNodeMarginInfo
. When passing sUSDe as collateral, it will return only net balances and zero deltas and margin requirements as this token is not a quote token and accounts cannot carry exposure in it.
getCollateralInfo
Get the collateral information of an account. The net deposits track only the in-and-out movements of the collateral, including deposits, withdrawals, fees paid. The real balance is the net plus the realised PnL gained from the markets exposure. This represents the amount that can be withdrawn and is also used to determine the liquidation status of this account. The margin balance also includes the unrealised PnL, which is not permitted for withdraw.
getActiveMarketsPerQuoteCollateral
Returns the list of market IDs where the account is exposed. Note, rUSD is the only quote used so far.
triggerAutoExchange
The requestedQuoteAmount is denominated in rUSD, with 6 decimals precision. The collateral
represents the token to be extracted by the liquidator and inCollateral
represents the quote token, rUSD.
The following function can be used to calculate the amount that can be auto-exchanged: calculateMaxQuoteToCoverInAutoExchange
and calculateAvailableCollateralToBeAutoExchanged
.
This function returns AutoExchangeAmounts specifying the collateral tokens that went to the liquidator (denoted in the token with its own decimal precision), the quote amount that went to the insurance fund (small fee paid for the protocol’s safety) and the quote that reached the liquidated account.
calculateMaxQuoteToCoverInAutoExchange
calculateAvailableCollateralToBeAutoExchanged
Returns the maximum amount of collateral that can be extracted from the user’s account in exchange for quote. The out collateral represents the token to be received by the auto-exchanger and the quote collateral should be rUSD, the token paid by the auto-exchanger. It returns the amount denoted in the collateral token with its decimal precision.
execute
This is a router-type function, it allows the user to call multiple protocol functionalities in the same transaction e.g. deposit, trade, withdraw. For Core commands (Deposit, Withdraw, DutchLiquidation, TransferBetweenMarginAccounts) the market id and exchange id should be zero. For the MatchOrder, the values should be specified. These commands have to act on a single account account, the one globally specified in the function parameters. If the msg.sender does not have permissions to modify this account, the transaction will fail.
Each command requires a different set of encoded inputs, sent under bytes inputs:
Deposit and Withdraw:
(address collateral, uint256 collateralAmount)
DutchLiquidation: (DutchLiquidationInput inputs) with
DutchLiquidationInput{uint128 liquidatableAccountId; address quoteCollateral; uint128[] marketIds; bytes[] inputs;}
where the inputs are encoded(int56 liquidatedBase, uint256 priceLimit)
into bytes. This command allows the execution of Dutch liquidation on multiple markets in the same transaction.TransferBetweenMarginAccounts: (TransferInput inputs) with
TransferInput{uint128 destAccountId;address collateral;uint256 collateralAmount;}
MatchOrder:
(uint128[] memory counterpartyAccountIds, bytes memory orderInputs)
DutchLiquidation command
This command triggers the liquidation of the liquidatableAccountId
if its margin balance fell under the liquidation margin requirement, queried using getUsdNodeMarginInfo
. This liquidation type moved the exposure (the liquidatedBase
) to the liquidator at the market price (without the Pool slippage) within the specified price limit. The liquidator must remain above the initial margin requirements after this exchange, otherwise the transaction fails. The liquidator reward is a fixed percentage of the LMR delta, the improvement in the account's margin requirement after reducing exposure.
executeBySig
This function provides the same functionality as execute()
with the added benefit that the msg.sender does not have to be the owner/admin of the provided accountId
. The owner/admin’s signature is required but the transaction can be called from any address, enabling the use of relayer or external peripheries.
executeBackstopLiquidation
Backstop is a type of liquidation that can be triggered on an account if its margin decreases below the ADL requirement. This can be queried using getUsdNodeMarginInfo
. This type of liquidation sells the position at a better price to the designated backstop LP. The backstop LP account must be registered in Core. The keeper receives a set percentage of the liquidated amount (backstopPercentage * liquidationMarginRequirement
).
Last updated