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 29, 2023
1 parent fcec6d0 commit ff4f593
Show file tree
Hide file tree
Showing 2 changed files with 125 additions and 30 deletions.
153 changes: 124 additions & 29 deletions docs/general/manage-tokens/faq.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,19 +7,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 +26,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 +47,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 @@ -67,17 +65,25 @@ which you can
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 CLI 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
execute it. 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 output directory where the file containing the Oasis private key
should be stored into (you can leave the default folder starting with
`wallet-export-`)

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:

```
$ ./unmnemonic
unmnemonic - Recover Oasis Network signing keys from mnemonics
? Which algorithm does your wallet use Bitpie
Expand All @@ -102,11 +108,16 @@ $ ./unmnemonic
Done writing wallet keys to disk, goodbye.
```

Open the generated file, copy the Base64-encoded key wrapped with
Move to the output directory. There you should see a `.private.pem` file
containing the private key and named after the address it belongs to. Open it
with a text editor and 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].

[Oasis unmnemonic CLI 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

### Chromium under Ubuntu does not recognize my Ledger device. What is the problem?

Expand Down Expand Up @@ -150,42 +161,126 @@ 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.

:::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
### I lost my Ledger or my Ledger is broken. I urgently need to access my assets. Can I import Ledger mnemonic into Oasis wallet?

Ledger supports [two derivation paths](#ledger-derivation-paths) on the Oasis
network. If you used the [Oasis CLI] with the [ADR-8] derivation path,
you can import the mnemonic directly into the Oasis Wallet.

:::danger

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!**

:::

If you used your Ledger with the Oasis Wallet Web, the Extension or the Oasis
node, then you will need to use the [Oasis unmnemonic CLI 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
execute it. 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 output directory where the file containing the Oasis private key
should be stored into (you can leave the default folder starting 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.
```

Move to the output directory. There you should see a `.private.pem` file
containing the private key and named after the address it belongs to. Open it
with a text editor and 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].

### The wallet gives me _Invalid keyphrase_ error when importing my wallet from mnemonics. How do I solve it?

Expand All @@ -212,7 +307,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 ff4f593

Please sign in to comment.