gaspersic/solana
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Clean up Ledger instructions (#10047)

Browse Source 
Co-authored-by: publish-docs.sh <maintainers@solana.com>
This commit is contained in:
Dan Albert
2020-05-14 14:03:16 -06:00
committed by GitHub
parent 816bf6ebdd
commit d195dce5d1
2 changed files with 197 additions and 99 deletions
Download Patch File Download Diff File Expand all files Collapse all files

88
docs/src/hardware-wallets/README.md
View File

@@ -18,7 +18,7 @@ hardware wallet.
The Solana CLI supports the following hardware wallets:
- [Ledger Nano S](ledger.md)
## Specify a Hardware Wallet Key
## Specify a Keypair URL
Solana defines a keypair URL format to uniquely locate any Solana keypair on a
hardware wallet connected to your computer.
@@ -36,89 +36,15 @@ usb://<MANUFACTURER>[/<WALLET_ID>][?key=<DERIVATION_PATH>]
The path has the form `<ACCOUNT>[/<CHANGE>]`, where each `ACCOUNT` and `CHANGE`
are positive integers.
All derivation paths implicitly include the prefix `44'/501'`, which indicates
the path follows the [BIP44 specifications](https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki)
and that any derived keys are Solana keys (Coin type 501). The single quote
indicates a "hardened" derivation. Because Solana uses Ed25519 keypairs, all
derivations are hardened and therefore adding the quote is optional and
unnecessary.
For example, a fully qualified URL for a Ledger device might be:
```text
usb://ledger/BsNsvfXqQTtJnagwFWdBS7FBXgnsK8VZ5CmuznN85swK?key=0/0
```
### Multiple Addresses on a Single Hardware Wallet
You can derive as many wallet addresses as you like. To view them, simply
iterate the `ACCOUNT` and/or `CHANGE` number when specifying the URL path.
Multiple wallet addresses can be useful if you want to transfer tokens between
your own accounts for different purposes.
For example, a first address can be viewed with:
```bash
solana-keygen pubkey usb://ledger?key=0
```
A second address can be viewed with:
```bash
solana-keygen pubkey usb://ledger?key=1
```
A third address:
```bash
solana-keygen pubkey usb://ledger?key=2
```
...and so on.
## Manage Multiple Hardware Wallets
It is sometimes useful to sign a transaction with keys from multiple hardware
wallets. Signing with multiple wallets requires *fully qualified keypair URLs*.
When the URL is not fully qualified, the Solana CLI will prompt you with
the fully qualified URLs of all connected hardware wallets, and ask you to
choose which wallet to use for each signature.
Instead of using the interactive prompts, you can generate fully qualified
URLs using the Solana CLI `resolve-signer` command. For example, try
connecting a Ledger Nano-S to USB, unlock it with your pin, and running the
following command:
```text
solana resolve-signer usb://ledger?key=0/0
```
You will see output similar to:
```text
usb://ledger/BsNsvfXqQTtJnagwFWdBS7FBXgnsK8VZ5CmuznN85swK?key=0/0
```
but where `BsNsvfXqQTtJnagwFWdBS7FBXgnsK8VZ5CmuznN85swK` is your `WALLET_ID`.
With your fully qualified URL, you can connect multiple hardware wallets to
the same computer and uniquely identify a keypair from any of them.
## Troubleshooting
### Keypair URL parameters are ignored in zsh
The question mark character is a special character in zsh. If that's not a
feature you use, add the following line to your `~/.zshrc` to treat it as a
normal character:
```bash
unsetopt nomatch
```
Then either restart your shell window or run `~/.zshrc`:
```bash
source ~/.zshrc
```
If you would prefer not to disable zsh's special handling of the question mark
character, you can disable it explictly with a backslash in your keypair URLs.
For example:
```bash
solana-keygen pubkey usb://ledger\?key=0
```
All derivation paths implicitly include the prefix `44'/501'`, which indicates
the path follows the [BIP44 specifications](https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki)
and that any derived keys are Solana keys (Coin type 501). The single quote
indicates a "hardened" derivation. Because Solana uses Ed25519 keypairs, all
derivations are hardened and therefore adding the quote is optional and
unnecessary.

208
docs/src/hardware-wallets/ledger.md
View File

@@ -9,14 +9,17 @@ secure transaction signing.
- [Set up a Ledger Nano S with the Solana App](../wallet-guide/ledger-live.md)
- [Install the Solana command-line tools](../cli/install-solana-cli-tools.md)
## Use Ledger Device with Solana CLI
## Use Ledger Nano S with Solana CLI
1. Ensure the Ledger Live application is closed
2. Plug your Ledger device into your computer's USB port
3. Enter your pin and start the Solana app on the Ledger device
4. Press both buttons to advance past the "Pending Ledger review" screen
5. Ensure the screen reads "Application is ready"
6. On your computer, run:
### View your Wallet ID
On your computer, run:
```bash
solana-keygen pubkey usb://ledger
@@ -25,39 +28,172 @@ solana-keygen pubkey usb://ledger
This confirms your Ledger device is connected properly and in the correct state
to interact with the Solana CLI. The command returns your Ledger's unique
*wallet ID*. When you have multiple Nano S devices connected to the same
computer, you can use your wallet key to specify which Ledger hardware wallet
you want to use. Run the same command again, but this time, with its fully
qualified URL:
computer, you can use your wallet ID to specify which Ledger hardware wallet
you want to use. If you only plan to use a single Nano S on your computer
at a time, you don't need to include the wallet ID. For information on
using the wallet ID to use a specific Ledger, see
[Manage Multiple Hardware Wallets](#manage-multiple-hardware-wallets).
### View your Wallet Addresses
Your Nano S supports an arbitrary number of valid wallet addresses and signers.
To view any address, use the `solana-keygen pubkey` command, as shown below,
followed by a valid [keypair URL](README.md#specify-a-keypair-url).
Multiple wallet addresses can be useful if you want to transfer tokens between
your own accounts for different purposes, or use different keypairs on the
device as signing authorities for a stake account, for example.
All of the following commands will display different addresses, associated with
the keypair path given. Try them out!
```bash
solana-keygen pubkey usb://ledger/<WALLET_ID>
solana-keygen pubkey usb://ledger
solana-keygen pubkey usb://ledger?key=0
solana-keygen pubkey usb://ledger?key=1
solana-keygen pubkey usb://ledger?key=2
```
where you replace `<WALLET_ID>` with the output of the first command.
Confirm it prints the same wallet ID as before.
You can use other values for the number after `key=` as well.
Any of the addresses displayed by these commands are valid Solana wallet
addresses. The private portion associated with each address is stored securely
on the Nano S device, and is used to sign transactions from this address.
Just make a note of which keypair URL you used to derive any address you will be
using to receive tokens.
To learn more about keypair URLs, see
[Specify A Hardware Wallet Key](README.md#specify-a-hardware-wallet-key)
If you are only planning to use a single address/keypair on your device, a good
easy-to-remember path might be to use the address at `key=0`. View this address
with:
```bash
solana-keygen pubkey usb://ledger?key=0
```
Read more about [sending and receiving tokens](../cli/transfer-tokens.md) and
[delegating stake](../cli/delegate-stake.md). You can use your Ledger keypair URL
anywhere you see an option or argument that accepts a `<KEYPAIR>`.
Now you have a wallet address (or multiple addresses), you can share any of
these addresses publicly to act as a receiving address, and you can use the
associated keypair URL as the signer for transactions from that address.
### View your Balance
To view the balance of any account, regardless of which wallet it uses, use the
`solana balance` command:
```bash
solana balance SOME_WALLET_ADDRESS
```
For example, if your address is `7cvkjYAkUYs4W8XcXsca7cBrEGFeSUjeZmKoNBvEwyri`,
then enter the following command to view the balance:
```bash
solana balance 7cvkjYAkUYs4W8XcXsca7cBrEGFeSUjeZmKoNBvEwyri
```
You can also view the balance of any account address on the Accounts tab in the
[Explorer](https://explorer.solana.com/accounts)
and paste the address in the box to view the balance in you web browser.
Note: Any address with a balance of 0 SOL, such as a newly created one on your
Ledger, will show as "Not Found" in the explorer. Empty accounts and non-existent
accounts are treated the same in Solana. This will change when your account
address has some SOL in it.
### Send SOL from a Ledger Nano S
To send some tokens from an address controlled by your Nano S device, you will
need to use the device to sign a transaction, using the same keypair URL you
used to derive the address. To do this, make sure your Nano S is plugged in,
unlocked with the PIN, Ledger Live is not running, and the Solana App is open
on the device, showing "Application is Ready".
The `solana transfer` command is used to specify to which address to send tokens,
how many tokens to send, and uses the `--keypair` argument to specify which
keypair is sending the tokens, which will sign the transaction, and the balance
from the associated address will decrease.
```bash
solana transfer RECIPIENT_ADDRESS AMOUNT --keypair KEYPAIR_URL_OF_SENDER
```
Below is a full example. First, an address is viewed at a certain keypair URL.
Second, the balance of tht address is checked. Lastly, a transfer transaction
is entered to send `1` SOL to the recipient address `7cvkjYAkUYs4W8XcXsca7cBrEGFeSUjeZmKoNBvEwyri`.
When you hit Enter for a transfer command, you will be prompted to approve the
transaction details on your Ledger device. On the device, use the right and
left buttons to review the transaction details. If they look correct, click
both buttons on the "Approve" screen, otherwise push both buttons on the "Reject"
screen.
```bash
~$ solana-keygen pubkey usb://ledger?key=42
CjeqzArkZt6xwdnZ9NZSf8D1CNJN1rjeFiyd8q7iLWAV
~$ solana balance CjeqzArkZt6xwdnZ9NZSf8D1CNJN1rjeFiyd8q7iLWAV
1.000005 SOL
~$ solana transfer 7cvkjYAkUYs4W8XcXsca7cBrEGFeSUjeZmKoNBvEwyri 1 --keypair usb://ledger?key=42
Waiting for your approval on Ledger hardware wallet usb://ledger/2JT2Xvy6T8hSmT8g6WdeDbHUgoeGdj6bE2VueCZUJmyN
✅ Approved
Signature: kemu9jDEuPirKNRKiHan7ycybYsZp7pFefAdvWZRq5VRHCLgXTXaFVw3pfh87MQcWX4kQY4TjSBmESrwMApom1V
```
After approving the transaction on your device, the program will display the
transaction signature, and wait for the maximum number of confirmations (32)
before returning. This only takes a few seconds, and then the transaction is
finalized on the Solana network. You can view details of this or any other
transaction by going to the Transaction tab in the
[Explorer](https://explorer.solana.com/transactions)
and paste in the transaction signature.
## Advanced Operations
### Manage Multiple Hardware Wallets
It is sometimes useful to sign a transaction with keys from multiple hardware
wallets. Signing with multiple wallets requires *fully qualified keypair URLs*.
When the URL is not fully qualified, the Solana CLI will prompt you with
the fully qualified URLs of all connected hardware wallets, and ask you to
choose which wallet to use for each signature.
Instead of using the interactive prompts, you can generate fully qualified
URLs using the Solana CLI `resolve-signer` command. For example, try
connecting a Ledger Nano-S to USB, unlock it with your pin, and running the
following command:
```text
solana resolve-signer usb://ledger?key=0/0
```
You will see output similar to:
```text
usb://ledger/BsNsvfXqQTtJnagwFWdBS7FBXgnsK8VZ5CmuznN85swK?key=0/0
```
but where `BsNsvfXqQTtJnagwFWdBS7FBXgnsK8VZ5CmuznN85swK` is your `WALLET_ID`.
With your fully qualified URL, you can connect multiple hardware wallets to
the same computer and uniquely identify a keypair from any of them.
Use the output from the `resolve-signer` command anywhere a `solana` command
expects a `<KEYPAIR>` entry to use that resolved path as the signer for that
part of the given transaction.
### Install the Solana Beta App
You're invited to help us test the latest pre-release version of our Ledger app
on one of the public testnets.
You can use the command-line to install the latest Solana Ledger app release before it has been validated by
You can use the command-line to install the latest Solana Ledger app release
before it has been validated by
the Ledger team and made available via Ledger Live. Note that because the app
is not installed via Ledger Live, you will need to approve installation from an
"unsafe" manager, as well as see the message, "This app is not genuine" each
time you open the app. Once the app is available on Ledger Live, you can
reinstall the app from there, and the message will no longer be displayed.
**WARNING:** Installing an unsigned Ledger app reduces the security of your Ledger device.
If your client is compromised, an attacker will be able to trick you into signing arbitrary
transactions with arbitrary derivation paths. Only use this installation method if you understand
**WARNING:** Installing an unsigned Ledger app reduces the security of your
Ledger device.
If your client is compromised, an attacker will be able to trick you into
signing arbitrary transactions with arbitrary derivation paths.
Only use this installation method if you understand
the security implications. We strongly recommend that you use a separate
Ledger device, with no other wallets/apps sharing the same seed phrase.
@@ -71,6 +207,8 @@ Ledger device, with no other wallets/apps sharing the same seed phrase.
5. An installation window appears and your device will display "Processing..."
6. The app installation is confirmed
#### Installing the Solana Beta App returns an error
If you encounter the following error:
```text
@@ -93,6 +231,40 @@ To fix, check the following:
2. Ensure your Ledger device is unlocked and not waiting for you to enter your pin
3. Ensure the Ledger Live application is not open
## Troubleshooting
### Keypair URL parameters are ignored in zsh
The question mark character is a special character in zsh. If that's not a
feature you use, add the following line to your `~/.zshrc` to treat it as a
normal character:
```bash
unsetopt nomatch
```
Then either restart your shell window or run `~/.zshrc`:
```bash
source ~/.zshrc
```
If you would prefer not to disable zsh's special handling of the question mark
character, you can disable it explictly with a backslash in your keypair URLs.
For example:
```bash
solana-keygen pubkey usb://ledger\?key=0
```
## Support
Check out our [Wallet Support Page](../wallet-guide/support.md) for ways to get help.
Check out our [Wallet Support Page](../wallet-guide/support.md)
for ways to get help.
Read more about [sending and receiving tokens](../cli/transfer-tokens.md) and
[delegating stake](../cli/delegate-stake.md). You can use your Ledger keypair URL
anywhere you see an option or argument that accepts a `<KEYPAIR>`.