Collateral Management Explanations

This section aims to illustrate the path dependent nature of the states of vaults. As smart contracts do not automatically run computation without off-chain input. Therefore, a user must actively calculate and monitor the collateral ratio to change the state of a vault. Without any user interaction, the vault cannot recognize if a specific collateral ratio is not met.

The collateral ratio in a vault is influenced by a number of factors: Posting and withdrawing collateral by the minter, the value of the collateral, baking rewards (where applicable) and changes to the value of the outstanding tokens.

Minters need to closely monitor the collateral ratio in order for them to perform actions that restore adequate levels and hence avoid a step in by a third party.

v3 Engines#

The v3 engines no longer have a target collateral ratio. The target collateral ratio that users can see on the platform is only enforced by the frontend. Liquidations in the v3 engines do not reinstate the target collateral ratio (the engines are not aware of it), but ony reinstate the emergency collateral ratio.

This setup also removes the path dependency of the status of a vault whether it can be liquidated or not.

If a vault has a collateral ratio below the emergency collateral level it can be liquidated.
If a vault has a collateral ratio at or above the emergency collatral level it cannot be liquidated.

Legacy v1 and v2 Engines#

The following rules apply to the legacy version engines:

If the collateral ratio in a vault is observed by a user at or above the target collateral ratio, then the vault is adequately collateralized and not open for step-ins.
If the collateral ratio in a vault is observed by a user at or below the emergency collateral ratio, then the vault is NOT adequately collateralized and it is open for step ins.
If the collateral ratio in a vault observed by a user is below the target collateral ratio and above the emergency collateral ratio, then the state of the vault depends on which of the two collateral ratios was last observed to be touched or breached.
- If the collateral ratio was last observed to be at or above the target collateral ratio, then the vault is adequately collateralized and not open for step-ins.
- If the collateral ratio was last observed to be at or below the emergency collateral ratio, then the vault is NOT adequately collateralized and it is open for step-ins.

Collateral Ratio Example#

For this example, it is assumed that all moves in collateral ratio are caused by moves in collateral FX.

A vault starts with minting the maximum amount of youves tracker tokens, the collateral FX is observed to move slightly up afterwards.

The collateral FX moves then such that the collateral ratio is observed to breach the target collateral ratio at (1) and drops between the target- and the emergency collateral level. The vault is not open to step ins.

Next the collateral FX drops so that the collateral ratio is observed to breach the emergency level at (2). The vault is now open for a step in. Any step in would lead the vault to be back at target collateral ratio again.

Then the collateral FX moves up again so that the collateral ratio is observed to be in-between the target- and the emergency collateral level. The vault remains open for a step in.

The collateral FX moves now such that the collateral ratio is observed breaching the target collateral level at (3) to the upside. The vault is no longer open for a step in. There is a tolerance of 5%-age points to reach the target.

Finally, the collateral FX moves down again, so that the collateral ratio is observed to breach the target collateral level to the downside. This does not change the state of the vault. It is not open for a step in.

Step In Numerical Example#

The below example is on uUSD. The same logic applies to other tracker tokens.

We start with the following assumptions.
- We only look at full step ins. Partial step ins are ignored for now.
- For these calculations, the platform assumes the price of one uUSD to be one USD at all times.
- The initial XTZ/USD exchange rate was at 3.0.
- Minter a posted XTZ 100 into a vault. The equivalent value of the XTZ collateral in USD is 300.
- Minter a minted uUSD 100, attaining a collateral ratio of 300%.
- We ignore the growth of outstanding youves tracker tokens through the liability interest rate for simplicity, so the outstanding youves tracker tokens remain at 100.
- Over time, the XTZ/USD exchange rate drops to 2.0, implying a collateral ratio of 200%, which is at the emergency level.
- This triggers the vault to be open for a step in.
- Minter a is late in reacting to the state of the vault, so party b steps in.
The value of the collateral is now USD 200.
To reach a collateral ratio of 300%, the minted amount should be at uUSD 66.67.
Hence there is an excess of 33.33 uUSD minted.
- Posting and burning uUSD 33.33 would eliminate the excess minted amount bring the vault back to a collateral ratio of 300%.
- The vault pays out a bonus of 12.50% of the step in amount to the party stepping in.
- The vault should also still be at target collateral ratio after paying out the bonus.
- As a consequence, the step in amount to post and burn needs to be higher than uUSD 33.33, otherwise there would not be any excess collateral to pay out a bonus while maintining the target collateral ratio.
Party b can either use uUSD from its wallet, buy them from another source like a DEX or mint new uUSD.
Party b posts and burns uUSD 53.33 and receives XTZ 30.00, which are worth USD 60.00 at the time, (1 + bonus) times higher than the value of the posted uUSD amount.
The remaining collateral is XTZ 70, worth USD 140.00.
The remaining minted amount is 46.67, which results in a collateral ratio of 300%.

