On-chain account management

Deposit

Users that want to deposit to an on-chain account call the depositEthToVault or despositERC20toVault functions, which take vaultId, assetId (and also quantized amount, in the case of an ERC-20 deposit). These functions add the relevant amounts to the vaultsBalance mapping.

Due to the way vaultsBalance is defined, vaults can be set arbitrarily by the user — since they aren’t shared between users, or even between different assetId’s that belong to the same user

When the chosen function finishes, the event LogDepositToVault is emitted.

A side effect of making a deposit to an on-chain account is that a lock is placed on the newly deposited funds and existing funds in that vaultId, for the default lock period, locktime. Check out the trade flow for more details as to why. With the lock implemented, the event LogVaultWithdrawalLockSet is emitted.

After the deposit is completed, users can get their current on-chain account balance by calling the getVaultBalance function or get the remaining lock time by calling the getVaultWithdrawalLock function. Both functions receive the eth_address, asset_Id, and vault_id as parameters.

Withdrawal

Users that want to withdraw their funds from an on-chain account call the withdrawalFromVault function. This function verifies that the caller is indeed the owner of the account, that the funds are not locked, and that the balance is sufficient. If all constraints hold, the function passes the user their funds and emits the event LogWithdrawalFromVault.

Layer 1 Limit Order

A user that wants to trade with the funds they have in the on-chain vault against funds on L2 or to initiate a DeFi pooling calls the registerLimitOrder function, supplying the exchange address (the specific StarkEx contract address that this order should be executed on), as well as all the relevant parameters for executing such an order, such as:

  • token type for buy, sell, and fee

  • amounts

  • vaultIds for buy, sell, and fee

  • nonce

  • expiration timestamp

All the vaults that appear on a L1 limit order should belong to on-chain accounts.

Never use the same nonce twice, as it might cause all the parameters of an order to be the same. In such a case, the StarkEx service will not be able to execute.

As discussed above, in order to respect L1 limit orders, the operator might insist that the on-chain account owner lock their funds (if they are not already locked due to a deposit call). In such a case, the user may need to extend the lock period by calling the lockVault function, supplying the Vault specification and the required lock time.