Merge pull request #651 from oasisprotocol/matevz/docs/revamp-faq

Revamp FAQ and Transfer ROSE to ParaTimes chapters

docs/general/manage-tokens/faq.md → docs/general/manage-tokens/faq.mdx

@@ -1,3 +1,6 @@
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
 # Frequently Asked Questions
 
 This documents answers frequently asked questions about Oasis Wallets and 3rd
@@ -7,19 +10,16 @@ party wallets & custody providers supporting ROSE tokens.
 
 :::caution
 
-BitPie wallet doesn't use the [standardized Oasis mnemonic derivation][adr8].
+BitPie wallet doesn't use the [standardized Oasis mnemonic derivation (ADR-8)][ADR-8].
 Consequently, your **Bitpie wallet's mnemonic phrase will not open the same
 account in the Oasis Wallet**.
 
 :::
 
-As of May 2023, the newer versions of BitPie wallet [do not support transferring
-tokens on the Oasis network anymore][bitpie-announcement]. Previously, sending
-tokens from the BitPie wallet to the address generated by the Oasis wallet was
-the preferred migration procedure.
-
-Thus, the only way to access your tokens stored on your BitPie wallet is to
-obtain the private key of your BitPie's wallet in one of the two ways:
+In May 2023, the BitPie team [removed support for the Oasis
+network][bitpie-announcement]. Thus, the only way to access your tokens stored
+on your BitPie wallet is to obtain the private key of your BitPie's wallet in
+one of the two ways:
 
 - [Export private key from a working BitPie wallet](#how-can-i-export-oasis-private-key-from-a-working-bitpie-wallet)
 - [Convert BitPie mnemonic to Oasis private key offline](#how-can-i-export-oasis-private-key-if-bitpie-doesnt-show-my-rose-account-anymore)
@@ -29,7 +29,7 @@ Once you obtained the private key, you can
 your assets.
 
 [bitpie-announcement]: https://medium.com/bitpie/announcement-on-suspension-of-support-for-algo-and-rose-fc35cb322617
-[adr8]: ../../adrs/0008-standard-account-key-generation.md
+[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
 
 ### How can I export Oasis private key from a working BitPie wallet?
@@ -50,7 +50,8 @@ On the main BitPie wallet screen, click on the "Receive" button.
 
 ![BitPie main screen](../images/wallet/bitpie/mainscreen.png)
 
-The QR code with your ROSE address will appear. Then, in the top right corner, tap on the kebab menu "⋮" and select "Display Private Key"_._
+The QR code with your ROSE address will appear. Then, in the top right corner,
+tap on the kebab menu "⋮" and select "Display Private Key"_._
 
 ![BitPie show private key](../images/wallet/bitpie/show_private_key.png)
 
@@ -64,20 +65,55 @@ which you can
 
 ### How can I export Oasis private key, if BitPie doesn't show my ROSE account anymore?
 
+<!-- NOTE: This answer is similar to the Ledger answer below. Keep them in sync. -->
+
 If you reinstalled BitPie or restored it with a mnemonic on a new device, you
 may not have your ROSE account present anymore. In this case, you will have
 to convert your BitPie mnemonic to the Oasis private key using the [Oasis
-unmnemonic CLI tool].
+unmnemonic tool] (64-bit binaries available for [Linux][unmnemonic-linux],
+[MacOS][unmnemonic-macos] and [Windows][unmnemonic-windows]).
 
-You will have to pick Bitpie algorithm, then enter the number of mnemonics
-(typically 12), the private key index (start with 0 and gradually increase it by
-1, if the resulting account does not contain any tokens) and the output
-directory where the file containing the Oasis private key should be stored into.
-For example:
+Open a terminal (on Windows run `cmd`), move to the corresponding folder and
+invoke the unmnemonic executable:
 
+<Tabs>
+<TabItem value="Linux">
+
+```shell
+./unmnemonic_linux_amd64
 ```
-$ ./unmnemonic
 
+</TabItem>
+<TabItem value="MacOS">
+
+```shell
+./unmnemonic_darwin_all
+```
+
+</TabItem>
+<TabItem value="Windows">
+
+```shell
+unmnemonic_windows_amd64
+```
+
+</TabItem>
+</Tabs>
+
+An interactive prompt will be shown to you:
+
+1. select the **Bitpie** algorithm,
+2. enter the number of words in the mnemonic (typically **12**) and carefully
+   type them in one by line,
+3. enter the private key index (start with **0** and gradually increase it by 1,
+   if the resulting account does not contain any tokens),
+4. answer **Yes** for writing the keys to disk,
+5. enter the name of the **output directory** to store the Oasis private key
+   into (by default the folder name starts with `wallet-export-`)
+
+For example:
+
+```
   unmnemonic - Recover Oasis Network signing keys from mnemonics
 
 ? Which algorithm does your wallet use Bitpie
@@ -102,11 +138,23 @@ $ ./unmnemonic
 Done writing wallet keys to disk, goodbye.
 ```
 
-Open the generated file, copy the Base64-encoded key wrapped with
+Finally, look into the output directory. There you should find a `.private.pem`
+file containing the private key and named after the address it belongs to. You
+can either:
+
+- Open it with a text editor, copy the Base64-encoded key between the
 `-----BEGIN ED25519 PRIVATE KEY-----` and `-----END ED25519 PRIVATE KEY-----`,
-and [import it to the Oasis wallet][oasis-wallet-import-private-key].
+and [paste it into the Oasis wallet][oasis-wallet-import-private-key], or
+- if you use the [Oasis CLI] simply execute the [`oasis wallet import-file`]
+  command to add the exported account to your CLI wallet, for example:
+
+  ![code shell](../../../external/cli/examples/wallet/import-file-unmnemonic.in.static)
 
-[Oasis unmnemonic CLI tool]: https://github.com/oasisprotocol/tools/tree/main/unmnemonic
+[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-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
 
 ### Chromium under Ubuntu does not recognize my Ledger device. What is the problem?
 
@@ -150,42 +198,155 @@ Here's a task for you:
 
 As an additional exercise, you can also create an Oasis wallet using the BIP39 mnemonic from the step 1 above. You will notice that the imported account's base64-encoded private key in the account details screen is different from the one in step 7 above. That's because Oasis uses a different _derivation path_ than Ethereum.
 
-### Which derivation path should I use on Ledger? ADR 0008 or Legacy? {#ledger-derivation-paths}
+### Which derivation path should I use on Ledger? ADR-8 or Legacy? {#ledger-derivation-paths}
 
 To convert your mnemonic phrase into a private key for signing trasactions,
 each wallet (hardware or software) performs a *key derivation*. The Oasis
 Protocol Foundation standardized the key derivation for official Oasis wallets
-in a document called [ADR 0008] back in January 2021. However, the Ledger
+in a document called [ADR-8] back in January 2021. However, the Ledger
 hardware wallet already supported signing transactions at that time using a
 custom (we now call it *legacy*) derivation path which is incompatible with
-the one defined in ADR 0008. Later, in Oasis app for Ledger v2.3.1 support for
-ADR 0008 was added so the wallet can request either derivation from the Ledger
+the one defined in ADR-8. Later, in Oasis app for Ledger v2.3.1 support for
+ADR-8 was added so the wallet can request either derivation from the Ledger
 device.
 
-The key derivation path defined in ADR 0008 has the following advantages
+The key derivation path defined in ADR-8 has the following advantages
 compared to the legacy one:
 
 - Derivation path is shorter which results in approximately twice as fast
   key derivation (and transaction signing) without compromising security.
 - In case your Ledger device is broken or lost and you are unable to retrieve
   a new one, you will be able to import your Ledger mnemonic and restore your
-  private key in any Oasis wallet which implements ADR 0008.
+  private key in any Oasis wallet which implements ADR-8.
 
-For reasons above, we recommend the usage of ADR 0008. However, since there are
+For reasons above, we recommend the usage of ADR-8. However, since there are
 no security considerations at stake, Oasis wallets will support legacy
 derivation on Ledger for the foreseeable future.
 
+### I lost my Ledger or my Ledger is broken. I urgently need to access my assets. Can I import Ledger mnemonic into Oasis wallet?
+
+<!-- NOTE: This answer is similar to the BitPie answer above. Keep them in sync. -->
+
 :::danger
 
-If you happen to import your Ledger mnemonic to a software wallet, consider
+When you import your Ledger mnemonic to a software wallet, consider
 that mnemonic *potentially exposed/compromised*, i.e. not appropriate for a
 hardware wallet mnemonic anymore. If you use a new hardware wallet in the
 future, **never restore it from the mnemonic that was previously used by any
 software wallet!**
 
 :::
 
-[ADR 0008]: /adrs/0008-standard-account-key-generation
+Ledger supports [two derivation paths](#ledger-derivation-paths) on the Oasis
+network.
+
+If you used your Ledger with the [Oasis CLI] and the [ADR-8] derivation path,
+you can import the mnemonic directly into the CLI wallet by invoking
+[`oasis wallet import`] and selecting the `ed25519-adr8` algorithm.
+
+If you used your Ledger with the Oasis Wallet Web, the browser extension, the
+Oasis CLI with the `ed25519-legacy` derivation path or the Oasis Core, then you
+will need to use the [Oasis unmnemonic tool] (64-bit binaries available for
+[Linux][unmnemonic-linux], [MacOS][unmnemonic-macos] and
+[Windows][unmnemonic-windows]).
+
+Open a terminal (on Windows run `cmd`), move to the corresponding folder and
+invoke the unmnemonic executable:
+
+<Tabs>
+<TabItem value="Linux">
+
+```shell
+./unmnemonic_linux_amd64
+```
+
+</TabItem>
+<TabItem value="MacOS">
+
+```shell
+./unmnemonic_darwin_all
+```
+
+</TabItem>
+<TabItem value="Windows">
+
+```shell
+unmnemonic_windows_amd64
+```
+
+</TabItem>
+</Tabs>
+
+An interactive prompt will be shown to you:
+
+1. select the **Ledger** algorithm,
+2. enter the number of words in the mnemonic (typically **24**) and carefully
+   type them in one by line,
+3. enter the private key index (start with **0** and gradually increase it by 1,
+   if the resulting account does not contain any tokens),
+4. answer **Yes** for writing the keys to disk,
+5. enter the name of the **output directory** to store the Oasis private key
+   into (by default the folder name starts with `wallet-export-`)
+
+For example:
+
+```
+  unmnemonic - Recover Oasis Network signing keys from mnemonics
+
+? Which algorithm does your wallet use Ledger
+ WARNING:
+
+  Entering your Ledger device mnemonic into any non-Leger device
+  can COMPROMISE THE SECURITY OF ALL ACCOUNTS TIED TO THE MNEMONIC.
+  Use of this tool is STRONGLY DISCOURAGED.
+
+? Have you read and understand the warning Yes
+? How many words is your mnemonic 24
+? Enter word 1 *****
+? Enter word 2 ****
+? Enter word 3 ****
+? Enter word 4 ******
+? Enter word 5 ****
+? Enter word 6 *****
+? Enter word 7 ****
+? Enter word 8 *******
+? Enter word 9 ******
+? Enter word 10 *****
+? Enter word 11 ***
+? Enter word 12 *****
+? Enter word 13 *****
+? Enter word 14 ****
+? Enter word 15 ****
+? Enter word 16 ******
+? Enter word 17 ****
+? Enter word 18 *****
+? Enter word 19 ****
+? Enter word 20 *******
+? Enter word 21 ******
+? Enter word 22 *****
+? Enter word 23 ***
+? Enter word 24 *****
+? Wallet index(es) (comma separated) 4
+ Index[4]: oasis1qqwkm23pyg638xvl2nu00frxhapusjjv8qhh3p77
+? Write the keys to disk Yes
+? Output directory /home/oa/tmp/wallet-export-2023-11-28
+ Index[4]: oasis1qqwkm23pyg638xvl2nu00frxhapusjjv8qhh3p77.private.pem - done
+Done writing wallet keys to disk, goodbye.
+```
+
+Finally, look into the output directory. There you should find a `.private.pem`
+file containing the private key and named after the address it belongs to. You
+can either:
+
+- Open it with a text editor, copy the Base64-encoded key between the
+  `-----BEGIN ED25519 PRIVATE KEY-----` and `-----END ED25519 PRIVATE KEY-----`,
+  and [paste it into the Oasis wallet][oasis-wallet-import-private-key], or
+- if you use the [Oasis CLI] simply execute the [`oasis wallet import-file`]
+  command to add the exported account to your CLI wallet, for example:
+
+  ![code shell](../../../external/cli/examples/wallet/import-file-unmnemonic.in.static)
+
+[`oasis wallet import`]: cli/wallet.md#import
 
 ### The wallet gives me _Invalid keyphrase_ error when importing my wallet from mnemonics. How do I solve it?
 
@@ -212,7 +373,7 @@ up and running, you should be able to see the correct balance.
 
 If your wallet address is different than the one you used to transfer your funds
 to, then you used one of the wallets that don't implement the [standardized key
-derivation path][adr-8]. If you were using the BitPie wallet see
+derivation path][ADR-8]. If you were using the BitPie wallet see
 [this question](#how-can-i-export-oasis-private-key-from-a-working-bitpie-wallet).
 Ledger hardware wallet users should refer to
 [this question](#ledger-derivation-paths).