Executing a Step-in#

The youves frontend does not supports manual step-in directly. As a consequence, manual step-ins have to be done through a block explorer, such as Better Call Dev (BCD). Alternatively a bot can be coded to interact directly with the smart contracts.

Executing a Step-in manually via Better Call Dev#

Please note that Better CallDev may not always have data representing the latest block on the tezos chain.

Find a Vault#

Go to the vaults map and select the token - collateral combination of interest.
Find a vault in the map appears to be open for step-ins.
Click on the owner address below the KT1... contract address to get to tezblock. This is typically a tz... wallet address, but can also be another KT1... contract address.
In tezblock, copy the owner address by clicking the copy button.

Check the Vault Details#

Open the list of token - collateral combinations
Open BCD by clicking on the engine address which matches the chosen token - collateral combination above.
Click on the Big Map [...] button to the right of vault_contexts to see the existing vaults.
Enter the previously found owner address into the search bar.
Click on the owner address.
Make note of the values next to balance (collateral) and minted (minted amount)
- Note that the smart contracts do lazy updating, so both these values may not incorporate the latest baking rewards (where applicable) and/or accrued interest. As a consequence, both balance and minted may have values that are smaller than the actual current values. However, given the size of the baking rewards and the interest rate, the differences should be not too large. In any case, this can impact all following calculations.
Normalise the values by taking into account the decimals.
- The collateral decimals canbe found at Eligible Collateral
- Form the minted amount the youves tracker tokens all have 12 decimals.
```
collateral_factor = 10 ^ decimalsnormalised_balance = balance / collateral_factornormalised_minted = minted / 10E12 
```
- Please note that BCD displays tez values without the 6 decimal shift and adds a ꜩ symbol. Once you click on balance, the value will be displayed as "mutez" (millionth of tez), so the 6 decimals are incorporated.

Calculate the Collateral Ratio#

Further normalise the values for balance and minted by transforming them into a common currency, i.e. tez or USD. The exchange rates are denoted as tez/collateral_type and tez/token_type respectively.
```
normalised_balance_in_tez = normalised_balance / (tez/collateral_type)normalised_minted_in_tez = normalised_minted / (tez/token_type)
```

Calculate the collateral ratio by dividing minted by balance.

collateral_ratio = normalised_minted_in_tez / normalised_balance_in_tez

Check that a Vault is Open for Liquidation#

Make note of the value for is_being_liquidated.
Check that the vault in question can actually be liquidated. This can be done if either
- The collateral ratio is < 300% AND is_being_liquidated = true or
- The collateral ratio is < 200%.

Establish the Maximum Amount to be Burned#

Calculate the excess_minted_amount

target_minted_amount = normalised_balance_in_tez * 300% * (tez/token_type)excess_minted_amount = normalised_minted - target_minted_amount

The max_burn_amount is the excess_minted_amount multiplied by 1.6, subject to an upper limit of all minted tokens from that vault. Calculate the excess_minted_amount
```
max_burn_amount = MIN(normalised_minted, excess_minted_amount * 1.6)max_burn_amount_pitoken = max_burn_amount * 1E12
```

Execute the Liquidation/Step-in#

Click on Interact.
Select liquidate from the list on the left.
Enter the required information:
- Enter the saved owner address from above into vault_owner.
- Enter the step in amount into token_amount. Make sure the number is not larger than max_burn_amount_pitoken.
- Press Fill next to "source" to enter your own wallet address.
"amount" can be ignored.
Press Execute.
- To test, press Simulate to check whether the transaction will likely fail.
- To actually execute the liquidation/step-in click either wallet or Spire, depending on the wallet set-up and confirm the transaction.
- In case this fails, some of the error codes can be compared to the list.

Executing a Step-in via a bot#

Experienced developers may use the liquidation bot GitHub repository for inspiration.