Skip to content

Commit

Permalink
faq: Extend unmnemonic tool instructions (Bitpie, Ledger)
Browse files Browse the repository at this point in the history
  • Loading branch information
@matevz
matevz committed Nov 30, 2023
1 parent 2ecec35 commit 342d828
Show file tree
Hide file tree
Showing 2 changed files with 192 additions and 31 deletions.
221 changes: 191 additions & 30 deletions docs/general/manage-tokens/faq.md → docs/general/manage-tokens/faq.mdx
View file
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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)
Expand All @@ -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?
Expand All @@ -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)

Expand All @@ -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
Expand All @@ -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?

Expand Down Expand Up @@ -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?

Expand All @@ -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).
Expand Down
2 changes: 1 addition & 1 deletion docs/general/manage-tokens/oasis-wallets/README.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

<DocCardList />

Expand Down

0 comments on commit 342d828

Please sign in to comment.