Dan Albert
GitHub
124
docs/src/hardware-wallets/README.md
Normal file
124
docs/src/hardware-wallets/README.md
Normal file
@@ -0,0 +1,124 @@
|
||||
# Hardware Wallets
|
||||
|
||||
Signing a transaction requires a private key, but storing a private
|
||||
key on your personal computer or phone leaves it subject to theft.
|
||||
Adding a password to your key adds security, but many people prefer
|
||||
to take it a step further and move their private keys to a separate
|
||||
physical device called a *hardware wallet*. A hardware wallet is a
|
||||
small handheld device that stores private keys and provides some
|
||||
interface for signing transactions.
|
||||
|
||||
The Solana CLI has first class support for hardware wallets. Anywhere
|
||||
you use a keypair filepath (denoted as `<KEYPAIR>` in usage docs), you
|
||||
can pass a *keypair URL* that uniquely identifies a keypair in a
|
||||
hardware wallet.
|
||||
|
||||
## Supported Hardware Wallets
|
||||
|
||||
The Solana CLI supports the following hardware wallets:
|
||||
- [Ledger Nano S](ledger.md)
|
||||
|
||||
## Specify a Hardware Wallet Key
|
||||
|
||||
Solana defines a keypair URL format to uniquely locate any Solana keypair on a
|
||||
hardware wallet connected to your computer.
|
||||
|
||||
The keypair URL has the following form, where square brackets denote optional
|
||||
fields:
|
||||
|
||||
```text
|
||||
usb://<MANUFACTURER>[/<WALLET_ID>][?key=<DERIVATION_PATH>]
|
||||
```
|
||||
|
||||
`WALLET_ID` is a globally unique key used to disambiguate multiple devices.
|
||||
|
||||
`DERVIATION_PATH` is used to navigate to Solana keys within your hardware wallet.
|
||||
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
|
||||
```
|
||||
90
docs/src/hardware-wallets/ledger.md
Normal file
90
docs/src/hardware-wallets/ledger.md
Normal file
@@ -0,0 +1,90 @@
|
||||
# Ledger Hardware Wallet
|
||||
|
||||
The Ledger Nano S hardware wallet offers secure storage of your Solana private
|
||||
keys. The Solana Ledger app enables derivation of essentially infinite keys, and
|
||||
secure transaction signing.
|
||||
|
||||
## Before You Begin
|
||||
|
||||
- [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
|
||||
|
||||
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:
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
solana-keygen pubkey usb://ledger/<WALLET_ID>
|
||||
```
|
||||
|
||||
where you replace `<WALLET_ID>` with the output of the first command.
|
||||
Confirm it prints the same wallet ID as before.
|
||||
|
||||
To learn more about keypair URLs, see
|
||||
[Specify A Hardware Wallet Key](README.md#specify-a-hardware-wallet-key)
|
||||
|
||||
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>`.
|
||||
|
||||
### Install the Solana Beta App
|
||||
|
||||
For those of you that enjoy life on the edge, 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.
|
||||
|
||||
1. Connect your Ledger device via USB and enter your pin to unlock it
|
||||
2. Download and run the Solana Ledger app installer:
|
||||
```text
|
||||
curl -sSLf https://github.com/solana-labs/ledger-app-solana/releases/download/v0.2.0/install.sh | sh
|
||||
```
|
||||
3. When prompted, approve the "unsafe" manager on your device
|
||||
4. When prompted, approve the installation on your device
|
||||
5. An installation window appears and your device will display "Processing..."
|
||||
6. The app installation is confirmed
|
||||
|
||||
If you encounter the following error:
|
||||
|
||||
```text
|
||||
Traceback (most recent call last):
|
||||
File "/Library/Developer/CommandLineTools/Library/Frameworks/Python3.framework/Versions/3.7/lib/python3.7/runpy.py", line 193, in _run_module_as_main
|
||||
"__main__", mod_spec)
|
||||
File "/Library/Developer/CommandLineTools/Library/Frameworks/Python3.framework/Versions/3.7/lib/python3.7/runpy.py", line 85, in _run_code
|
||||
exec(code, run_globals)
|
||||
File "ledger-env/lib/python3.7/site-packages/ledgerblue/loadApp.py", line 197, in <module>
|
||||
dongle = getDongle(args.apdu)
|
||||
File "ledger-env/lib/python3.7/site-packages/ledgerblue/comm.py", line 216, in getDongle
|
||||
dev.open_path(hidDevicePath)
|
||||
File "hid.pyx", line 72, in hid.device.open_path
|
||||
OSError: open failed
|
||||
```
|
||||
|
||||
To fix, check the following:
|
||||
|
||||
1. Ensure your Ledger device is connected to USB
|
||||
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
|
||||
|
||||
## Support
|
||||
|
||||
Check out our [Wallet Support Page](../wallet-guide/support.md) for ways to get help.
|
||||
Reference in New Issue
Block a user