The deposit flow

deposit flow

Before your user can trade, they need to deposit funds into StarkEx. To do so, they first deposit funds to the onchain StarkEx contract. The application should then send a corresponding offchain deposit transaction, which updates the offchain state.

1. Alice deposits funds onchain.

Alice executes an onchain transaction to deposit funds. The deposit operation supports deposits of ETH, ERC-20, ERC-721, and ERC-1155.

The onchain 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 offchain account.
quantizedAmount

For ERC-20 and ERC-1155, the amount to be deposited. For ERC-721, this value must be 1.

A user can deposit to any vault, 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 offchain deposit transaction.

The offchain 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 DepositRequest transaction type.

The request includes the following information:

vault_id

Vault ID in the StarkEx system.
stark_key

Public Stark key of the party as registered on the StarkEx contract.
token_id

Unique token ID as registered on the StarkEx contract.
amount

Amount of token 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 offchain deposit.

4. StarkEx includes the deposit in a batch.

If the deposit is valid, it is included in a batch to be submitted onchain along with the validity proof.

Even before the deposit is proven and the proof is accepted onchain, the funds already exist in Alice’s offchain 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 vault, by not transmitting a corresponding deposit request to the StarkEx gateway. In such a case that user is then able to reclaim their locked onchain funds by calling the depositCancel function.

Only the owner of the Stark key that is specified in the onchain deposit function can cancel the deposit, even if a different user issued the deposit.

Additional resources