The deleverage flow

deleverage

1. The total value of Alice’s position becomes negative.

Alice has a position with -1 BTC and +29,000 USDC. A new oracle price tick raises the price of BTC from 28,800 USDC to 29,400 USDC, resulting in Alice’s position becoming negative, or deleveraged, and a result, the application can liquidate it.

Bob has a position with a positive amount of BTC.

In cases such as this, the application is allowed to match Alice’s position with Bob’s position. So Bob’s position is matched against Alice’s. He can provide the entire 1 BTC or only a part of it. In this scenario, Bob is the deleverager.

2. The application sends a Deleverage transaction to StarkEx.

The application sends a deleverage transaction to the StarkEx gateway, using the add_transaction API with the Deleverage transaction type.

After the matching is set, the application sends the following parameters to StarkEx:

deleveraged_position_id

The ID of Alice’s position.

deleverager_position_id

The ID of Bob’s position.

synthetic_asset_id

The unique ID of the asset being deleveraged, as registered on the contract.

amount_synthetic

The amount of the synthetic asset being deleveraged, with the resolution factor applied.

amount_collateral

The quantized amount of the deleveraged position’s collateral.

deleverager_is_buying_synthetic

true: Bob, the deleverager is buying the synthetic asset and Alice is selling.

false: Alice, the deleveraged, is buying the synthetic asset and Bob is selling.

3. StarkEx checks the validity of the request.

StarkEx checks the following constraints:

  • Alice’s position indeed needs to be leveraged, meaning, she has a negative balance according to the most current prices.

  • The signs for Alice’s and Bob’s BTC positions are opposite.

  • The total amount of Alice’s and Bob’s synthetic assets becomes smaller as a result of the transaction and do not change their sign.

  • For Bob, the ratio of Total_Account_Value / Total_Maintenance_Margin_Requirement is either above 1, or is improved as a result of the transaction.

  • Each asset’s ID corresponds to real assets registered in the system.

  • Every position involved is either empty or the position’s public Stark key matches the public Stark key in the request.

  • All signatures in the request are valid with respect to the corresponding public Stark key and message.

  • If a funding tick that occurs before the transaction is executed invalidates the transaction, the transaction is not completed and the funding tick is reverted.

  • Every balance that results from executing the order is within the range (-263, 263).

  • The amounts transferred between Alice and Bob preserve the ratio of Alice’s Total_Account_Value / Total_Maintenance_Margin_Requirement.

    This condition guarantees fairness for users in the system. For example, because Alice has -1 BTC and +29000 USDC, StarkEx can give Alice either of the following:

    • 1 BTC in exchange for 29,000 USDC

    • 0.1 BTC in exchange for 2900 USDC

    StarkEx cannot give Alice either of the following:

    • 0.1 BTC in exchange for 5000 USDC. This exchange is not fair to Alice.

    • 0.1 BTC in exchange for 1000 USDC. This exchange is not fair to Bob.

4. StarkEx includes the Deleverage transaction in a batch.

If the Deleverage transaction is valid, StarkEx includes it in a batch to be submitted on-chain along with the validity proof.

Implementing a Deleverage transaction in your application

To implement deleverage functionality in your application, use the add_transaction API with the Deleverage transaction type.

The StarkEx REST API reference includes all necessary information.

Additional resources