Skip to content
This repository was archived by the owner on Jan 22, 2025. It is now read-only.

Commit d195dce

Browse files
danpaul000publish-docs.sh
danpaul000
and
publish-docs.sh
authored
Clean up Ledger instructions (#10047)
Co-authored-by: publish-docs.sh <[email protected]>
1 parent 816bf6e commit d195dce

File tree

2 files changed

+197
-99
lines changed

2 files changed

+197
-99
lines changed

‎docs/src/hardware-wallets/README.md

Lines changed: 7 additions & 81 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ hardware wallet.
1818
The Solana CLI supports the following hardware wallets:
1919
- [Ledger Nano S](ledger.md)
2020

21-
## Specify a Hardware Wallet Key
21+
## Specify a Keypair URL
2222

2323
Solana defines a keypair URL format to uniquely locate any Solana keypair on a
2424
hardware wallet connected to your computer.
@@ -36,89 +36,15 @@ usb://<MANUFACTURER>[/<WALLET_ID>][?key=<DERIVATION_PATH>]
3636
The path has the form `<ACCOUNT>[/<CHANGE>]`, where each `ACCOUNT` and `CHANGE`
3737
are positive integers.
3838

39-
All derivation paths implicitly include the prefix `44'/501'`, which indicates
40-
the path follows the [BIP44 specifications](https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki)
41-
and that any derived keys are Solana keys (Coin type 501). The single quote
42-
indicates a "hardened" derivation. Because Solana uses Ed25519 keypairs, all
43-
derivations are hardened and therefore adding the quote is optional and
44-
unnecessary.
45-
4639
For example, a fully qualified URL for a Ledger device might be:
4740

4841
```text
4942
usb://ledger/BsNsvfXqQTtJnagwFWdBS7FBXgnsK8VZ5CmuznN85swK?key=0/0
5043
```
5144

52-
### Multiple Addresses on a Single Hardware Wallet
53-
You can derive as many wallet addresses as you like. To view them, simply
54-
iterate the `ACCOUNT` and/or `CHANGE` number when specifying the URL path.
55-
Multiple wallet addresses can be useful if you want to transfer tokens between
56-
your own accounts for different purposes.
57-
58-
For example, a first address can be viewed with:
59-
```bash
60-
solana-keygen pubkey usb://ledger?key=0
61-
```
62-
A second address can be viewed with:
63-
```bash
64-
solana-keygen pubkey usb://ledger?key=1
65-
```
66-
A third address:
67-
```bash
68-
solana-keygen pubkey usb://ledger?key=2
69-
```
70-
...and so on.
71-
72-
## Manage Multiple Hardware Wallets
73-
74-
It is sometimes useful to sign a transaction with keys from multiple hardware
75-
wallets. Signing with multiple wallets requires *fully qualified keypair URLs*.
76-
When the URL is not fully qualified, the Solana CLI will prompt you with
77-
the fully qualified URLs of all connected hardware wallets, and ask you to
78-
choose which wallet to use for each signature.
79-
80-
Instead of using the interactive prompts, you can generate fully qualified
81-
URLs using the Solana CLI `resolve-signer` command. For example, try
82-
connecting a Ledger Nano-S to USB, unlock it with your pin, and running the
83-
following command:
84-
85-
```text
86-
solana resolve-signer usb://ledger?key=0/0
87-
```
88-
89-
You will see output similar to:
90-
91-
```text
92-
usb://ledger/BsNsvfXqQTtJnagwFWdBS7FBXgnsK8VZ5CmuznN85swK?key=0/0
93-
```
94-
95-
but where `BsNsvfXqQTtJnagwFWdBS7FBXgnsK8VZ5CmuznN85swK` is your `WALLET_ID`.
96-
97-
With your fully qualified URL, you can connect multiple hardware wallets to
98-
the same computer and uniquely identify a keypair from any of them.
99-
100-
## Troubleshooting
101-
102-
### Keypair URL parameters are ignored in zsh
103-
104-
The question mark character is a special character in zsh. If that's not a
105-
feature you use, add the following line to your `~/.zshrc` to treat it as a
106-
normal character:
107-
108-
```bash
109-
unsetopt nomatch
110-
```
111-
112-
Then either restart your shell window or run `~/.zshrc`:
113-
114-
```bash
115-
source ~/.zshrc
116-
```
117-
118-
If you would prefer not to disable zsh's special handling of the question mark
119-
character, you can disable it explictly with a backslash in your keypair URLs.
120-
For example:
121-
122-
```bash
123-
solana-keygen pubkey usb://ledger\?key=0
124-
```
45+
All derivation paths implicitly include the prefix `44'/501'`, which indicates
46+
the path follows the [BIP44 specifications](https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki)
47+
and that any derived keys are Solana keys (Coin type 501). The single quote
48+
indicates a "hardened" derivation. Because Solana uses Ed25519 keypairs, all
49+
derivations are hardened and therefore adding the quote is optional and
50+
unnecessary.

‎docs/src/hardware-wallets/ledger.md

Lines changed: 190 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -9,14 +9,17 @@ secure transaction signing.
99
- [Set up a Ledger Nano S with the Solana App](../wallet-guide/ledger-live.md)
1010
- [Install the Solana command-line tools](../cli/install-solana-cli-tools.md)
1111

12-
## Use Ledger Device with Solana CLI
12+
## Use Ledger Nano S with Solana CLI
1313

1414
1. Ensure the Ledger Live application is closed
1515
2. Plug your Ledger device into your computer's USB port
1616
3. Enter your pin and start the Solana app on the Ledger device
1717
4. Press both buttons to advance past the "Pending Ledger review" screen
1818
5. Ensure the screen reads "Application is ready"
19-
6. On your computer, run:
19+
20+
### View your Wallet ID
21+
22+
On your computer, run:
2023

2124
```bash
2225
solana-keygen pubkey usb://ledger
@@ -25,39 +28,172 @@ solana-keygen pubkey usb://ledger
2528
This confirms your Ledger device is connected properly and in the correct state
2629
to interact with the Solana CLI. The command returns your Ledger's unique
2730
*wallet ID*. When you have multiple Nano S devices connected to the same
28-
computer, you can use your wallet key to specify which Ledger hardware wallet
29-
you want to use. Run the same command again, but this time, with its fully
30-
qualified URL:
31+
computer, you can use your wallet ID to specify which Ledger hardware wallet
32+
you want to use. If you only plan to use a single Nano S on your computer
33+
at a time, you don't need to include the wallet ID. For information on
34+
using the wallet ID to use a specific Ledger, see
35+
[Manage Multiple Hardware Wallets](#manage-multiple-hardware-wallets).
36+
37+
### View your Wallet Addresses
38+
39+
Your Nano S supports an arbitrary number of valid wallet addresses and signers.
40+
To view any address, use the `solana-keygen pubkey` command, as shown below,
41+
followed by a valid [keypair URL](README.md#specify-a-keypair-url).
42+
43+
Multiple wallet addresses can be useful if you want to transfer tokens between
44+
your own accounts for different purposes, or use different keypairs on the
45+
device as signing authorities for a stake account, for example.
46+
47+
All of the following commands will display different addresses, associated with
48+
the keypair path given. Try them out!
3149

3250
```bash
33-
solana-keygen pubkey usb://ledger/<WALLET_ID>
51+
solana-keygen pubkey usb://ledger
52+
solana-keygen pubkey usb://ledger?key=0
53+
solana-keygen pubkey usb://ledger?key=1
54+
solana-keygen pubkey usb://ledger?key=2
3455
```
3556

36-
where you replace `<WALLET_ID>` with the output of the first command.
37-
Confirm it prints the same wallet ID as before.
57+
You can use other values for the number after `key=` as well.
58+
Any of the addresses displayed by these commands are valid Solana wallet
59+
addresses. The private portion associated with each address is stored securely
60+
on the Nano S device, and is used to sign transactions from this address.
61+
Just make a note of which keypair URL you used to derive any address you will be
62+
using to receive tokens.
3863

39-
To learn more about keypair URLs, see
40-
[Specify A Hardware Wallet Key](README.md#specify-a-hardware-wallet-key)
64+
If you are only planning to use a single address/keypair on your device, a good
65+
easy-to-remember path might be to use the address at `key=0`. View this address
66+
with:
67+
```bash
68+
solana-keygen pubkey usb://ledger?key=0
69+
```
4170

42-
Read more about [sending and receiving tokens](../cli/transfer-tokens.md) and
43-
[delegating stake](../cli/delegate-stake.md). You can use your Ledger keypair URL
44-
anywhere you see an option or argument that accepts a `<KEYPAIR>`.
71+
Now you have a wallet address (or multiple addresses), you can share any of
72+
these addresses publicly to act as a receiving address, and you can use the
73+
associated keypair URL as the signer for transactions from that address.
74+
75+
### View your Balance
76+
77+
To view the balance of any account, regardless of which wallet it uses, use the
78+
`solana balance` command:
79+
```bash
80+
solana balance SOME_WALLET_ADDRESS
81+
```
82+
83+
For example, if your address is `7cvkjYAkUYs4W8XcXsca7cBrEGFeSUjeZmKoNBvEwyri`,
84+
then enter the following command to view the balance:
85+
```bash
86+
solana balance 7cvkjYAkUYs4W8XcXsca7cBrEGFeSUjeZmKoNBvEwyri
87+
```
88+
89+
You can also view the balance of any account address on the Accounts tab in the
90+
[Explorer](https://explorer.solana.com/accounts)
91+
and paste the address in the box to view the balance in you web browser.
92+
93+
Note: Any address with a balance of 0 SOL, such as a newly created one on your
94+
Ledger, will show as "Not Found" in the explorer. Empty accounts and non-existent
95+
accounts are treated the same in Solana. This will change when your account
96+
address has some SOL in it.
97+
98+
### Send SOL from a Ledger Nano S
99+
100+
To send some tokens from an address controlled by your Nano S device, you will
101+
need to use the device to sign a transaction, using the same keypair URL you
102+
used to derive the address. To do this, make sure your Nano S is plugged in,
103+
unlocked with the PIN, Ledger Live is not running, and the Solana App is open
104+
on the device, showing "Application is Ready".
105+
106+
The `solana transfer` command is used to specify to which address to send tokens,
107+
how many tokens to send, and uses the `--keypair` argument to specify which
108+
keypair is sending the tokens, which will sign the transaction, and the balance
109+
from the associated address will decrease.
110+
111+
```bash
112+
solana transfer RECIPIENT_ADDRESS AMOUNT --keypair KEYPAIR_URL_OF_SENDER
113+
```
114+
115+
Below is a full example. First, an address is viewed at a certain keypair URL.
116+
Second, the balance of tht address is checked. Lastly, a transfer transaction
117+
is entered to send `1` SOL to the recipient address `7cvkjYAkUYs4W8XcXsca7cBrEGFeSUjeZmKoNBvEwyri`.
118+
When you hit Enter for a transfer command, you will be prompted to approve the
119+
transaction details on your Ledger device. On the device, use the right and
120+
left buttons to review the transaction details. If they look correct, click
121+
both buttons on the "Approve" screen, otherwise push both buttons on the "Reject"
122+
screen.
123+
124+
```bash
125+
~$ solana-keygen pubkey usb://ledger?key=42
126+
CjeqzArkZt6xwdnZ9NZSf8D1CNJN1rjeFiyd8q7iLWAV
127+
128+
~$ solana balance CjeqzArkZt6xwdnZ9NZSf8D1CNJN1rjeFiyd8q7iLWAV
129+
1.000005 SOL
130+
131+
~$ solana transfer 7cvkjYAkUYs4W8XcXsca7cBrEGFeSUjeZmKoNBvEwyri 1 --keypair usb://ledger?key=42
132+
Waiting for your approval on Ledger hardware wallet usb://ledger/2JT2Xvy6T8hSmT8g6WdeDbHUgoeGdj6bE2VueCZUJmyN
133+
✅ Approved
134+
135+
Signature: kemu9jDEuPirKNRKiHan7ycybYsZp7pFefAdvWZRq5VRHCLgXTXaFVw3pfh87MQcWX4kQY4TjSBmESrwMApom1V
136+
```
137+
138+
After approving the transaction on your device, the program will display the
139+
transaction signature, and wait for the maximum number of confirmations (32)
140+
before returning. This only takes a few seconds, and then the transaction is
141+
finalized on the Solana network. You can view details of this or any other
142+
transaction by going to the Transaction tab in the
143+
[Explorer](https://explorer.solana.com/transactions)
144+
and paste in the transaction signature.
145+
146+
## Advanced Operations
147+
148+
### Manage Multiple Hardware Wallets
149+
150+
It is sometimes useful to sign a transaction with keys from multiple hardware
151+
wallets. Signing with multiple wallets requires *fully qualified keypair URLs*.
152+
When the URL is not fully qualified, the Solana CLI will prompt you with
153+
the fully qualified URLs of all connected hardware wallets, and ask you to
154+
choose which wallet to use for each signature.
155+
156+
Instead of using the interactive prompts, you can generate fully qualified
157+
URLs using the Solana CLI `resolve-signer` command. For example, try
158+
connecting a Ledger Nano-S to USB, unlock it with your pin, and running the
159+
following command:
160+
161+
```text
162+
solana resolve-signer usb://ledger?key=0/0
163+
```
164+
165+
You will see output similar to:
166+
167+
```text
168+
usb://ledger/BsNsvfXqQTtJnagwFWdBS7FBXgnsK8VZ5CmuznN85swK?key=0/0
169+
```
170+
171+
but where `BsNsvfXqQTtJnagwFWdBS7FBXgnsK8VZ5CmuznN85swK` is your `WALLET_ID`.
172+
173+
With your fully qualified URL, you can connect multiple hardware wallets to
174+
the same computer and uniquely identify a keypair from any of them.
175+
Use the output from the `resolve-signer` command anywhere a `solana` command
176+
expects a `<KEYPAIR>` entry to use that resolved path as the signer for that
177+
part of the given transaction.
45178

46179
### Install the Solana Beta App
47180

48181
You're invited to help us test the latest pre-release version of our Ledger app
49182
on one of the public testnets.
50183

51-
You can use the command-line to install the latest Solana Ledger app release before it has been validated by
184+
You can use the command-line to install the latest Solana Ledger app release
185+
before it has been validated by
52186
the Ledger team and made available via Ledger Live. Note that because the app
53187
is not installed via Ledger Live, you will need to approve installation from an
54188
"unsafe" manager, as well as see the message, "This app is not genuine" each
55189
time you open the app. Once the app is available on Ledger Live, you can
56190
reinstall the app from there, and the message will no longer be displayed.
57191

58-
**WARNING:** Installing an unsigned Ledger app reduces the security of your Ledger device.
59-
If your client is compromised, an attacker will be able to trick you into signing arbitrary
60-
transactions with arbitrary derivation paths. Only use this installation method if you understand
192+
**WARNING:** Installing an unsigned Ledger app reduces the security of your
193+
Ledger device.
194+
If your client is compromised, an attacker will be able to trick you into
195+
signing arbitrary transactions with arbitrary derivation paths.
196+
Only use this installation method if you understand
61197
the security implications. We strongly recommend that you use a separate
62198
Ledger device, with no other wallets/apps sharing the same seed phrase.
63199

@@ -71,6 +207,8 @@ Ledger device, with no other wallets/apps sharing the same seed phrase.
71207
5. An installation window appears and your device will display "Processing..."
72208
6. The app installation is confirmed
73209

210+
#### Installing the Solana Beta App returns an error
211+
74212
If you encounter the following error:
75213

76214
```text
@@ -93,6 +231,40 @@ To fix, check the following:
93231
2. Ensure your Ledger device is unlocked and not waiting for you to enter your pin
94232
3. Ensure the Ledger Live application is not open
95233

234+
## Troubleshooting
235+
236+
### Keypair URL parameters are ignored in zsh
237+
238+
The question mark character is a special character in zsh. If that's not a
239+
feature you use, add the following line to your `~/.zshrc` to treat it as a
240+
normal character:
241+
242+
```bash
243+
unsetopt nomatch
244+
```
245+
246+
Then either restart your shell window or run `~/.zshrc`:
247+
248+
```bash
249+
source ~/.zshrc
250+
```
251+
252+
If you would prefer not to disable zsh's special handling of the question mark
253+
character, you can disable it explictly with a backslash in your keypair URLs.
254+
For example:
255+
256+
```bash
257+
solana-keygen pubkey usb://ledger\?key=0
258+
```
259+
96260
## Support
97261

98-
Check out our [Wallet Support Page](../wallet-guide/support.md) for ways to get help.
262+
Check out our [Wallet Support Page](../wallet-guide/support.md)
263+
for ways to get help.
264+
265+
266+
267+
268+
Read more about [sending and receiving tokens](../cli/transfer-tokens.md) and
269+
[delegating stake](../cli/delegate-stake.md). You can use your Ledger keypair URL
270+
anywhere you see an option or argument that accepts a `<KEYPAIR>`.

0 commit comments

Comments
 (0)