From 8eaa8d8788f51a5fd7212f390c194abd26b2179d Mon Sep 17 00:00:00 2001 From: "mergify[bot]" <37929162+mergify[bot]@users.noreply.github.com> Date: Wed, 18 Mar 2020 19:15:34 -0700 Subject: [PATCH] Add docs on wallets and generating keys (bp #8905) (#8946) automerge --- docs/src/SUMMARY.md | 9 ++- docs/src/cli/README.md | 2 +- docs/src/cli/choose-a-wallet.md | 79 +++++++++++++++++++++ docs/src/cli/generate-keys.md | 90 ++++++++++++++++++++++++ docs/src/cli/transfer-tokens.md | 116 +++++++++++++++++++++++++++++++ docs/src/remote-wallet/README.md | 22 +++--- 6 files changed, 303 insertions(+), 15 deletions(-) create mode 100644 docs/src/cli/choose-a-wallet.md create mode 100644 docs/src/cli/generate-keys.md create mode 100644 docs/src/cli/transfer-tokens.md diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md index 269e66f860..50ab932608 100644 --- a/docs/src/SUMMARY.md +++ b/docs/src/SUMMARY.md @@ -1,15 +1,18 @@ # Table of contents * [Introduction](introduction.md) -* [Install Solana](install-solana.md) -* [Use Solana from the Command-line](cli/README.md) - * [Command-line Usage](cli/usage.md) +* [Install the Solana Tool Suite](install-solana.md) +* [Command-line Guide](cli/README.md) + * [Choose a Wallet](cli/choose-a-wallet.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) + * [Generate Keys](cli/generate-keys.md) + * [Send and Receive Tokens](cli/transfer-tokens.md) * [Offline Signing](offline-signing/README.md) * [Durable Transaction Nonces](offline-signing/durable-nonce.md) + * [Command-line Reference](cli/usage.md) * [Develop Applications](apps/README.md) * [Example: Web Wallet](apps/webwallet.md) * [Example: Tic-Tac-Toe](apps/tictactoe.md) diff --git a/docs/src/cli/README.md b/docs/src/cli/README.md index f5ffb32cc7..d56fac2d73 100644 --- a/docs/src/cli/README.md +++ b/docs/src/cli/README.md @@ -1,4 +1,4 @@ -# Using Solana from the Command-line +# Command-line Guide This section describes the command-line tools for interacting with Solana. One could use these tools to send payments, stake validators, and check account diff --git a/docs/src/cli/choose-a-wallet.md b/docs/src/cli/choose-a-wallet.md new file mode 100644 index 0000000000..7681268dc9 --- /dev/null +++ b/docs/src/cli/choose-a-wallet.md @@ -0,0 +1,79 @@ +# Choose a Wallet + +Keypairs are stored in *wallets* and wallets come in many forms. A wallet might +be a directory in your computer's file system, a piece of paper, or a +specialized device called a *hardware wallet*. Some wallets are easier to use +than others. Some are more secure than others. In this section, we'll compare +and contrast different types of wallets and help you choose the wallet that +best fits your needs. + +## File System Wallet + +A *file system wallet*, aka an FS wallet, is a directory in your computer's +file system. Each file in the directory holds a keypair. + +### FS Wallet Security + +An FS wallet is the most convenient and least secure form of wallet. It is +convenient because the keypair is stored in a simple file. You can generate as +many keys as you'd like and trivially back them up by copying the files. It is +insecure because the keypair files are **unencrypted**. If you are the only +user of your computer and you are confident it is free of malware, an FS wallet +is a fine solution for small amounts of cryptocurrency. If, however, your +computer contains malware and is connected to the Internet, that malware may +upload your keys and use them to take your tokens. Likewise, because the +keypairs are stored on your computer as files, a skilled hacker with physical +access to your computer may be able to access it. Using an encrypted hard +drive, such as FileVault on MacOS, minimizes that risk. + +## Paper Wallet + +A *paper wallet* is a collection of *seed phrases* written on paper. A seed +phrase is some number of words (typically 12 or 24) that can be used to +regenerate a keypair on demand. + +### Paper Wallet Security + +In terms of convenience versus security, a paper wallet sits at the opposite +side of the spectrum from an FS wallet. It is terribly inconvenient to use, but +offers excellent security. That high security is further amplified when paper +wallets are used in conjunction with +[offline signing](../offline-signing/index.md). Custody services such as +[Coinbase Custody](https://custody.coinbase.com/) use this combination. Paper wallets +and custody services are an excellent way to secure a large number of tokens +for a long period of time. + +## Hardware Wallet + +A hardware wallet is a small handheld device that stores keypairs and provides +some interface for signing transactions. + +### Hardware Wallet Security + +A hardware wallet, such as the +[Ledger hardware wallet](https://www.ledger.com/), offers a great blend of +security and convenience for cryptocurrencies. It effectively automates the +process of offline signing while retaining nearly all the convenience of an FS +wallet. In contrast to offline signing with paper wallets, which we regard as +highly secure, offline signing with hardware wallets presents some security +concerns: + +* Keys could be leaked by a malicious app on the hardware wallet +* Keys could be stolen by a malicious client via a bug in the hardware wallet's + operating system +* Keys could be read from storage if hardware wallet is lost or stolen + +To keep your hardware wallet tokens safe, we suggest: + +* Only install apps using the vendor's app manager +* Keep the hardware wallet's firmware up to date +* Put keys for large amounts of tokens into their own hardware wallets. Store + in a secure location. + +## Which Wallet is Best? + +Different people will have different needs, but if you are still unsure what's +best for you after reading the comparisons above, go with a +[Ledger Nano S](https://shop.ledger.com/products/ledger-nano-s). The +[Nano S is well-integrated into Solana's tool suite](../remote-wallet/ledger) +and offers an outstanding blend of security and convenience. diff --git a/docs/src/cli/generate-keys.md b/docs/src/cli/generate-keys.md new file mode 100644 index 0000000000..5f9b0bfffa --- /dev/null +++ b/docs/src/cli/generate-keys.md @@ -0,0 +1,90 @@ +# Generate a Keypair and its Public Key + +In this section, we'll generate a keypair, query it for its public key, +and verify you control its private key. Before you begin, you'll need +to: + +* [Install the Solana Tool Suite](../install-solana.md) +* [Choose a wallet](choose-a-wallet.md) + +## Generate an FS Wallet Keypair + +Use Solana's command-line tool `solana-keygen` to generate keypair files. For +example, run the following from a command-line shell: + +```bash +mkdir ~/my-solana-wallet +solana-keygen new -o ~/my-solana-wallet/my-keypair.json +``` + +If you view the file, you will see a long list of numbers, such as: + +```text +[42,200,155,187,52,228,32,9,179,129,192,196,149,41,177,47,87,228,5,19,70,82,170,6,142,114,68,85,124,34,165,216,110,186,177,254,198,143,235,59,173,59,17,250,142,32,66,162,130,62,53,252,48,33,148,38,149,17,81,154,95,178,163,164] +``` + +This file contains your **unencrypted** keypair. In fact, even if you specify +a password, that password applies to the recovery seed phrase, not the file. Do +not share this file with others. Anyone with access to this file will have access +to all tokens sent to its public key. Instead, you should share only its public +key. To display its public key, run: + +```bash +solana-keygen pubkey ~/my-solana-wallet/my-keypair.json +``` + +It will output a string of characters, such as: + +```text +ErRr1caKzK8L8nn4xmEWtimYRiTCAZXjBtVphuZ5vMKy +``` + +This is the public key corresponding to the keypair in `~/my-solana-wallet/my-keypair.json`. +To verify you hold the private key for a given public key, use `solana-keygen verify`: + +```bash +solana-keygen verify ~/my-solana-wallet/my-keypair.json +``` + +where `` is the public key output from the previous command. +The command will output "Success" if the given public key matches the +the one in your keypair file, and "Failed" otherwise. + +## Generate a Paper Wallet Seed Phrase + +See [Creating a Paper Wallet](../paper-wallet/usage.md#creating-a-paper-wallet). + +To verify you control the private key of that public key, use `solana-keygen verify`: + +```bash +solana-keygen verify ASK +``` + +where `` is the keypair's public key and they keyword `ASK` tells the +command to prompt you for the keypair's seed phrase. Note that for security +reasons, your seed phrase will not be displayed as you type. After entering your +seed phrase, the command will output "Success" if the given public key matches the +keypair generated from your seed phrase, and "Failed" otherwise. + +## Generate a Hardware Wallet Keypair + +Keypairs are automatically derived when you query a hardware wallet with a +[keypair URL](../remote-wallet#specify-a-hardware-wallet-key). + +Once you have your keypair URL, use `solana-keygen pubkey` to query the hardware +wallet for the keypair's public key: + +```bash +solana-keygen pubkey +``` + +where `` is the keypair URL. + +To verify you control the private key of that public key, use `solana-keygen verify`: + +```bash +solana-keygen verify +``` + +The command will output "Success" if the given public key matches the +the one at your keypair URL, and "Failed" otherwise. diff --git a/docs/src/cli/transfer-tokens.md b/docs/src/cli/transfer-tokens.md new file mode 100644 index 0000000000..33a8b8bd2b --- /dev/null +++ b/docs/src/cli/transfer-tokens.md @@ -0,0 +1,116 @@ +# Send and Receive Tokens + +## Receive Tokens + +To receive tokens, you will need an address for others to send tokens to. In +Solana, an address is the public key of a keypair. There are a variety +of techniques for generating keypairs. The method you choose will depend on how +you choose to store keypairs. Keypairs are stored in wallets. Before receiving +tokens, you'll need to [choose a wallet](choose-a-wallet.md) and +[generate keys](generate-keys.md). Once completed, you should have a public key +for each keypair you generated. The public key is a long string of base58 +characters. Its length varies from 32 to 44 characters. + +### Using Solana CLI + +Before running any Solana CLI commands, let's go over some conventions that +you will see across all commands. First, the Solana CLI is actually a collection +of different commands for each action you might want to take. You can view the list +of all possible commands by running: + +```bash +solana --help +``` + +To zoom in on how to use a particular command, run: + +```bash +solana --help +``` + +where you replace the text `` with the name of the command you want +to learn more about. + +The command's usage message will typically contain words such as ``, +`` or ``. Each word is a placeholder for the *type* of text +you can execute the command with. For example, you can replace `` +with a number such as `42` or `100.42`. You can replace `` with the +base58 encoding of your public key. For ``, it depends on what type +of wallet you chose. If you chose an fs wallet, that path might be +`~/my-solana-wallet/my-keypair.json`. If you chose a paper wallet, use the +keyword `ASK`, and the Solana CLI will prompt you for your seed phrase. If +you chose a hardware wallet, use your USB URL, such as `usb://ledger?key=0`. + +### Test-drive your Public Keys + +Before sharing your public key with others, you may want to first ensure the +key is valid and that you indeed hold the corresponding private key. + +Try and *airdrop* yourself some play tokens on the developer testnet, called +Devnet: + +```bash +solana airdrop 10 --url http://devnet.solana.com +``` + +where you replace the text `` with your base58 public key. + +Confirm the airdrop was successful by checking the account's balance. +It should output `10 SOL`: + +```bash +solana balance --url http://devnet.solana.com +``` + +Next, prove that you own those tokens by transferring them. The Solana cluster +will only accept the transfer if you sign the transaction with the private +key corresponding to the sender's public key in the transaction. + +First, we'll need a public key to receive our tokens. Create a second +keypair and record its pubkey: + +```bash +solana-keygen new --no-passphrase --no-outfile +``` + +The output will contain the public key after the text `pubkey:`. Copy the +public key. We'll use it in the next step. + +```text +============================================================================ +pubkey: GKvqsuNcnwWqPzzuhLmGi4rzzh55FhJtGizkhHaEJqiV +============================================================================ +``` + +```bash +solana transfer --keypair= 5 --url http://devnet.solana.com +``` + +where you replace `` with the path to a keypair in your wallet, +and replace `` with the output of `solana-keygen new` above. + +Confirm the updated balances with `solana balance`: + +```bash +solana balance --url http://devnet.solana.com +``` + +where `` is either the public key from your keypair or the +recipient's public key. + +## Send Tokens + +If you already hold SOL and want to send tokens to someone, you will need +a path to your keypair, their base58-encoded public key, and a number of +tokens to transfer. Once you have that collected, you can transfer tokens +with the `solana transfer` command: + +```bash +solana transfer --keypair= +``` + +Confirm the updated balances with `solana balance`: + +```bash +solana balance +``` diff --git a/docs/src/remote-wallet/README.md b/docs/src/remote-wallet/README.md index 0c9ff373f7..017a786ad5 100644 --- a/docs/src/remote-wallet/README.md +++ b/docs/src/remote-wallet/README.md @@ -10,27 +10,27 @@ interface for signing transactions. 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. +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 {% page-ref page="ledger.md" %} +- [Ledger Nano S](ledger.md) -## Specify A Hardware Wallet Key +## 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. +Solana defines a keypair URL format to uniquely locate any Solana keypair on a +hardware wallet connected to your computer. -The URL has the following form, where square brackets denote optional fields: +The keypair URL has the following form, where square brackets denote optional +fields: ```text -usb://[/][?key=] +usb://[/][?key=] ``` -`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. +`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 `[/]`, where each `ACCOUNT` and `CHANGE` @@ -72,7 +72,7 @@ You will see output similar to: usb://ledger/BsNsvfXqQTtJnagwFWdBS7FBXgnsK8VZ5CmuznN85swK?key=0/0 ``` -but where `BsNsvfXqQTtJnagwFWdBS7FBXgnsK8VZ5CmuznN85swK` is your `WALLET_KEY`. +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.