From 0102ee3fa91f899569c4eb0a975cf932e3b1cf23 Mon Sep 17 00:00:00 2001 From: "mergify[bot]" <37929162+mergify[bot]@users.noreply.github.com> Date: Mon, 16 Mar 2020 16:31:35 -0700 Subject: [PATCH] Hoist USB URL docs (#8894) (#8895) automerge --- docs/src/SUMMARY.md | 2 +- docs/src/remote-wallet/README.md | 85 +++++++++++++++++++++++++++++--- docs/src/remote-wallet/ledger.md | 35 +------------ 3 files changed, 80 insertions(+), 42 deletions(-) diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md index ee6759e6bc..269e66f860 100644 --- a/docs/src/SUMMARY.md +++ b/docs/src/SUMMARY.md @@ -4,7 +4,7 @@ * [Install Solana](install-solana.md) * [Use Solana from the Command-line](cli/README.md) * [Command-line Usage](cli/usage.md) - * [Remote Wallet](remote-wallet/README.md) + * [Hardware Wallets](remote-wallet/README.md) * [Ledger Hardware Wallet](remote-wallet/ledger.md) * [Paper Wallet](paper-wallet/README.md) * [Paper Wallet Usage](paper-wallet/usage.md) diff --git a/docs/src/remote-wallet/README.md b/docs/src/remote-wallet/README.md index 25babad4d8..b26a7d49db 100644 --- a/docs/src/remote-wallet/README.md +++ b/docs/src/remote-wallet/README.md @@ -1,12 +1,81 @@ -# Remote Wallet +# Hardware Wallets -This document describes how to use a remote wallet with the Solana CLI -tools. Currently, Solana supports: -- Ledger hardware wallet (Nano S) +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. -## Overview +The Solana CLI has first class support for hardware wallets. Anywhere +you use a keypair filepath (denoted as `` in usage docs), you +can pass a URL that uniquely identifies a keypair in a hardware +wallet. -Solana's remote-wallet integration provides Solana CLI methods to query a -device's BIP32 public keys and send messages to the device for secure signing. +## Supported Hardware Wallets -{% page-ref page="ledger.md" %} +The Solana CLI supports the following hardware wallets: +- Ledger Nano S {% page-ref page="ledger.md" %} + +## Specify A Hardware Wallet Key + +Solana defines a format for the URL protocol "usb://" to uniquely locate any +Solana key on any hardware wallet connected to your computer. + +The URL has the following form, where square brackets denote optional fields: + +```text +usb://[/[/]][?key=] +``` + +`PRODUCT` is optional and defaults to an auto-detected value. When using a Ledger +Nano S, for example, it defaults to "nano-s" without quotes. + +`WALLET_KEY` is used to disambiguate multiple devices. Each device has a unique +master key and from that key derives a separate unique key per app. + +`DERVIATION_PATH` is used to navigate to Solana keys within your hardware wallet. +The path has the form `[/]`, 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/nano-s/BsNsvfXqQTtJnagwFWdBS7FBXgnsK8VZ5CmuznN85swK?key=0/0 +``` + +## 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 USB 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/nano-s/BsNsvfXqQTtJnagwFWdBS7FBXgnsK8VZ5CmuznN85swK?key=0/0 +``` + +but where `BsNsvfXqQTtJnagwFWdBS7FBXgnsK8VZ5CmuznN85swK` is your `WALLET_KEY`. + +With your fully qualified URL, you can connect multiple hardware wallets to +the same computer and uniquely identify a keypair from any of them. diff --git a/docs/src/remote-wallet/ledger.md b/docs/src/remote-wallet/ledger.md index 02d3a45968..fdd54c3b7c 100644 --- a/docs/src/remote-wallet/ledger.md +++ b/docs/src/remote-wallet/ledger.md @@ -88,39 +88,8 @@ solana address --keypair usb://ledger/nano-s/ Confirm it prints the same key as when you entered just `usb://ledger`. -### Ledger Device URLs - -Solana defines a format for the URL protocol "usb://" to uniquely locate any Solana key on -any remote wallet connected to your computer. - -The URL has the form, where square brackets denote optional fields: - -```text -usb://ledger[/[/]][?key=] -``` - -`LEDGER_TYPE` is optional and defaults to the value "nano-s". If the value is provided, -it must be "nano-s" without quotes, the only supported Ledger device at this time. - -`WALLET_KEY` is used to disambiguate multiple Nano S devices. Every Ledger has -a unique master key and from that key derives a separate unique key per app. - -`DERVIATION_PATH` is used to navigate to Solana keys within your Ledger hardware -wallet. The path has the form `[/]`, where each `ACCOUNT` and -`CHANGE` are postive 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 dervied 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 complete Ledger device path might be: - -```text -usb://ledger/nano-s/BsNsvfXqQTtJnagwFWdBS7FBXgnsK8VZ5CmuznN85swK?key=0/0 -``` +To learn more about USB URLs, see +[Specify A Hardware Wallet Key](index.md#specify-a-hardware-wallet-key) ### Set CLI Configuration