vega-frontend-monorepo/specs/1002-WITH-withdraw.md

Withdraw

Withdrawing funds is a two step process.

First the Vega network needs to approve that the funds can be released (not required for margin on open positions or in liquidity bond etc). If they are not, a withdraw is prepared and set aside so that it can not be used for positions etc. This also define what ethereum address will be credited the funds in step 2.

Second the user will need to run an ethereum function on the bridge contract to release the funds (and pay the gas to do so). They do this using a signature supplied by nodes of the Vega network in Step 1.

Although this is a two step process technically effort should be put into making it feel like one, then handle exceptions (like delays on withdrawals) as required.

See Specs for eth bridge and docs on withdrawals. See also the specs on delays to withdrawals.

Prepare an ERC20 withdraw from Vega

When wishing to withdraw some of an ERC20 asset from Vega, I...

• should be prompted to complete any existing incomplete withdrawals that exist for connected keys (see complete withdrawal)

Note: It is better to encourage the completion of started withdraws as soon as possible after preparing them. This is because the validator set could theoretically change enough to make the node signatures that authorize the withdrawal invalid.

• should be warned that they will need to pay gas on the withdrawal before starting
• could show the current gas fees BEFORE preparing the withdrawal (note: shows gas estimate is a general should for all ethereum transactions but this is so a user gets to see the gas costs at step 1 assuming they will do step 2 immediately. )

Note: A user may want to delay preparing a withdrawal if gas fees on the network are particularly high at the time

• must select the asset to withdraw (1002-WITH-001)

  • should not see option to select assets where I a zero total balance (note this should also avoid Pending assets from appearing in the list)
  • must see the general balance I have for that asset (1002-WITH-002)
  • should see balances to the full number of decimal places possible for that asset
  • should see the total balances of the assets I have
  • could see a breakdown of other accounts I have in this asset and their balances

• must select the amount of the asset I wish to withdraw (1002-WITH-003)

  • should have an easy option (link/button) to input the full amount in general balance
  • must be able to specify as many decimal places as the asset supports (1002-WITH-004)

• must be warned if the amount is greater than general balance (including if the general balance amount changes while the user is looking at the form) (1002-WITH-005)

• must be warned if the amount is lesser than the minimum allowed, where the minimum amount is the selected asset's quantum multiplied by the value of spam.protection.minimumWithdrawalQuantumMultiple network parameter (1002-WITH-026)

• should see a link to a faucet on the selected asset (only if there is one)

• must specify the Ethereum address that can claim the withdrawal (e.g. where you are withdrawing too) (1002-WITH-006)

  • should be able to easily select an Ethereum key the app is already connected to
  • should be able to withdraw to a different Ethereum key to the one the app is connected to
  • should be warned if the input does not look like an ethereum address (wrong number of characters, not starting with 0x etc)

• if there is a withdraw delay on the selected asset:

  • should see how large a withdrawal (or sum of withdrawals) needs to be to hit the withdraw delay threshold
  • should see what the withdraw delay is in hours and mins (if hit)
  • should see how much I have withdrawn in the last withdraw delay period
  • must be warned if this withdraw will hit a the delay before hitting withdraw (1002-WITH-007)

• must be warned if there are known reasons that the prepared withdrawal will not work (1002-WITH-008)

• must submit a withdraw vega transaction (1002-WITH-009)

• if the preparing the withdraw on Vega fails:

  • must be directed back to the withdraw form (containing the submitted values) and see an explanation of why the transaction failed, so I can fix and resubmit (1002-WITH-010)

• if the preparing the withdraw on Vega is successful:

  • must see that withdraw is prepared (1002-WITH-011)
  • if this withdraw will not hit the withdrawal threshold:
    • should be prompted to complete the transaction on ethereum (see complete ERC20 withdraw)
    • could be directed to a list of incomplete withdrawals
  • if this withdraw will hit withdrawal threshold:
    • must see that the withdraw has been complete and is in the list waiting for the delay to pass (1002-WITH-024)

...so that I can get the details required to release my funds from the the Ethereum ERC20 bridge.

Withdraws list / history

When looking to either complete a withdraw or view past withdraws, I...

• must be able to navigate to a list prepared withdrawals for the connected to a vega wallet + key(s)

• for each prepared withdraw:

  • must see the asset being withdrawn (1002-WITH-012)
  • must see the amount being withdrawn (1002-WITH-013)
  • must see the destination of the withdrawal (e.g. Recipient Eth address) (1002-WITH-014)
  • should see the date with withdraw was prepared
  • could see the full signature bundle from Vega node (for use on Ethereum)
  • for withdraws that are in progress:
    • must see the status of the withdraw (e.g. pending) (1002-WITH-015)
  • for completed withdraws:
    • could see when it was completed on native chain (e.g. ethereum)
    • must see a link to the transaction on native block explorer (e.g. etherscan) (1002-WITH-016)
  • for withdraws that have not been completed on the external chain, but are not delayed (e.g. Ethereum):
    • must see a link to complete the withdraw. See complete ERC20 withdrawal (1002-WITH-017)
  • for withdrawals that have a delay in place before the transaction can be completed:
    • should see much of the delay remains before it can be completed
  • for withdraws that failed to be prepared (e.g. there was not enough in the general account):
    • must show that the withdraw preparation failed (1002-WITH-025)

... so I can complete withdrawals or find details of previous ones

Complete ERC20 withdraw from Ethereum bridge

When looking to submit the Ethereum transaction to release funds from the Vega bridge into my Ethereum wallet, I...

• must see a link to connect an ethereum wallet if not already connected (1002-WITH-018)

• must see a link to submit the ethereum transaction to finish withdrawal (1002-WITH-019)

• could be warned if the connected ethereum wallet is different to the one that the withdraw is going to credit (this is permitted but is a good reminder to the user about what to expect)

• if successful:

  • must see asset balances have been updated post withdrawal (1002-WITH-020)
  • must see the list of withdrawals (with updated status) (1002-WITH-021)
  • could see prompt to start another transaction or complete another incomplete one

• if failed:

  • must see a description of why the transaction failed, and advised what to do (e.g. bad signature) (1002-WITH-022)
  • must be returned to a state where I can correct anything that is wrong, and attempt to submit the transaction again (1002-WITH-023)
  • should see a link to docs about withdrawals for trouble shooting (e.g. if the signer set has changed significantly since the withdraw was prepared)
  • should see status of incomplete withdrawals (so I can confirm the withdraw I attempted to complete is incomplete)

... so the funds I withdrew from Vega are credited to my Ethereum key