Add docs on wallets and generating keys (bp #8905) (#8946)

automerge

docs/src/SUMMARY.md

@@ -1,15 +1,18 @@
 # Table of contents
 
 * [Introduction](introduction.md)
-* [Install Solana](install-solana.md)
+* [Install the Solana Tool Suite](install-solana.md)
-* [Use Solana from the Command-line](cli/README.md)
+* [Command-line Guide](cli/README.md)
-  * [Command-line Usage](cli/usage.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)

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

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.

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 <PUBKEY> ~/my-solana-wallet/my-keypair.json
+```
+
+where `<PUBKEY>` 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 <PUBKEY> ASK
+```
+
+where `<PUBKEY>` 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 <KEYPAIR>
+```
+
+where `<KEYPAIR>` is the keypair URL.
+
+To verify you control the private key of that public key, use `solana-keygen verify`:
+
+```bash
+solana-keygen verify <PUBKEY> <KEYPAIR>
+```
+
+The command will output "Success" if the given public key matches the
+the one at your keypair URL, and "Failed" otherwise.

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 <COMMAND> --help
+```
+
+where you replace the text `<COMMAND>` with the name of the command you want
+to learn more about.
+
+The command's usage message will typically contain words such as `<NUMBER>`,
+`<PUBKEY>` or `<KEYPAIR>`. Each word is a placeholder for the *type* of text
+you can execute the command with. For example, you can replace `<NUMBER>`
+with a number such as `42` or `100.42`. You can replace `<PUBKEY>` with the
+base58 encoding of your public key. For `<KEYPAIR>`, 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 <PUBKEY> --url http://devnet.solana.com
+```
+
+where you replace the text `<PUBKEY>` with your base58 public key.
+
+Confirm the airdrop was successful by checking the account's balance.
+It should output `10 SOL`:
+
+```bash
+solana balance <PUBKEY> --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=<KEYPAIR> <PUBKEY> 5 --url http://devnet.solana.com
+```
+
+where you replace `<KEYPAIR>` with the path to a keypair in your wallet,
+and replace `<PUBKEY>` with the output of `solana-keygen new` above.
+
+Confirm the updated balances with `solana balance`:
+
+```bash
+solana balance <PUBKEY> --url http://devnet.solana.com
+```
+
+where `<PUBKEY>` 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=<KEYPAIR> <PUBKEY> <NUMBER>
+```
+
+Confirm the updated balances with `solana balance`:
+
+```bash
+solana balance <PUBKEY>
+```

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 `<KEYPAIR>` in usage docs), you
-can pass a URL that uniquely identifies a keypair in a hardware
+can pass a *keypair URL* that uniquely identifies a keypair in a
-wallet.
+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 defines a keypair URL format to uniquely locate any Solana keypair on a
-Solana key on any hardware wallet connected to your computer.
+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://<MANUFACTURER>[/<WALLET_KEY>][?key=<DERIVATION_PATH>]
+usb://<MANUFACTURER>[/<WALLET_ID>][?key=<DERIVATION_PATH>]
 ```
 
-`WALLET_KEY` is used to disambiguate multiple devices. Each device has a unique
+`WALLET_ID` is a globally unique key used to disambiguate multiple devices.
-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 `<ACCOUNT>[/<CHANGE>]`, 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.