gaspersic/solana
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

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

Browse Source 
automerge
This commit is contained in:
mergify[bot]
2020-03-18 19:15:34 -07:00
committed by GitHub
parent 51940eec9b
commit 8eaa8d8788
6 changed files with 303 additions and 15 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
docs/src/SUMMARY.md
View File

@ -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)

2
docs/src/cli/README.md
View File

@ -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

79
docs/src/cli/choose-a-wallet.md Normal file
View File

@ -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.

90
docs/src/cli/generate-keys.md Normal file
View File

@ -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.

116
docs/src/cli/transfer-tokens.md Normal file
View File

@ -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>
```

22
docs/src/remote-wallet/README.md
View File

@ -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
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://<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
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 `<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.