Full WithdrawalsΒΆ

At any point in time, a user may opt to perform a full withdrawal request for a given off-chain vault directly from the contract. This request guarantees that the user either receives the funds via a proof or is able to freeze the contract (and thus the exchange) and withdraw directly from the contract. This ability ensures the self custody aspect of the system. Users can always withdraw their funds: With or without the cooperation of the exchange. Such a request is a different flow than the normal withdrawal flow (see Withdrawals) in the following ways:

  1. The user calls the fullWithdrawalRequest contract function instead of calling an off-chain service REST API.

  2. Upon the successful fulfillment of the operation, the entire vault balance is withdrawn, and it is effectively evicted (no longer belongs to the user). Hence, a full withdrawal request does not include an amount to withdraw.

  3. Failure of the exchange to service a full withdrawal request within a given timeframe gives the user the option to freeze the exchange disabling the ability to update its state.

We describe both possible scenarios - the simple case in which the exchange fulfills the full withdrawal request via a proof, and the mass exit case in which the user freezes the exchange.

sequencediagram-fullwithdrawalwf-0

In the simple case, the full withdrawal request of the user is fulfilled by the exchange within a Grace Period time frame.

  1. The User submits a full withdrawal request by calling fullWithdrawalRequest with the vault ID to be withdrawn.

  2. The Exchange observes the event and sends a full withdrawal request to StarkEx for the specified vault.

  3. StarkEx submits a proof including the full withdrawal to the blockchain.

  4. The user calls the withdraw contract function to withdraw the funds.

The full details of the contract operation in this case can be found here FullWithdrawals.

sequencediagram-fullwithdrawalwf-1

In the mass exit case, the exchange fails to service the full withdrawal request within the Grace Period. The user is then able to freeze the contract. Once frozen, anyone can claim funds by providing Merkle proofs for specific vault contents.

  1. The User submits a full withdrawal request by calling fullWithdrawalRequest with the vault ID to be withdrawn.

  2. The Exchange fails to service the request (does not submit a valid proof as above) within the Grace Period.

  3. The User freezes the contract by calling freezeRequest and indicating the vault ID for which the full withdrawal request has not been serviced.

  4. The User calls the EscapeVerifier contract with the Merkle proof for the vault to be evicted.

  5. The User calls the escape function and the contract adds the vault balance to an on-chain pending withdrawals account under the Stark Key of the vault owner and the appropriate token ID.

  6. The User calls the withdraw function to withdraw funds from the pending withdrawals account.

See Escapes for the full details of the contract operation in this case.