The withdrawal flow

withdrawal flow

Your user can only withdraw collateral funds, and only funds that are in excess of what is required to maintain a well-leveraged position.

1. Alice submits an off-chain withdrawal request

Alice sends a withdrawal request using the off-chain application.

The request is signed in order to prevent a malicious operator from issuing withdrawals at their own discretion, which might put Alice’s position below the maintenance margin, enabling the operator to liquidate the position.

StarkEx Perpetual Trading v2.0

The request includes Alice’s signature and Ethereum address.

2. The application sends a withdrawal transaction to StarkEx.

The off-chain application checks the validity of the withdrawal request according to its business logic and the relevant positionId state. If it is valid, it sends the off-chain withdrawal transaction to the StarkEx service using the add_transaction API method with the appropriate transaction type:

  • StarkEx Perpetual Trading v1.0: Withdrawal

  • StarkEx Perpetual Trading v2.0: WithdrawalToAddress

3. StarkEx validates the withdrawal request.

StarkEx checks the following to validate the withdrawal request:

  • The position is properly signed by the Stark key that owns the position.

  • All amounts in the request are ≥ 0.

  • After the transaction is executed one of the following must be true:

    • The resulting position is well leveraged, that is: \(\text{total_value} \ge \text{total_risk}\)

    • Total value per risk (TV/TR) does not decrease after funding is applied, and the position’s total risk decreases or stays the same, which means that for every synthetic asset, \(|\text{new_balance}| \le |\text{old_balance}|\)

4. StarkEx includes the withdrawal in a batch.

If the withdrawal is valid, it is included in a batch to be submitted on-chain along with a validity proof.

5. StarkEx moves the funds to the withdrawal area.

StarkEx Perpetual Trading v1.0

Upon performing a state update, the StarkEx smart contract moves the relevant funds to the withdrawal area, under the Stark key that owns the L2 position from which the funds were withdrawn.

StarkEx Perpetual Trading v2.0

Upon performing a state update, the StarkEx smart contract moves the relevant funds to the withdrawal area, under Alice’s Ethereum address.

6. On-chain withdrawal transaction.

StarkEx Perpetual Trading v1.0

Once the funds are in the withdrawal area, Alice can make an on-chain call to register her Ethereum address, using her Stark key, which enables her to reclaim her funds from the withdrawal area to her Ethereum address.

StarkEx Perpetual Trading v2.0

Once the funds are in the withdrawal area, any user can make an on-chain call to withdraw the funds to the Ethereum address to which the funds belong.

Implementing a withdrawal in your application.

To implement withdrawal functionality in your application, use the add_transaction API with the WithdrawalToAddress transaction type.

The StarkEx REST API reference includes all necessary information.

Additional resources