Merge pull request #777 from oasisprotocol/matevz/docs/manage-tokens-…

…revamp

docs: Revamp manage-tokens chapters

README.md

@@ -204,14 +204,18 @@ There are three kinds of image assets used in the docs.
 The following is a consistent case-sensitive collection of Oasis-related terms,
 and their usage including the articles:
 
+- Bech32
 - c10l
   Check out the c10l-hello-world folder for the confidential version of the
   original example.
 - c13y
   EVM with added c13y.
+- CBOR
 - Cipher
 - consensus layer
   The consensus layer makes sure that the ParaTimes tick.
+- Ed25519
+  The consensus layer only supports the Ed25519 signature scheme.
 - Emerald
 - dApp
   Emerald supports writing dApps. DApp is a modern distributed application.
@@ -224,6 +228,8 @@ and their usage including the articles:
 - Oasis CLI
   You can use the Oasis CLI to set up your wallet.
 - Oasis Core
+- Oasis Network
+  The Oasis Network is a proof-of-stake network.
 - OPL
   Oasis Privacy Layer supports privacy of dApps on all EVM chains.
 - ParaTime
@@ -234,11 +240,15 @@ and their usage including the articles:
   Please send 10.00000000 ROSE to the address above.
 - runtime
 - Sapphire
+- secp256k1
+  The Koblitz curve secp256k1 parameters are deterministic.
+- Sr25519
 - TEST
   Please send 10.00000000 TEST to the address above.
 - trusted execution environment
 - validator
 - validator node
+- Wasm
 - Web3 gateway
   We strongly suggest that you set up your own Web3 gateway for your Sapphire
   endpoint.

docs/dapp/cipher/README.mdx

