Clean up Ledger instructions (#10047)
Co-authored-by: publish-docs.sh <maintainers@solana.com>
This commit is contained in:
parent
816bf6ebdd
commit
d195dce5d1
|
@ -18,7 +18,7 @@ hardware wallet.
|
||||||
The Solana CLI supports the following hardware wallets:
|
The Solana CLI supports the following hardware wallets:
|
||||||
- [Ledger Nano S](ledger.md)
|
- [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
|
Solana defines a keypair URL format to uniquely locate any Solana keypair on a
|
||||||
hardware wallet connected to your computer.
|
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`
|
The path has the form `<ACCOUNT>[/<CHANGE>]`, where each `ACCOUNT` and `CHANGE`
|
||||||
are positive integers.
|
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:
|
For example, a fully qualified URL for a Ledger device might be:
|
||||||
|
|
||||||
```text
|
```text
|
||||||
usb://ledger/BsNsvfXqQTtJnagwFWdBS7FBXgnsK8VZ5CmuznN85swK?key=0/0
|
usb://ledger/BsNsvfXqQTtJnagwFWdBS7FBXgnsK8VZ5CmuznN85swK?key=0/0
|
||||||
```
|
```
|
||||||
|
|
||||||
### Multiple Addresses on a Single Hardware Wallet
|
All derivation paths implicitly include the prefix `44'/501'`, which indicates
|
||||||
You can derive as many wallet addresses as you like. To view them, simply
|
the path follows the [BIP44 specifications](https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki)
|
||||||
iterate the `ACCOUNT` and/or `CHANGE` number when specifying the URL path.
|
and that any derived keys are Solana keys (Coin type 501). The single quote
|
||||||
Multiple wallet addresses can be useful if you want to transfer tokens between
|
indicates a "hardened" derivation. Because Solana uses Ed25519 keypairs, all
|
||||||
your own accounts for different purposes.
|
derivations are hardened and therefore adding the quote is optional and
|
||||||
|
unnecessary.
|
||||||
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
|
|
||||||
```
|
|
||||||
|
|
|
@ -9,14 +9,17 @@ secure transaction signing.
|
||||||
- [Set up a Ledger Nano S with the Solana App](../wallet-guide/ledger-live.md)
|
- [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)
|
- [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
|
1. Ensure the Ledger Live application is closed
|
||||||
2. Plug your Ledger device into your computer's USB port
|
2. Plug your Ledger device into your computer's USB port
|
||||||
3. Enter your pin and start the Solana app on the Ledger device
|
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
|
4. Press both buttons to advance past the "Pending Ledger review" screen
|
||||||
5. Ensure the screen reads "Application is ready"
|
5. Ensure the screen reads "Application is ready"
|
||||||
6. On your computer, run:
|
|
||||||
|
### View your Wallet ID
|
||||||
|
|
||||||
|
On your computer, run:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
solana-keygen pubkey usb://ledger
|
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
|
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
|
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
|
*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
|
computer, you can use your wallet ID to specify which Ledger hardware wallet
|
||||||
you want to use. Run the same command again, but this time, with its fully
|
you want to use. If you only plan to use a single Nano S on your computer
|
||||||
qualified URL:
|
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
|
```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.
|
You can use other values for the number after `key=` as well.
|
||||||
Confirm it prints the same wallet ID as before.
|
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
|
If you are only planning to use a single address/keypair on your device, a good
|
||||||
[Specify A Hardware Wallet Key](README.md#specify-a-hardware-wallet-key)
|
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
|
Now you have a wallet address (or multiple addresses), you can share any of
|
||||||
[delegating stake](../cli/delegate-stake.md). You can use your Ledger keypair URL
|
these addresses publicly to act as a receiving address, and you can use the
|
||||||
anywhere you see an option or argument that accepts a `<KEYPAIR>`.
|
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
|
### Install the Solana Beta App
|
||||||
|
|
||||||
You're invited to help us test the latest pre-release version of our Ledger app
|
You're invited to help us test the latest pre-release version of our Ledger app
|
||||||
on one of the public testnets.
|
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
|
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
|
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
|
"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
|
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.
|
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.
|
**WARNING:** Installing an unsigned Ledger app reduces the security of your
|
||||||
If your client is compromised, an attacker will be able to trick you into signing arbitrary
|
Ledger device.
|
||||||
transactions with arbitrary derivation paths. Only use this installation method if you understand
|
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
|
the security implications. We strongly recommend that you use a separate
|
||||||
Ledger device, with no other wallets/apps sharing the same seed phrase.
|
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..."
|
5. An installation window appears and your device will display "Processing..."
|
||||||
6. The app installation is confirmed
|
6. The app installation is confirmed
|
||||||
|
|
||||||
|
#### Installing the Solana Beta App returns an error
|
||||||
|
|
||||||
If you encounter the following error:
|
If you encounter the following error:
|
||||||
|
|
||||||
```text
|
```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
|
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
|
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
|
## 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>`.
|
Loading…
Reference in New Issue