The deposit flow

Before your user can trade, they need to deposit funds into StarkEx. To do so, they first deposit funds to the on-chain StarkEx contract. The application should then send a corresponding off-chain deposit transaction, which updates the off-chain state.
1. Alice deposits funds on-chain.
Alice executes an on-chain transaction to deposit funds. The deposit operation supports deposits of ETH, ERC-20, ERC-721, and ERC-1155.
The on-chain deposit
function gets the following parameters:
starkKey
|
The public Stark key that corresponds to the vault id. |
assetType
|
The asset identifier of the token to be deposited. |
vaultId
|
The recipient’s off-chain account. |
quantizedAmount
|
For ERC-20 and ERC-1155, the amount to be deposited. For ERC-721, this value must be |
A user can deposit to any position, even to one that they do not own. |
For more information, see Identifiers for supported assets and Asset quantities in StarkEx.
2. The application sends an off-chain deposit transaction.
The off-chain application monitors the contract. When the contract emits the event LogDeposit
, the application sends a deposit request transaction to the StarkEx gateway, using the add_transaction
API with the
Deposit
transaction type.
The request includes the following information:
position_id
-
The position ID to deposit to.
public_key
-
The position ID owner’s public Stark key.
amount
-
Amount of collateral asset to be deposited; required to be >= 0.
3. StarkEx validates the deposit request.
StarkEx checks the following constraints:
-
The pending deposits area in the StarkEx smart contract contains enough funds to complete the off-chain deposit.
-
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 deposit in a batch.
If the deposit is valid, it is included in a batch to be submitted on-chain along with the validity proof.
Even before the deposit is proven and the proof is accepted on-chain, the funds already exist in Alice’s off-chain vault, and the application can execute subsequent requests to use these funds. |
5. The smart contract removes funds from the pending deposits area.
As part of the state update, the smart contract deducts the relevant amount of funds from the contract’s pending deposits area.
The application can censor a deposit that is undesirable, such as a deposit to the wrong position, by not transmitting a corresponding deposit request to the StarkEx gateway.
In such a case that user is then able to reclaim their locked on-chain funds by calling the Only the owner of the Stark key that is specified in the on-chain |
Additional resources
-
On-chain functions including
deposit
,depositWithTokenId
, anddepositCancel
in Deposit and withdrawal for off-chain accounts -
StarkEx REST API reference