@@ -85,7 +85,7 @@ public list above, open an issue at [github.com/oasisprotocol/docs].
 ## See also
 
 <DocCardList items={[
-    findSidebarItem('/general/manage-tokens/how-to-transfer-rose-into-paratime'),
+    findSidebarItem('/general/manage-tokens/'),
     findSidebarItem('/node/run-your-node/paratime-node'),
     findSidebarItem('/node/run-your-node/paratime-client-node'),
     findSidebarItem('/dapp/emerald/'),

docs/dapp/emerald/README.mdx

@@ -95,7 +95,7 @@ to be added to the public list above, open an issue at
 ## See also
 
 <DocCardList items={[
-    findSidebarItem('/general/manage-tokens/how-to-transfer-rose-into-paratime'),
+    findSidebarItem('/general/manage-tokens/'),
     findSidebarItem('/node/run-your-node/paratime-node'),
     findSidebarItem('/node/run-your-node/paratime-client-node'),
     findSidebarItem('/node/web3'),

docs/dapp/emerald/integrating-band-oracle-smart-contract.md

@@ -16,7 +16,7 @@ contracts. You can read more about the specific details of the protocol
 2. Compile the contract with compiler version `0.6.11`.
 3. Switch to the Deploy tab of Remix.
    1. Select "Injected Web3" in the Environment dropdown in the top left to connect Metamask.
-   2. Make sure that Metamask is connected to the Emerald (Testnet/Mainnet) network. You can read about adding Emerald network to Metamask [here](../../general/manage-tokens/how-to-transfer-rose-into-paratime.mdx#metamask).
+   2. Make sure that Metamask is connected to the Emerald (Testnet/Mainnet) network. You can read about adding Emerald network to Metamask [here](../../general/manage-tokens/#metamask).
 
 ![Setting up the environment in Remix](../images/emerald/band_demooracle_smartcontract.png)
 

docs/dapp/emerald/writing-dapps-on-emerald.mdx

@@ -40,7 +40,7 @@ ParaTime][how-to-deposit-rose] chapter to learn more.
 [overview]: ../../general/oasis-network/README.mdx
 [Ed25519]: https://en.wikipedia.org/wiki/EdDSA#Ed25519
 [ECDSA]: https://en.wikipedia.org/wiki/Elliptic_Curve_Digital_Signature_Algorithm
-[how-to-deposit-rose]: ../../general/manage-tokens/how-to-transfer-rose-into-paratime.mdx
+[how-to-deposit-rose]: ../../general/manage-tokens/README.mdx
 [Testnet faucet]: https://faucet.testnet.oasis.io/
 
 ## Testnet and Mainnet
@@ -373,7 +373,7 @@ Oasis Emerald blockchain! Should you have any questions, do not hesitate to
 share them with us on the [#emerald-paratime Discord channel][discord].
 
 [Remix]: https://remix.ethereum.org
-[metamask]: ../../general/manage-tokens/how-to-transfer-rose-into-paratime.mdx#verifying-rose-balance-on-paratime
+[metamask]: ../../general/manage-tokens/README.mdx#check-your-account
 [discord]: https://oasis.io/discord
 
 ## Troubleshooting

docs/dapp/sapphire/README.mdx

@@ -101,7 +101,7 @@ to be added to the public list above, open an issue at
 ## See also
 
 <DocCardList items={[
-    findSidebarItem('/general/manage-tokens/how-to-transfer-rose-into-paratime'),
+    findSidebarItem('/general/manage-tokens/'),
     findSidebarItem('/node/run-your-node/paratime-node'),
     findSidebarItem('/node/run-your-node/paratime-client-node'),
     findSidebarItem('/node/web3'),

docs/general/manage-tokens/README.mdx

@@ -1,30 +1,188 @@
-import DocCardList from '@theme/DocCardList';
-import {findSidebarItem} from '@site/src/sidebarUtils';
+---
+description: Transfer, deposit, withdraw and delegate your ROSE
+---
 
-# Overview
+# Manage your Tokens
 
-This documentation will guide you on how to use your ROSE tokens, where to keep them, how to transfer them, how to stake/delegate them, and more.
+The **native token** on Oasis Mainnet is called **ROSE**. The native token plays
+a crucial security role in the proof-of-stake block validation protocol and in
+participating on governance proposal votes. Staking rewards are paid out in the
+native token and smart contract users pay gas fees with ROSE.
 
-## Summary
+## ROSE and the ParaTimes
 
-* For **self-custody**, we recommend using one of our **official** [**Oasis Wallets**](oasis-wallets/README.mdx), [Web](oasis-wallets/web.md) or [Browser Extension](oasis-wallets/browser-extension.md).
-* ROSE is supported via three [**custody providers**](holding-rose-tokens/custody-providers.md): [Copper.co](https://copper.co), [Anchorage](https://anchorage.com) and [Finoa](https://finoa.io).
-* For extra security with self-custody, we recommend using the [Ledger](https://www.ledger.com) wallet with one of our official [Oasis Wallets](oasis-wallets/README.mdx).
-* For experienced developers/power users, we offer [Oasis CLI Tools](cli/README.md).
+The [Oasis Network architecture] separates between the **consensus** and the
+**compute** layer. The consensus layer and each ParaTime running on the compute
+layer have their own **ledger** containing, among other data, the **balances of
+the accounts**.
+
+You can only use your ROSE token **one place at a time**—either on the consensus
+layer or inside an individual ParaTime. Moving tokens from the consensus layer
+to a ParaTime is a **deposit** and moving them from a ParaTime back to
+the consensus layer is a **withdrawal** (see [ADR-3] for technical
+specifications). You can **transfer** tokens from your account to another
+account only, if both accounts are either on the consensus layer or inside the
+same ParaTime. Besides moving the tokens across layers and accounts, you can also
+**[delegate tokens]** to a validator and **earn passive income** as a reward.
+
+![Deposits, withdrawals, transfers](../images/manage-tokens/transfer_deposit_withdrawal.svg)
+
+[delegate tokens]: staking-and-delegating.md
+[ADR-3]: ../../adrs/0003-consensus-runtime-token-transfer.md
+[Oasis Network architecture]: ../oasis-network/README.mdx
+
+## The Wallets
+
+To sign the token-related transactions such as transfers, deposits, withdrawals
+and delegations described above, you need a **private key** tied to the
+corresponding account. Your keys are stored in *[crypto wallets]*.
+
+[crypto wallets]: https://en.wikipedia.org/wiki/Cryptocurrency_wallet
 
 :::caution
 
-For your own security and peace of mind, please only use wallets that are listed in our official documentation. Any other wallets are likely unofficial and may be subject to critical security vulnerabilities and other technical issues. Using wallets that not listed in our official documentation could result in the permanent loss of your ROSE tokens.
+For your own security and peace of mind, please only use the wallets that are
+listed here. **Using unofficial wallets can result in the permanent loss of your
+ROSE!**
 
 :::
 
-## Quick Navigation
+### Non-Custodial Oasis Wallets
+
+The Oasis team developed the following **non-custodial wallets** for you. This
+means that the keys for managing the tokens are **stored on your device** such
+as a laptop or a mobile phone and **you are responsible to keep it safe**:
+
+- **[Oasis ROSE Wallet - Web]**: Runs as a web application in your web browser, the private keys are encrypted
+  with a password and stored inside your Browser's local store.
+
+- **[Oasis ROSE Wallet - Browser extension]**: Runs as an extension to your Chrome-based browser, the private keys are
+  encrypted with a password and stored inside your Browser's encrypted store.
+
+- **[Oasis CLI]**: Runs in a command line, suitable for automation, the private keys are
+  encrypted by a password and stored inside your home folder.
+
+[Oasis ROSE Wallet - Web]: oasis-wallets/web.mdx
+[Oasis ROSE Wallet - Browser extension]: oasis-wallets/browser-extension.mdx
+[Oasis CLI]: cli/README.md
+
+### MetaMask
+
+[MetaMask] is probably the most-known crypto wallet. However, it is an
+**EVM-compatible** wallet. This means **you can only use it to check the account
+balances and sign transactions on Sapphire and Emerald chains**. You cannot use
+it, for example, to sign **consensus layer transactions** or perform
+**deposits** and **withdrawals** to and from ParaTimes.
+
+You can add the Sapphire RPC endpoint by clicking on the "Add to MetaMask"
+button next to your preferred Mainnet endpoint provider in the [Sapphire]
+chapter. Similarly, you will find a list of RPC endpoints for Emerald on the
+[Emerald] page.
+
+![Metamask - Adding Sapphire Mainnet Network Configuration](../images/wallet/metamask/settings.png)
+
+[MetaMask]: https://metamask.io/download/
+[Sapphire]: ../../dapp/sapphire/README.mdx#rpc-endpoints
+[Emerald]: ../../dapp/emerald/README.mdx#rpc-endpoints
+
+### Ledger
+
+The wallets above are just carefully programmed computer programs that store
+your keys (in an encrypted form) somewhere on your disk and then use them to
+sign the transactions. However, if your device gets infected with a piece of
+malicious software (malware, key loggers, screen captures), **the password to
+decrypt your private keys may be obtained and your private keys stolen**.
+
+To mitigate such attacks, a **hardware wallet** can be used. This is a physical
+device which stores your private key and which is only accessed when you send
+the hardware wallet a transaction to be signed. The transaction is then decoded,
+shown on the hardware wallet screen for a user to verify and if the user agrees,
+the transaction is signed and sent back to your computer or mobile device to be
+submitted. The Oasis team **integrated support for Ledger hardware wallets into all Oasis
+wallets**. Check out a [special chapter][Ledger] devoted to the Ledger wallet.
+
+[Ledger]: holding-rose-tokens/ledger-wallet.md
+
+### Custodial Services
+
+It is up to you to pick the right strategy for keeping the private key of your
+account holding your tokens safe. Some users may decide to trust their tokens to
+a **custody provider**. You can read more about those in the
+[Custody providers][custody-providers] chapter.
+
+[custody-providers]: holding-rose-tokens/custody-providers.md
 
-<DocCardList items={[
-    findSidebarItem('/general/manage-tokens/terminology'),
-    findSidebarItem('/general/manage-tokens/staking-and-delegating'),
-    findSidebarItem('/general/manage-tokens/oasis-wallets/'),
-    findSidebarItem('/general/manage-tokens/cli/'),
-    findSidebarItem('/general/manage-tokens/holding-rose-tokens/custody-providers'),
-    findSidebarItem('/general/manage-tokens/holding-rose-tokens/ledger-wallet'),
-]} />
+## Account Formats and Signature Schemes
+
+Transactions on the consensus layer must be signed using the **ed25519
+signature scheme**. The addresses on the consensus layer use the
+**[Bech-32 encoding]** and you can recognize them by a typical `oasis1` prefix.
+
+ParaTimes can implement arbitrary signature schemes and address encodings. For
+example, since the Sapphire and Emerald ParaTimes are EVM-compatible, they
+implement the **secp256k1** scheme and prefer the **hex-encoded**
+addresses and private keys starting with `0x`.
+
+The table below summarizes the current state of the address formats, signature
+schemes and compatible wallets.
+
+| Consensus or ParaTime | Address Format | Digital Signature Scheme    | Supported Wallets                                           |
+|-----------------------|----------------|-----------------------------|-------------------------------------------------------------|
+| Consensus             | `oasis1`       | ed25519                     | <ul><li>Oasis Wallet - Web</li><li>Oasis Wallet - Browser Extension</li><li>Oasis CLI</li></ul> |
+| Sapphire              | `0x`, `oasis1` | secp256k1, ed25519, sr25519 | <ul><li>Metamask and other EVM-compatible wallets (transfers only)</li><li>Oasis Wallet - Browser Extension</li><li>Oasis Wallet - Web (deposits and withdrawals only)</li><li>Oasis CLI</li></ul> |
+| Cipher                | `oasis1`       | secp256k1, ed25519, sr25519 | <ul><li>Oasis CLI</li></ul> |
+| Emerald               | `0x`, `oasis1` | secp256k1, ed25519, sr25519 | <ul><li>Metamask and other EVM-compatible wallets (transfers only)</li><li>Oasis Wallet - Browser Extension</li><li>Oasis Wallet - Web (deposits and withdrawals only)</li><li>Oasis CLI</li></ul> |
+
+[Bech-32 encoding]: https://github.com/bitcoin/bips/blob/master/bip-0173.mediawiki#bech32
+
+## Obtaining ROSE
+
+The most common way to obtain ROSE is by buying it on a centralized
+[cryptocurrency exchange]. At time of writing this chapter, all exchanges
+operated solely on the **consensus layer**. This means that you can only move
+the tokens in or out of the exchange using **your consensus account**.
+
+An alternative way to obtain ROSE is by swapping another cryptocurrency with
+ROSE on an on-chain exchange also known as **a [decentralized exchange] (DEX)**.
+At time of writing at least one such exchange is operating on Sapphire. In this
+case, your originating token is sent to the contract address on the source chain
+and the payout is made to **your account on Sapphire**.
+
+[cryptocurrency exchange]: https://en.wikipedia.org/wiki/Cryptocurrency_exchange
+[decentralized exchange]: https://en.wikipedia.org/wiki/Decentralized_finance#Decentralized_exchanges
+
+## Check your account
+
+To check the balance of your consensus account, you can use the
+[Oasis Scan](https://www.oasisscan.com) block explorer. Enter your `oasis1`
+address at the top and hit enter. For example:
+
+![Account details of entered oasis1 address in Oasis Scan](../images/manage-tokens/oasisscan_account_details.png)
+
+The "Amount" is a sum of three values:
+
+- the "Available" tokens that can immediately be transferred,
+- the "Escrow" tokens that are delegated,
+- the "Reclaim" tokens that are waiting for the debonding period to pass.
+
+To check the account's deposits and withdrawals navigate to "Transactions" pane
+and press "ParaTime" on the right side, next to the "Consensus" button.
+You will see all ParaTime-related transactions including deposits, withdrawals,
+transfers and even smart contract transactions.
+
+![Search result of oasis1 address - Account details](../images/manage-tokens/oasisscan_paratime_txes.png)
+
+Furthermore, you can view the transaction details, if you click on a
+transaction's "Tx Hash". Among others, you will see the transaction type, the
+"from", "to" and "amount" fields.
+
+![Tx Hash - Transaction details](../images/manage-tokens/oasisscan_paratime_tx_details.png)
+
+:::info
+
+Be aware that the [Oasis Scan Blockchain Explorer](https://www.oasisscan.com)
+is built for consensus layer. If you want to explore Sapphire (0x addresses,
+Token Transfers, Contract Calls, etc.), you have to use the
+[Sapphire Blockchain Explorer](https://explorer.oasis.io/mainnet/sapphire).
+
+:::

docs/general/manage-tokens/faq.mdx

@@ -30,7 +30,7 @@ your assets.
 
 [bitpie-announcement]: https://medium.com/bitpie/announcement-on-suspension-of-support-for-algo-and-rose-fc35cb322617
 [ADR-8]: ../../adrs/0008-standard-account-key-generation.md
-[oasis-wallet-import-private-key]: ../../general/manage-tokens/oasis-wallets/web.md#open-wallet-via-private-key
+[oasis-wallet-import-private-key]: ../../general/manage-tokens/oasis-wallets/web.mdx#import-an-existing-account
 
 ### How can I export Oasis private key from a working BitPie wallet?
 
@@ -152,7 +152,7 @@ and [paste it into the Oasis wallet][oasis-wallet-import-private-key], or
 
 [Oasis unmnemonic tool]: https://github.com/oasisprotocol/tools/tree/main/unmnemonic
 [unmnemonic-linux]: https://github.com/oasisprotocol/tools/releases/download/unmnemonic-tool-0.1.0/unmnemonic_linux_amd64
-[unmnemonic-windows]: https://github.com/oasisprotocol/tools/releases/download/unmnemonic-tool-0.1.0/unmnemonic_windows_amd64
+[unmnemonic-windows]: https://github.com/oasisprotocol/tools/releases/download/unmnemonic-tool-0.1.0/unmnemonic_windows_amd64.exe
 [unmnemonic-macos]: https://github.com/oasisprotocol/tools/releases/download/unmnemonic-tool-0.1.0/unmnemonic_darwin_all
 [`oasis wallet import-file`]: cli/wallet.md#import-file
 
@@ -395,4 +395,4 @@ Sending ROSE is different than staking it! With the staking transaction you **le
 
 ### I withdrew ROSE from Emerald to an exchange (Binance, KuCoin), but my deposit is not there. What should I do?
 
-Withdrawals from Emerald are slightly different from regular `staking.Transfer` transactions used to send ROSE on the consensus layer. If you withdrew your ROSE directly to an exchange and you were not funded there, contact the exchange support and provide them the link to your account on the [Oasis Scan](https://www.oasisscan.com) where they can verify all transactions. To learn more about this issue, read the [How to Transfer ROSE to ParaTime section](how-to-transfer-rose-into-paratime.mdx).
+Withdrawals from Emerald are slightly different from regular `staking.Transfer` transactions used to send ROSE on the consensus layer. If you withdrew your ROSE directly to an exchange and you were not funded there, contact the exchange support and provide them the link to your account on the [Oasis Scan](https://www.oasisscan.com) where they can verify all transactions. To learn more about this issue, read the [Manage tokens](README.mdx) chapter.

docs/general/manage-tokens/holding-rose-tokens/custody-providers.md

@@ -1,12 +1,25 @@
-# Custody Providers
+---
+description: Not comfortable keeping the keys on your own?
+---
 
-Another way to hold your ROSE tokens is by using a custody provider.
+# Custody Providers & Protocols
 
-We've partnered with industry-leaders who each support a number of top crypto assets.
+Another way to hold your ROSE is by involving custodial partners—either
+by giving them complete custody over your tokens
+([Custody Providers](#custody-providers)) or just require a multi-signature
+transaction to move them and then splitting some of those keys among trusted
+parties ([Decentralized Custody Protocols](#decentralized-custody-protocols)).
+We've partnered with industry-leaders who support a number of top crypto
+assets. You can pick among the custodial providers or decentralized custody
+protocols below.
+
+
+## Custody Providers
 
 :::info
 
-Below are some simple ways to get in touch, but please do reach out to them directly for more information on insurance, fees and cross-chain support.
+Below are some simple ways to get in touch, but please do reach out to them
+directly for more information on insurance, fees and cross-chain support.
 
 :::
 
@@ -33,3 +46,16 @@ Finoa is a regulated custodian for digital assets, servicing professional invest
 * **Delegation options:** Finoa offers delegation to a number of select validators including Bison Trails, Blockdaemon, Chorus One, Figment Networks, and more.
 * **Min holding:** No threshold for assets under custody. Please check out details at [finoa.io](https://www.finoa.io).
 * **Sign up:** Email [[email protected]](mailto:[email protected]) to set up an account.
+
+## Decentralized Custody Protocols
+
+### [Oasis Safe][safe.oasis.io]
+
+Unlock a new way of ownership! Oasis Safe is the most trusted **decentralized
+custody protocol** and collective asset management (*multisignature* support)
+platform running on **Oasis Sapphire**.
+
+Visit [safe.oasis.io] and login with your MetaMask or other Ethereum-compatible
+wallet.
+
+[safe.oasis.io]: https://safe.oasis.io