Withdrawing and escaping without the application’s approval (StarkEx Spot)

In order for a user to take control of their funds without the application’s approval, they need to first execute a full withdrawal and then escape from the contract. The user initiates these operations on-chain.

A valid on-chain request activates a forced action request, but even if the corresponding off-chain transaction itself is invalid, the application nonetheless must serve the request, either fulfilling the request, or proving that the request is invalid.

Forced transactions are irreversible. Neither you nor the user can cancel a forced full withdrawal request.

Withdrawing funds without the application’s approval

Prerequisite
  • The private Stark key that matches the public Stark key of the relevant vault.

  • A block explorer, such as Etherscan.

Procedure
  1. Using a block explorer, such as Etherscan, the user calls the fullWithdrawalRequest function. For more information, see the Full withdrawal reference.

    You must service the request within the amount of time defined by the constant FREEZE_GRACE_PERIOD. The default time period is seven days.

    After receiving the function call, the StarkEx smart contract emits the LogFullWithdrawalRequest event.

    If you serve the request, and the request is proven to be valid, the user can subsequently withdraw their funds to an Ethereum vault.

  2. After the freeze grace period passes, and the forced operation is still in the pending forced operations area, the user calls the freezeRequest function, with the public Stark key and the vault ID from the previous step.

    The exchange becomes frozen, and it can accept no further state updates. Withdrawals of on-chain funds are still possible.

If you do not serve a forced action request within the freeze grace period, then any user, not just the user that submitted the request, can freeze the contract by calling the freezeRequest function with their public Stark key and vault ID.

The user must now escape from the frozen smart contract.

Escaping from a frozen application smart contract

Once the application becomes frozen, the escape operation enables any user to withdraw their funds and leave the application.

Procedure
  1. The user obtains a Merkle path of a vault to be evicted with respect to the frozen vault tree root. Typically, once the application is frozen, such data should be made public or obtainable from an application API, depending on the application’s data availability approach.

  2. The user calls the verifyEscape function with the Merkle proof for the vault to be evicted.

    For information on the structure of the proof, see Escape verifier

    A valid proof results in the registration of the following fact:
    keccak256(starkKey, assetId, quantizedAmount, vaultRoot, height, vaultId).

  3. The user calls the escape function with the same parameters submitted to the Escape verifier.

    If a proof was accepted for the same parameters by the Escape verifier, and no prior escape call was made for the vault, the contract adds the vault balance to an on-chain pending withdrawals account under the public Stark key of the vault owner and the appropriate asset ID.

  4. The user withdraws this amount from the pending withdrawals account by calling the normal on-chain withdraw function to transfer the funds to their ETH or ERC-20 account, depending on the type of token.

    While anyone can perform the initial steps of the escape operation, including the application, for example, only the vault owner can perform the final step of transferring the funds.

Additional resources