Merge pull request #847 from vegaprotocol/managing-tokens

Withdrawing guides

docs/tutorials/assets-tokens/withdrawing-assets.md

@@ -12,31 +12,36 @@ import NetworkParameter from '@site/src/components/NetworkParameter';
 import EthAddresses from '@site/src/components/EthAddresses';
 
 :::caution Completing a withdrawal
-Before beginning a withdrawal, it is worth confirming that there's no scheduled network restart or upgrade in the following 48 hours.
+Before beginning a withdrawal, it is worth confirming that there's no scheduled network restart or upgrade in the next 48 hours.
 
 * Withdrawals may be subject to a delay once started.
 * Any withdrawals that are left 'in progress' during a network restart or upgrade will not be visible in any UI or API request. **Your assets will be safe** but you will need to get the details of your transaction. See the instructions below for how to do this.
 :::
 
-The easiest way to withdraw assets is to use the Console trading interface, which will walk you through the process and notify you of progress. However, if you'd like to interact directly with Etherscan instead, use the instructions below.
+## Withdraw your trading assets
+If you want to withdraw assets from your general account, you won't need to take any extra steps.
 
-## What you need
-You'll need the following information available:
-* Vega public key you want to withdraw from
-* Vega Wallet connection details (wallet name, passphrase)
-* ERC-20 bridge logic address
-* Vega asset ID
-* Receiver Ethereum address for the withdrawal
+To remove all assets from your public key, you'll need to close all your open positions, cancel your liquidity commitments, if you have any, and redeem your vested staking and trading rewards.
 
