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

Refactor file and URL paths in docusaurus (#11080)

Browse Source 
* Fix introduction link

* Restore staking guide pages

* Remove Edit this page link

* Fix broken wallet guide link

* Restore lost images

* Fixup URL paths to match gitbook style

* Refactor wallet guide READMEs and clean up URLs

* Remove lingering gitbook files

* Refactor all README files to keep consistent linking

* Updte homepage tile links

Co-authored-by: publish-docs.sh <maintainers@solana.com>
This commit is contained in:
Dan Albert
2020-07-15 14:11:51 -06:00
committed by GitHub
parent 7fe870ba48
commit 6342e3e215
50 changed files with 107 additions and 274 deletions
Download Patch File Download Diff File Expand all files Collapse all files

66
docs/src/wallet-guide/README.md
View File

@@ -1,66 +0,0 @@
---
title: Solana Wallet Guide
---
This document describes the different wallet options that are available to users
of Solana who want to be able to send, receive and interact with
SOL tokens on the Solana blockchain.
## What is a Wallet?
A crypto wallet is a device or application that stores a collection of keys and
can be used to send, receive,
and track ownership of cryptocurrencies. Wallets can take many forms.
A wallet might be a directory or file in your computer's file system,
a piece of paper, or a specialized device called a _hardware wallet_.
There are also various smartphone apps and computer programs
that provide a user-friendly way to create and manage wallets.
A _keypair_ is a securely generated _private key_ and its
cryptographically-derived _public key_. A private key and its corresponding
public key are together known as a _keypair_.
A wallet contains a collection of one or more keypairs and provides some means
to interact with them.
The _public key_ (commonly shortened to _pubkey_) is known as the wallet's
_receiving address_ or simply its _address_. The wallet address **may be shared
and displayed freely**. When another party is going to send some amount of
cryptocurrency to a wallet, they need to know the wallet's receiving address.
Depending on a blockchain's implementation, the address can also be used to view
certain information about a wallet, such as viewing the balance,
but has no ability to change anything about the wallet or withdraw any tokens.
The _private key_ is required to digitally sign any transactions to send
cryptocurrencies to another address or to make any changes to the wallet.
The private key **must never be shared**. If someone gains access to the
private key to a wallet, they can withdraw all the tokens it contains.
If the private key for a wallet is lost, any tokens that have been sent
to that wallet's address are **permanently lost**.
Different wallet solutions offer different approaches to keypair security and
interacting with the keypair and sign transactions to use/spend the tokens.
Some are easier to use than others.
Some store and back up private keys more securely.
Solana supports multiple types of wallets so you can choose the right balance
of security and convenience.
**If you want to be able to receive SOL tokens on the Solana blockchain,
you first will need to create a wallet.**
## Supported Wallets
Solana supports supports several types of wallets in the Solana native
command-line app as well as wallets from third-parties.
For the majority of users, we recommend using one of the
[app wallets](apps.md), which will provide a more familiar user
experience rather than needing to learn command line tools.
{% page-ref page="apps.md" %}
For advanced users or developers, the [command-line wallets](cli.md)
may be more appropriate, as new features on the Solana blockchain will always be
supported on the command line first before being integrated into third-party
solutions.
{% page-ref page="cli.md" %}

4
docs/src/wallet-guide/cli.md
View File

@@ -44,12 +44,12 @@ 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/README.md). Custody services such as
[offline signing](../offline-signing.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.
[Paper Wallets](../paper-wallet/README.md)
[Paper Wallets](paper-wallet.md)
## Hardware Wallet

65
docs/src/wallet-guide/file-system-wallet.md Normal file
View File

@@ -0,0 +1,65 @@
---
title: File System Wallet
---
This document describes how to create and use a file system wallet with the
Solana CLI tools. A file system wallet exists as an unencrypted keypair file
on your computer system's filesystem.
> File system wallets are the **least secure** method of storing SOL tokens. Storing large amounts of tokens in a file system wallet is **not recommended**.
## Before you Begin
Make sure you have
[installed the Solana Command Line Tools](../cli/install-solana-cli-tools.md)
## Generate a File System 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 --outfile ~/my-solana-wallet/my-keypair.json
```
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`. The public key of the keypair file is
your _wallet address_.
## Verify your Address against your Keypair file
To verify you hold the private key for a given address, use
`solana-keygen verify`:
```bash
solana-keygen verify <PUBKEY> ~/my-solana-wallet/my-keypair.json
```
where `<PUBKEY>` is replaced with your wallet address.
The command will output "Success" if the given address matches the
the one in your keypair file, and "Failed" otherwise.
## Creating Multiple File System Wallet Addresses
You can create as many wallet addresses as you like. Simply re-run the
steps in [Generate a File System Wallet](#generate-a-file-system-wallet-keypair)
and make sure to use a new filename or path with the `--outfile` argument.
Multiple wallet addresses can be useful if you want to transfer tokens between
your own accounts for different purposes.

53
docs/src/wallet-guide/hardware-wallets.md Normal file
View File

@@ -0,0 +1,53 @@
---
title: 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](hardware-wallets/ledger.md)
## Specify a Keypair URL
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.
For example, a fully qualified URL for a Ledger device might be:
```text
usb://ledger/BsNsvfXqQTtJnagwFWdBS7FBXgnsK8VZ5CmuznN85swK?key=0/0
```
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.

272
docs/src/wallet-guide/hardware-wallets/ledger.md Normal file
View File

@@ -0,0 +1,272 @@
---
title: 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](../ledger-live.md)
- [Install the Solana command-line tools](../../cli/install-solana-cli-tools.md)
## Use Ledger Nano S 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"
### View your Wallet ID
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 ID to specify which Ledger hardware wallet
you want to use. If you only plan to use a single Nano S on your computer
at a time, you don't need to include the wallet ID. For information on
using the wallet ID to use a specific Ledger, see
[Manage Multiple Hardware Wallets](#manage-multiple-hardware-wallets).
### View your Wallet Addresses
Your Nano S supports an arbitrary number of valid wallet addresses and signers.
To view any address, use the `solana-keygen pubkey` command, as shown below,
followed by a valid [keypair URL](../hardware-wallets.md#specify-a-keypair-url).
Multiple wallet addresses can be useful if you want to transfer tokens between
your own accounts for different purposes, or use different keypairs on the
device as signing authorities for a stake account, for example.
All of the following commands will display different addresses, associated with
the keypair path given. Try them out!
```bash
solana-keygen pubkey usb://ledger
solana-keygen pubkey usb://ledger?key=0
solana-keygen pubkey usb://ledger?key=1
solana-keygen pubkey usb://ledger?key=2
```
You can use other values for the number after `key=` as well.
Any of the addresses displayed by these commands are valid Solana wallet
addresses. The private portion associated with each address is stored securely
on the Nano S device, and is used to sign transactions from this address.
Just make a note of which keypair URL you used to derive any address you will be
using to receive tokens.
If you are only planning to use a single address/keypair on your device, a good
easy-to-remember path might be to use the address at `key=0`. View this address
with:
```bash
solana-keygen pubkey usb://ledger?key=0
```
Now you have a wallet address (or multiple addresses), you can share any of
these addresses publicly to act as a receiving address, and you can use the
associated keypair URL as the signer for transactions from that address.
### View your Balance
To view the balance of any account, regardless of which wallet it uses, use the
`solana balance` command:
```bash
solana balance SOME_WALLET_ADDRESS
```
For example, if your address is `7cvkjYAkUYs4W8XcXsca7cBrEGFeSUjeZmKoNBvEwyri`,
then enter the following command to view the balance:
```bash
solana balance 7cvkjYAkUYs4W8XcXsca7cBrEGFeSUjeZmKoNBvEwyri
```
You can also view the balance of any account address on the Accounts tab in the
[Explorer](https://explorer.solana.com/accounts)
and paste the address in the box to view the balance in you web browser.
Note: Any address with a balance of 0 SOL, such as a newly created one on your
Ledger, will show as "Not Found" in the explorer. Empty accounts and non-existent
accounts are treated the same in Solana. This will change when your account
address has some SOL in it.
### Send SOL from a Ledger Nano S
To send some tokens from an address controlled by your Nano S device, you will
need to use the device to sign a transaction, using the same keypair URL you
used to derive the address. To do this, make sure your Nano S is plugged in,
unlocked with the PIN, Ledger Live is not running, and the Solana App is open
on the device, showing "Application is Ready".
The `solana transfer` command is used to specify to which address to send tokens,
how many tokens to send, and uses the `--keypair` argument to specify which
keypair is sending the tokens, which will sign the transaction, and the balance
from the associated address will decrease.
```bash
solana transfer RECIPIENT_ADDRESS AMOUNT --keypair KEYPAIR_URL_OF_SENDER
```
Below is a full example. First, an address is viewed at a certain keypair URL.
Second, the balance of tht address is checked. Lastly, a transfer transaction
is entered to send `1` SOL to the recipient address `7cvkjYAkUYs4W8XcXsca7cBrEGFeSUjeZmKoNBvEwyri`.
When you hit Enter for a transfer command, you will be prompted to approve the
transaction details on your Ledger device. On the device, use the right and
left buttons to review the transaction details. If they look correct, click
both buttons on the "Approve" screen, otherwise push both buttons on the "Reject"
screen.
```bash
~$ solana-keygen pubkey usb://ledger?key=42
CjeqzArkZt6xwdnZ9NZSf8D1CNJN1rjeFiyd8q7iLWAV
~$ solana balance CjeqzArkZt6xwdnZ9NZSf8D1CNJN1rjeFiyd8q7iLWAV
1.000005 SOL
~$ solana transfer 7cvkjYAkUYs4W8XcXsca7cBrEGFeSUjeZmKoNBvEwyri 1 --keypair usb://ledger?key=42
Waiting for your approval on Ledger hardware wallet usb://ledger/2JT2Xvy6T8hSmT8g6WdeDbHUgoeGdj6bE2VueCZUJmyN
✅ Approved
Signature: kemu9jDEuPirKNRKiHan7ycybYsZp7pFefAdvWZRq5VRHCLgXTXaFVw3pfh87MQcWX4kQY4TjSBmESrwMApom1V
```
After approving the transaction on your device, the program will display the
transaction signature, and wait for the maximum number of confirmations (32)
before returning. This only takes a few seconds, and then the transaction is
finalized on the Solana network. You can view details of this or any other
transaction by going to the Transaction tab in the
[Explorer](https://explorer.solana.com/transactions)
and paste in the transaction signature.
## Advanced Operations
### 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.
Use the output from the `resolve-signer` command anywhere a `solana` command
expects a `<KEYPAIR>` entry to use that resolved path as the signer for that
part of the given transaction.
### Install the Solana Beta App
You're invited to help us test the latest pre-release version of our Ledger app
on one of the public testnets.
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.
**WARNING:** Installing an unsigned Ledger app reduces the security of your
Ledger device.
If your client is compromised, an attacker will be able to trick you into
signing arbitrary transactions with arbitrary derivation paths.
Only use this installation method if you understand
the security implications. We strongly recommend that you use a separate
Ledger device, with no other wallets/apps sharing the same seed phrase.
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.1/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
#### Installing the Solana Beta App returns an error
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
## 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
```
## Support
Check out our [Wallet Support Page](../support.md)
for ways to get help.
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>`.

4
docs/src/wallet-guide/ledger-live.md
View File

@@ -13,7 +13,7 @@ Integration with Ledger Live to use Solana wallet accounts on Ledger Live
will be available in the future.**
Users may [use a Ledger Nano S with the Solana command
line tools](../hardware-wallets/ledger.md).
line tools](hardware-wallets/ledger.md).
## Set up a Ledger Nano S
@@ -70,7 +70,7 @@ of the Solana App, please upgrade to version v0.2.2 by following these steps.
- To interact with your Ledger wallet on our live network, please see our
instructions on how to
[use a Ledger Nano S with the Solana command line tools](../hardware-wallets/ledger.md).
[use a Ledger Nano S with the Solana command line tools](hardware-wallets/ledger.md).
## Support

169
docs/src/wallet-guide/paper-wallet.md Normal file
View File

@@ -0,0 +1,169 @@
---
title: Paper Wallet
---
This document describes how to create and use a paper wallet with the Solana CLI
tools.
> We do not intend to advise on how to _securely_ create or manage paper wallets. Please research the security concerns carefully.
## Overview
Solana provides a key generation tool to derive keys from BIP39 compliant seed
phrases. Solana CLI commands for running a validator and staking tokens all
support keypair input via seed phrases.
To learn more about the BIP39 standard, visit the Bitcoin BIPs Github repository
[here](https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki).
## Paper Wallet Usage
Solana commands can be run without ever saving a keypair to disk on a machine.
If avoiding writing a private key to disk is a security concern of yours, you've
come to the right place.
> Even using this secure input method, it's still possible that a private key gets written to disk by unencrypted memory swaps. It is the user's responsibility to protect against this scenario.
## Before You Begin
- [Install the Solana command-line tools](../cli/install-solana-cli-tools.md)
### Check your installation
Check that `solana-keygen` is installed correctly by running:
```bash
solana-keygen --version
```
## Creating a Paper Wallet
Using the `solana-keygen` tool, it is possible to generate new seed phrases as
well as derive a keypair from an existing seed phrase and (optional) passphrase.
The seed phrase and passphrase can be used together as a paper wallet. As long
as you keep your seed phrase and passphrase stored safely, you can use them to
access your account.
> For more information about how seed phrases work, review this [Bitcoin Wiki page](https://en.bitcoin.it/wiki/Seed_phrase).
### Seed Phrase Generation
Generating a new keypair can be done using the `solana-keygen new` command. The
command will generate a random seed phrase, ask you to enter an optional
passphrase, and then will display the derived public key and the generated seed
phrase for your paper wallet.
After copying down your seed phrase, you can use the
[public key derivation](#public-key-derivation) instructions to verify that you
have not made any errors.
```bash
solana-keygen new --no-outfile
```
> If the `--no-outfile` flag is **omitted**, the default behavior is to write the keypair to `~/.config/solana/id.json`, resulting in a [file system wallet](file-system-wallet.md)
The output of this command will display a line like this:
```bash
pubkey: 9ZNTfG4NyQgxy2SWjSiQoUyBPEvXT2xo7fKc5hPYYJ7b
```
The value shown after `pubkey:` is your _wallet address_.
**Note:** In working with paper wallets and file system wallets, the terms "pubkey"
and "wallet address" are sometimes used interchangably.
> For added security, increase the seed phrase word count using the `--word-count` argument
For full usage details run:
```bash
solana-keygen new --help
```
### Public Key Derivation
Public keys can be derived from a seed phrase and a passphrase if you choose to
use one. This is useful for using an offline-generated seed phrase to
derive a valid public key. The `solana-keygen pubkey` command will walk you
through entering your seed phrase and a passphrase if you chose to use one.
```bash
solana-keygen pubkey ASK
```
> Note that you could potentially use different passphrases for the same seed phrase. Each unique passphrase will yield a different keypair.
The `solana-keygen` tool uses the same BIP39 standard English word list as it
does to generate seed phrases. If your seed phrase was generated with another
tool that uses a different word list, you can still use `solana-keygen`, but
will need to pass the `--skip-seed-phrase-validation` argument and forego this
validation.
```bash
solana-keygen pubkey ASK --skip-seed-phrase-validation
```
After entering your seed phrase with `solana-keygen pubkey ASK` the console
will display a string of base-58 character. This is the _wallet address_
associated with your seed phrase.
> Copy the derived address to a USB stick for easy usage on networked computers
> A common next step is to [check the balance](#checking-account-balance) of the account associated with a public key
For full usage details run:
```bash
solana-keygen pubkey --help
```
## Verifying the Keypair
To verify you control the private key of a paper wallet address, use
`solana-keygen verify`:
```bash
solana-keygen verify <PUBKEY> ASK
```
where `<PUBKEY>` is replaced with the wallet address 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.
## Checking Account Balance
All that is needed to check an account balance is the public key of an account.
To retrieve public keys securely from a paper wallet, follow the
[Public Key Derivation](#public-key-derivation) instructions on an
[air gapped computer](<https://en.wikipedia.org/wiki/Air_gap_(networking)>).
Public keys can then be typed manually or transferred via a USB stick to a
networked machine.
Next, configure the `solana` CLI tool to
[connect to a particular cluster](../cli/choose-a-cluster.md):
```bash
solana config set --url <CLUSTER URL> # (i.e. https://api.mainnet-beta.solana.com)
```
Finally, to check the balance, run the following command:
```bash
solana balance <PUBKEY>
```
## Creating Multiple Paper Wallet Addresses
You can create as many wallet addresses as you like. Simply re-run the
steps in [Seed Phrase Generation](#seed-phrase-generation) or
[Public Key Derivation](#public-key-derivation) to create a new address.
Multiple wallet addresses can be useful if you want to transfer tokens between
your own accounts for different purposes.
## Support
Check out our [Wallet Support Page](support.md) for ways to get help.

2
docs/src/wallet-guide/support.md
View File

@@ -4,7 +4,7 @@ title: Support / Troubleshooting
If you have questions or are having trouble setting up or using your wallet
of choice, please make sure you've read through all the relevant pages in our
[Wallet Guide](README.md). The Solana team is working hard to support new
[Wallet Guide](paper-wallet.md). The Solana team is working hard to support new
features on popular wallets, and we do our best to keep our documents up to date
with the latest available features.