From 342d8281df55dde21314a1bc4e1697033fcba952 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matev=C5=BE=20Jekovec?= Date: Tue, 28 Nov 2023 13:42:54 +0100 Subject: [PATCH] faq: Extend unmnemonic tool instructions (Bitpie, Ledger) --- .../general/manage-tokens/{faq.md => faq.mdx} | 221 +++++++++++++++--- .../manage-tokens/oasis-wallets/README.mdx | 2 +- 2 files changed, 192 insertions(+), 31 deletions(-) rename docs/general/manage-tokens/{faq.md => faq.mdx} (62%) diff --git a/docs/general/manage-tokens/faq.md b/docs/general/manage-tokens/faq.mdx similarity index 62% rename from docs/general/manage-tokens/faq.md rename to docs/general/manage-tokens/faq.mdx index 709734b750..d7f7e6cc1b 100644 --- a/docs/general/manage-tokens/faq.md +++ b/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? + + 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: + + + +```shell +./unmnemonic_linux_amd64 ``` -$ ./unmnemonic + + + +```shell +./unmnemonic_darwin_all +``` + + + + +```shell +unmnemonic_windows_amd64 +``` + + + + +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,34 +198,38 @@ 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? + + + :::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 @@ -185,7 +237,116 @@ 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: + + + + +```shell +./unmnemonic_linux_amd64 +``` + + + + +```shell +./unmnemonic_darwin_all +``` + + + + +```shell +unmnemonic_windows_amd64 +``` + + + + +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). diff --git a/docs/general/manage-tokens/oasis-wallets/README.mdx b/docs/general/manage-tokens/oasis-wallets/README.mdx index f5b636c10d..dbf4826042 100644 --- a/docs/general/manage-tokens/oasis-wallets/README.mdx +++ b/docs/general/manage-tokens/oasis-wallets/README.mdx @@ -32,7 +32,7 @@ The Oasis Wallets currently support the following features: * Toggling between light mode and dark mode (Web variant) * Selecting a language for the UI (currently, English and French fort the Web variant, English and Chinese for the Browser Extension variant) * Staking and receiving staking rewards -* Easily switching between different Oasis Wallets that use the same [ADR 0008](../../../adrs/0008-standard-account-key-generation.md) standard account key generation process +* Easily switching between different Oasis Wallets that use the same [ADR-8](../../../adrs/0008-standard-account-key-generation.md) standard account key generation process