-### Bridge address 
-The ERC-20 bridge address shown is for the Ethereum network that is compatible with the Vega network these docs are pointing to. 
+If you plan to stop using the key entirely, check if you have any [VEGA tokens](./withdrawing-vega-tokens.md#check-the-status-of-your-vega) connected to it.
 
-<EthAddresses frontMatter={frontMatter} show={["ERC20Bridge"]} />
+Console has a step-by-step process to move your assets out of Vega; this is the easiest way to withdraw them. If you want to use Etherscan instead, follow the [instructions](#withdraw-using-etherscan) below.
+
+## Withdraw your rewards
+Assets received as rewards may be locked for a time. Each epoch, a percentage of the locked amount begins vesting. Any amount that is vested is moved into a vested account. From there, you can redeem vested tokens by transferring them into your general account. Then, they can be withdrawn to an Ethereum address.
+
+1. You can check the status of all your assets using the [Explorer dApp](https://explorer.fairground.wtf) by providing your public key. 
+
+2. Any assets that are listed on Explorer as in the "Vested account" need to be redeemed. Assets that are locked or vesting can't be moved *yet*. To redeem your vested rewards, go to the rewards page on [Console](https://vegafairground.eth.limo/#/rewards). From there you can transfer those tokens from your vested account into your general account by clicking on "redeem rewards".
+
+  a. From the Governance dApp, you can click on Redeem on the wallet sidebar. This will take you to Console where you can transfer those assets to your Vega general account.
+
+3. Assets in your general account on Vega can be withdrawn to your Ethereum address using Console's step-by-step process. This is the easiest way to withdraw them. If you want to use Etherscan instead, follow the instructions below.
 
 ## Withdrawal delays and thresholds
 Assets can have a withdrawal delay, as well as a withdrawal delay threshold. 
 
-**Withdrawal delay**: Set on the ERC-20 bridge for all assets. It is the time that a withdrawal is delayed, once it's begun, before it can be completed. You can see the delay by looking at the ERC-20 bridge contract. 
+**Withdrawal delay**: Set on the ERC-20 bridge for all assets. It is the time that a withdrawal is delayed once it's started, before it can be completed. You can see the delay by looking at the ERC-20 bridge contract. 
 
 **Withdrawal delay threshold**: Set per asset in its governance proposal. Requesting to withdraw that amount (and above) will trigger a withdrawal delay. If the threshold is 1, that denotes the smallest decimal position for the market's asset, and thus all withdrawals will have a delay. [Query for an asset's details](../../api/rest/data-v2/trading-data-service-get-asset.api.mdx) (under erc20) to see each asset's delay threshold.
 
@@ -46,6 +51,19 @@ Once the delay time has passed, and if the bundle is valid, the withdrawal **mus
 
 ## Withdraw using Etherscan
 
+### What you need 
+You'll need the following information available:
+* Vega public key you want to withdraw from
+* Vega Wallet connection details (wallet name, passphrase)
+* ERC-20 bridge logic address
+* Vega asset ID
+* Receiver Ethereum address for the withdrawal
+
+### Bridge address 
+The ERC-20 bridge address shown is for the Ethereum network that is compatible with the Vega network these docs are pointing to. 
+
+<EthAddresses frontMatter={frontMatter} show={["ERC20Bridge"]} />
+
 ### Prepare and send withdrawal transaction
 
 You'll need to prepare a withdrawal transaction to send using your Vega Wallet app.

docs/tutorials/assets-tokens/withdrawing-vega-tokens.md

@@ -0,0 +1,66 @@
+---
+title: Withdraw VEGA tokens
+sidebar_position: 5
+hide_title: false
+vega_network: TESTNET
+description: Withdraw staked, claimed or reward VEGA tokens
+---
+
+## Check the status of your VEGA
+
+How to withdraw your VEGA tokens depends on the status of the tokens. You can withdraw any tokens that are *unlocked*, or that are already held by your Ethereum address.
+
+In a nutshell, tokens may be locked for a time. How they're locked depends on how you came to receive them.
+
+If your tokens are in the *vesting contract*, they will need to be unlocked before you can remove them from the Vega network. VEGA in the vesting contract is broken up by tranches, which unlock block by block until each tranche's tokens are fully available.
+
+If you received them as *trading rewards*, each epoch, a percentage of locked tokens begin vesting. Once they're vested, they are moved into a vested account. From there, you can redeem vested tokens by transferring them into your general account, at which point they can be withdrawn.
+
+1. Search for your Ethereum address into the redeem page on the [governance dApp](https://governance.fairground.wtf/token/redeem). 
+
+2. If you are connected to your Ethereum and Vega wallets, you can also see a breakdown of your tokens and their status in the wallet sidebar.
+
+## Remove tokens from Vega that are stored on Ethereum
+
+For tokens that are already in your Ethereum wallet, and not locked, vesting or vested with Vega, you can remove them from Vega almost immediately.
+
+### Remove staked VEGA
+If your tokens are associated to a Vega key and staked to a validator: 
+
+1. To remove your tokens immediately, use the governance dApp to [disassociate](https://governance.fairground.wtf/token/disassociate) the tokens from your Vega key. This will also remove any validator nominations you have. You'll lose any accrued staking rewards for the current epoch.
+
+2. To receive the current epoch's staking rewards, use the governance dApp. 
+    a. Visit the [validators](https://governance.fairground.wtf/validators) page.
+
+    b. Click on "Staked by me". 
+
+    c. Choose a validator to remove stake from, and how much you want to remove. Click "Remove $VEGA tokens at the end of the epoch."
+
+    d. You'll need to remove stake from each validator individually.
+
+### Remove unstaked VEGA
+Tokens that are not held in a tranche and are associated to a Vega key, but not used for staking validators are easy to remove from the Vega network.
+
+All you need to do is [disassociate](https://governance.fairground.wtf/token/disassociate) the tokens from your Vega key.
+
+## Withdraw VEGA from the vesting contract
+
+For VEGA tokens that are in the vesting contract and are now unlocked, you will need to disassociate and then redeem them. This moves the VEGA directly to your Ethereum address.
+
+1. [Disassociate](https://governance.fairground.wtf/token/disassociate) your vested tokens. If you have nominated validators, disassociating without removing your nomination means you'll lose any staking rewards for that epoch. You can choose to un-nominate at the end of the epoch if you'd rather not lose rewards.
+
+2. Redeem your tokens to move them to your Ethereum address. Visit the Redeem page on the [Governance dApp](https://governance.fairground.wtf/token/redeem), enter the Ethereum address you used for those VEGA tokens, and follow the instructions.
+
+## Withdraw VEGA received as rewards
+
+Rewards also go through a vesting process, which is different from tokens in the vesting contract. Those tokens are held in accounts on Vega until they become vested. At that point, they can be moved into your general account on Vega, after which they can be withdrawn from the Vega network to the Ethereum network.
+
+1. If you have associated your tokens to your Vega key for staking purposes, [disassociate](https://governance.fairground.wtf/token/disassociate) them. Disassociating without removing your validator nominations means you'll lose any staking rewards for that epoch. You can choose to un-nominate at the end of the epoch if you'd rather not lose rewards.
+
+2. Redeem your tokens to move them to your general account on Vega. You can redeem using either the Governance dApp or Console.
+
+    a. On the [Governance dApp](https://governance.fairground.wtf), you can click on Redeem on the wallet sidebar, which will take you to Console where you can transfer those tokens to your general account.
+
+    b. On [Console](https://vegafairground.eth.limo/#/rewards) under Rewards, you can see any tokens or assets that are available to redeem. From there you can transfer those tokens from your vested account into your general account.
+
+3. Withdraw tokens from Vega to your Ethereum wallet. In Console, you can use the Withdraw icon in the right sidebar to initiate your withdrawal into your Ethereum address. To use Etherscan, follow the [withdrawing assets tutorial](./withdrawing-assets.md).

versioned_docs/version-v0.73/tutorials/assets-tokens/withdrawing-assets.md

@@ -17,26 +17,30 @@ Before beginning a withdrawal, it is worth confirming that there's no scheduled
 * Withdrawals may be subject to a delay once started.
 * Any withdrawals that are left 'in progress' during a network restart or upgrade will not be visible in any UI or API request. **Your assets will be safe** but you will need to get the details of your transaction. See the instructions below for how to do this.
 :::
+## Withdraw your trading assets
+If you want to withdraw assets from your general account, you won't need to take any extra steps.
 
-The easiest way to withdraw assets is to use the Console trading interface, which will walk you through the process and notify you of progress. However, if you'd like to interact directly with Etherscan instead, use the instructions below.
+To remove all assets from your public key, you'll need to close all your open positions, cancel your liquidity commitments, if you have any, and redeem your vested staking and trading rewards.
 
-## What you need
-You'll need the following information available:
-* Vega public key you want to withdraw from
-* Vega Wallet connection details (wallet name, passphrase)
-* ERC-20 bridge logic address
-* Vega asset ID
-* Receiver Ethereum address for the withdrawal
+If you plan to stop using the key entirely, check if you have any [VEGA tokens](./withdrawing-vega-tokens.md#check-the-status-of-your-vega) connected to it.
 
-### Bridge address 
-The ERC-20 bridge address shown is for the Ethereum network that is compatible with the Vega network these docs are pointing to. 
+Console has a step-by-step process to move your assets out of Vega; this is the easiest way to withdraw them. If you want to use Etherscan instead, follow the instructions below.
 
-<EthAddresses frontMatter={frontMatter} show={["ERC20Bridge"]} />
+## Withdraw your rewards
+Assets received as rewards may be locked for a time. Each epoch, a percentage of the locked amount begins vesting. Any amount that is vested is moved into a vested account. From there, you can redeem vested tokens by transferring them into your general account. Then, they can be withdrawn to an Ethereum address.
+
+1. You can check the status of all your assets using the [Explorer dApp](https://explorer.vega.xyz) by providing your public key. 
+
+2. Any assets that are listed on Explorer as in the "Vested account" need to be redeemed. Assets that are locked or vesting can't be moved *yet*. To redeem your vested rewards, go to the rewards page on [Console](https://vegaprotocol.eth.limo/#/rewards). From there you can transfer those tokens from your vested account into your general account by clicking on "redeem rewards".
+
+  a. From the Governance dApp, you can click on Redeem on the wallet sidebar. This will take you to Console where you can transfer those assets to your Vega general account.
+
+3. Assets in your general account on Vega can be withdrawn to your Ethereum address using Console's step-by-step process. This is the easiest way to withdraw them. If you want to use Etherscan instead, follow the instructions below.
 
 ## Withdrawal delays and thresholds
 Assets can have a withdrawal delay, as well as a withdrawal delay threshold. 
 
-**Withdrawal delay**: Set on the ERC-20 bridge for all assets. It is the time that a withdrawal is delayed, once it's begun, before it can be completed. You can see the delay by looking at the ERC-20 bridge contract. 
+**Withdrawal delay**: Set on the ERC-20 bridge for all assets. It is the time that a withdrawal is delayed once it's started, before it can be completed. You can see the delay by looking at the ERC-20 bridge contract. 
 
 **Withdrawal delay threshold**: Set per asset in its governance proposal. Requesting to withdraw that amount (and above) will trigger a withdrawal delay. If the threshold is 1, that denotes the smallest decimal position for the market's asset, and thus all withdrawals will have a delay. [Query for an asset's details](../../api/rest/data-v2/trading-data-service-get-asset.api.mdx) (under erc20) to see each asset's delay threshold.
 
@@ -46,6 +50,19 @@ Once the delay time has passed, and if the bundle is valid, the withdrawal **mus
 
 ## Withdraw using Etherscan
 
+### What you need 
+You'll need the following information available:
+* Vega public key you want to withdraw from
+* Vega Wallet connection details (wallet name, passphrase)
+* ERC-20 bridge logic address
+* Vega asset ID
+* Receiver Ethereum address for the withdrawal
+
+### Bridge address 
+The ERC-20 bridge address shown is for the Ethereum network that is compatible with the Vega network these docs are pointing to. 
+
+<EthAddresses frontMatter={frontMatter} show={["ERC20Bridge"]} />
+
 ### Prepare and send withdrawal transaction
 
 You'll need to prepare a withdrawal transaction to send using your Vega Wallet app.

versioned_docs/version-v0.73/tutorials/assets-tokens/withdrawing-vega-tokens.md

@@ -0,0 +1,66 @@
+---
+title: Withdraw VEGA tokens
+sidebar_position: 5
+hide_title: false
+vega_network: TESTNET
+description: Withdraw staked, claimed or reward VEGA tokens
+---
+
+## Check the status of your VEGA
+
+How to withdraw your VEGA tokens depends on the status of the tokens. You can withdraw any tokens that are *unlocked*, or that are already held by your Ethereum address.
+
+In a nutshell, tokens may be locked for a time. How they're locked depends on how you came to receive them.
+
+If your tokens are in the *vesting contract*, they will need to be unlocked before you can remove them from the Vega network. VEGA in the vesting contract is broken up by tranches, which unlock block by block until each tranche's tokens are fully available.
+
+If you received them as *trading rewards*, each epoch, a percentage of locked tokens begin vesting. Once they're vested, they are moved into a vested account. From there, you can redeem vested tokens by transferring them into your general account, at which point they can be withdrawn.
+
+1. Search for your Ethereum address into the redeem page on the [governance dApp](https://governance.vega.xyz/token/redeem). 
+
+2. If you are connected to your Ethereum and Vega wallets, you can also see a breakdown of your tokens and their status in the wallet sidebar.
+
+## Remove tokens from Vega that are stored on Ethereum
+
+For tokens that are already in your Ethereum wallet, and not locked, vesting or vested with Vega, you can remove them from Vega almost immediately.
+
+### Remove staked VEGA
+If your tokens are associated to a Vega key and staked to a validator: 
+
+1. To remove your tokens immediately, use the governance dApp to [disassociate](https://governance.vega.xyz/token/disassociate) the tokens from your Vega key. This will also remove any validator nominations you have. You'll lose any accrued staking rewards for the current epoch.
+
+2. To receive the current epoch's staking rewards, use the governance dApp. 
+    a. Visit the [validators](https://governance.vega.xyz/validators) page.
+
+    b. Click on "Staked by me". 
+
+    c. Choose a validator to remove stake from, and how much you want to remove. Click "Remove $VEGA tokens at the end of the epoch."
+
+    d. You'll need to remove stake from each validator individually.
+
+### Remove unstaked VEGA
+Tokens that are not held in a tranche and are associated to a Vega key, but not used for staking validators are easy to remove from the Vega network.
+
+All you need to do is [disassociate](https://governance.vega.xyz/token/disassociate) the tokens from your Vega key.
+
+## Withdraw VEGA from the vesting contract
+
+For VEGA tokens that are in the vesting contract and are now unlocked, you will need to disassociate and then redeem them. This moves the VEGA directly to your Ethereum address.
+
+1. [Disassociate](https://governance.vega.xyz/token/disassociate) your vested tokens. If you have nominated validators, disassociating without removing your nomination means you'll lose any staking rewards for that epoch. You can choose to un-nominate at the end of the epoch if you'd rather not lose rewards.
+
+2. Redeem your tokens to move them to your Ethereum address. Visit the Redeem page on the [Governance dApp](https://governance.vega.xyz/token/redeem), enter the Ethereum address you used for those VEGA tokens, and follow the instructions.
+
+## Withdraw VEGA received as rewards
+
+Rewards also go through a vesting process, which is different from tokens in the vesting contract. Those tokens are held in accounts on Vega until they become vested. At that point, they can be moved into your general account on Vega, after which they can be withdrawn from the Vega network to the Ethereum network.
+
+1. If you have associated your tokens to your Vega key for staking purposes, [disassociate](https://governance.vega.xyz/token/disassociate) them. Disassociating without removing your validator nominations means you'll lose any staking rewards for that epoch. You can choose to un-nominate at the end of the epoch if you'd rather not lose rewards.
+
+2. Redeem your tokens to move them to your general account on Vega. You can redeem using either the Governance dApp or Console.
+
+    a. On the [Governance dApp](https://governance.vega.xyz), you can click on Redeem on the wallet sidebar, which will take you to Console where you can transfer those tokens to your general account.
+
+    b. On [Console](https://vegaprotocol.eth.limo/#/rewards) under Rewards, you can see any tokens or assets that are available to redeem. From there you can transfer those tokens from your vested account into your general account.
+
+3. Withdraw tokens from Vega to your Ethereum wallet. In Console, you can use the Withdraw icon in the right sidebar to initiate your withdrawal into your Ethereum address. To use Etherscan, follow the [withdrawing assets tutorial](./withdrawing-assets.md).