Forced actions and escape hatch

Full Withdrawal

The function fullWithdrawalRequest is a part of an anti-censorship mechanism that lets the user withdraw their funds. The user supplies the vault id and the Stark key. Only the user to whom this Stark key belongs may submit this request. When this function is called, the event LogFullWithdrawalRequest (with the relevant starkKey, vaultId) is emitted.

The Full Withdrawal function consumes a lot of gas and is expected to be used only as an anticensorship mechanism.

For information on regular withdrawals, see The withdrawal flow and Withdrawing funds from the StarkEx contract.

If the application fails to service the request, upon the expiration of a FREEZE_GRACE_PERIOD, the user is entitled to freeze the contract by calling freezeRequest.

The user supplies the vaultId and the Stark key and indicating the vaultId for which the full withdrawal request has not been serviced. Once the contract is frozen, funds can be extracted using the escape operation. For more information, see Escape, below.

A user cannot cancel full withdrawal requests.

To avoid the potential attack of the application by a flood of full withdrawal requests, the rate of such requests must be limited. In the current implementation, this is achieved by making the request’s cost exceed 1M gas.

Escape

Once the application becomes frozen the escape operation is what allows users to withdraw their funds and leave the application.

Any escaper entity/user may perform an escape operation as follows:

  1. Escapers must obtain 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 will be made public or obtainable from an application API, depending on the application’s data availability approach.

  2. Escapers call verifyEscape function on the EscapeVerifier contract with the Merkle proof for the vault to be evicted. See Escape Verifier for more details on the proof structure. A valid proof results in the registration of the following fact - keccak256(starkKey, assetId, quantizedAmount, vaultRoot, height, vaultId).

  3. Escapers call the escape function with the same parameters as submitted to the EscapeVerifier (starkKey, assetId, quantizedAmount, vaultId). If a proof was accepted for the same parameters by the EscapeVerifier, 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 starkKey of the vault owner and the appropriate assetId.

  4. The owner of the vault may then withdraw this amount from the pending withdrawals account by calling the normal withdraw function (see Withdrawal) to transfer the funds to the user’s ETH or ERC-20 account (depending on the token type).

Note that while anyone can perform the initial steps of the escape operation (including the application, for example), only the vault owner may perform the final step of transferring the funds.

Additional resources