The 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.
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.
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.
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.
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.
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
-
StarkEx REST API reference
-
Structure of a
WithdrawalToAddress
transaction (StarkEx Perpetual Trading 2.0) -
Structure of a
Withdrawal
transaction (StarkEx Perpetual Trading 1.0)