blockworks-foundation
/
solana
mirror of https://github.com/blockworks-foundation/solana.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Add staking docs (#8988) 

automerge
This commit is contained in:
Greg Fitzgerald 2020-03-21 20:50:09 -06:00 committed by GitHub
parent 2592894958
commit 1f83c56e05
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
9 changed files with 190 additions and 79 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
docs/src/SUMMARY.md
View File

@ -10,6 +10,7 @@
* [Paper Wallet Usage](paper-wallet/usage.md)
* [Generate Keys](cli/generate-keys.md)
* [Send and Receive Tokens](cli/transfer-tokens.md)
* [Earn Staking Rewards](cli/delegate-stake.md)
* [Offline Signing](offline-signing/README.md)
* [Durable Transaction Nonces](offline-signing/durable-nonce.md)
* [Command-line Reference](cli/usage.md)

2
docs/src/cli/.usage.md.header
View File

@ -8,7 +8,7 @@ The [solana-cli crate](https://crates.io/crates/solana-cli) provides a command-l
```bash
// Command
$ solana address
$ solana-keygen pubkey
// Return
<PUBKEY>

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

@ -1,9 +1,9 @@
# Command-line Guide
In this section, we'll describe how to create a Solana *wallet*, how to send
In this section, we will describe how to create a Solana *wallet*, how to send
and receive tokens, and how to participate in the cluster by delegating stake.
To interact with a Solana cluster, we will use its command-line interface, also
known as the CLI. We use the command-line because it's the first place the
Solana core team deploys new functionality. The command-line interface isn't
known as the CLI. We use the command-line because it is the first place the
Solana core team deploys new functionality. The command-line interface is not
necessarily the easiest to use, but it provides the most direct, flexible, and
secure access to your Solana accounts.

10
docs/src/cli/choose-a-wallet.md
View File

@ -3,7 +3,7 @@
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
than others. Some are more secure than others. In this section, we will compare
and contrast different types of wallets and help you choose the wallet that
best fits your needs.
@ -16,8 +16,8 @@ file system. Each file in the directory holds a keypair.
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
many keys as you would 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
@ -72,8 +72,8 @@ To keep your hardware wallet tokens safe, we suggest:
## 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
Different people will have different needs, but if you are still unsure what
is 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.

162
docs/src/cli/delegate-stake.md Normal file
View File

@ -0,0 +1,162 @@
# Earn Staking Rewards
After you have [received SOL](transfer-tokens.md), you might consider putting
it to use by delegating *stake* to a validator. Stake is what we call tokens
in a *stake account*. Solana weights validator votes by the amount of stake
delegated to them, which gives those validators more influence in determining
then next valid block of transactions in the blockchain. Solana then generates
new SOL periodically to reward stakers and validators. You earn more rewards
the more stake you delegate.
## Create a Stake Account
To delegate stake, you will need to transfer some tokens into a stake account.
To create an account, you will need a keypair. Its public key will be used as
the stake account address. No need for a password or encryption here; this
keypair will be discarded right after creating the stake account.
```bash
solana-keygen new --no-passphrase -o stake-account.json
```
The output will contain the public key after the text `pubkey:`.
```text
============================================================================
pubkey: GKvqsuNcnwWqPzzuhLmGi4rzzh55FhJtGizkhHaEJqiV
============================================================================
```
Copy the public key and store it for safekeeping. You will need it any time you
want to perform an action on the stake account you create next.
Now, create a stake account:
```bash
solana create-stake-account --from=<KEYPAIR> stake-account.json <AMOUNT> --stake-authority=<KEYPAIR> --withdraw-authority=<KEYPAIR>
```
`<AMOUNT>` tokens are transferred from the account at `<KEYPAIR>` to a new
stake account at the public key of stake-account.json.
The stake-account.json file can now be discarded. To authorize additional
actions, you will use the `--stake-authority` or `withdraw-authority` keypair,
not stake-account.json.
### Set Stake and Withdraw Authorities
Staking commands look to keypairs to authorize certain stake account
operations. They use the stake authority to authorize stake delegation,
deactivating stake, splitting stake, and setting a new stake authority. They
use the withdraw authority to authorize withdrawing stake, and when setting
either a new stake or withdraw authority.
Stake and withdraw authorities can be set when creating an account via the
`--stake-authority` and `--withdraw-authority` options, or afterward with the
`solana stake-authorize` command. For example, to set a new stake authority,
run:
```bash
solana stake-authorize <STAKE_ACCOUNT_ADDRESS> --stake-authority=<KEYPAIR> --new-stake-authority=<PUBKEY>
```
This will use the existing stake authority `<KEYPAIR>` to authorize a new stake
authority `<PUBKEY>` on the stake account `<STAKE_ACCOUNT_ADDRESS>`.
### Advanced: Derive Stake Account Addresses
When you delegate stake, you delegate all tokens in the stake account to a
single validator. To delegate to multiple validators, you will need multiple
stake accounts. Creating a new keypair for each account and managing those
addresses can be cumbersome. Fortunately, you can derive stake addresses using
the `--seed` option:
```bash
solana create-stake-account --from=<KEYPAIR> <STAKE_ACCOUNT_KEYPAIR> --seed=<STRING> <AMOUNT> --stake-authority=<PUBKEY> --withdraw-authority=<PUBKEY>
```
`<STRING>` is an arbitrary string up to 32 bytes, but will typically be a
number corresponding to which derived account this is. The first account might
be "0", then "1", and so on. The public key of `<STAKE_ACCOUNT_KEYPAIR>` acts
as the base address. The command derives a new address from the base address
and seed string. To see what stake address the command will derive, use `solana
create-address-with-seed`:
```bash
solana create-address-with-seed --from=<PUBKEY> <SEED_STRING> STAKE
```
`<PUBKEY>` is the public key of the `<STAKE_ACCOUNT_KEYPAIR>` passed to
`solana create-stake-account`.
The command will output a derived address, which can be used for the
`<STAKE_ACCOUNT_ADDRESS>` argument in staking operations.
## Delegate Stake
To delegate your stake to a validator, you will need its vote account address.
Find it by querying the cluster for the list of all validators and their vote
accounts with the `solana validators` command:
```bash
solana validators
```
The first column of each row contains the validator's identity and the second
is the vote account address. Choose a validator and use its vote account
address in `solana delegate-stake`:
```bash
solana delegate-stake --stake-authority=<KEYPAIR> <STAKE_ACCOUNT_ADDRESS> <VOTE_ACCOUNT_ADDRESS>
```
`<KEYPAIR>` authorizes the operation on the account with address
`<STAKE_ACCOUNT_ADDRESS>`. The stake is delegated to the vote account with
address `<VOTE_ACCOUNT_ADDRESS>`.
## Deactivate Stake
Once delegated, you can undelegate stake with the `solana deactivate-stake`
command:
```bash
solana deactivate-stake --stake-authority=<KEYPAIR> <STAKE_ACCOUNT_ADDRESS>
```
`<KEYPAIR>` authorizes the operation on the account with address
`<STAKE_ACCOUNT_ADDRESS>`.
Note that stake takes several epochs to "cool down". Attempts to delegate stake
in the cool down period will fail.
## Withdraw Stake
Transfer tokens out of a stake account with the `solana withdraw-stake` command:
```bash
solana withdraw-stake --withdraw-authority=<KEYPAIR> <STAKE_ACCOUNT_ADDRESS> <RECIPIENT_ADDRESS> <AMOUNT>
```
`<STAKE_ACCOUNT_ADDRESS>` is the existing stake account, `<KEYPAIR>` is the
withdraw authority, and `<AMOUNT>` is the number of tokens to transfer to
`<RECIPIENT_ADDRESS>`.
## Split Stake
You may want to delegate stake to additional validators while your existing
stake is not eligible for withdrawal. It might not be eligible because it is
currently staked, cooling down, or locked up. To transfer tokens from an
existing stake account to a new one, use the `solana split-stake` command:
```bash
solana split-stake --stake-authority=<KEYPAIR> <STAKE_ACCOUNT_ADDRESS> <NEW_STAKE_ACCOUNT_KEYPAIR> <AMOUNT>
```
`<STAKE_ACCOUNT_ADDRESS>` is the existing stake account, `<KEYPAIR>` is the
stake authority, `<NEW_STAKE_ACCOUNT_KEYPAIR>` is the keypair for the new account,
and `<AMOUNT>` is the number of tokens to transfer to the new account.
To split a stake account into a derived account address, use the `--seed`
option. See
[Derive Stake Account Addresses](#advanced-derive-stake-account-addresses)
for details.

4
docs/src/cli/generate-keys.md
View File

@ -1,7 +1,7 @@
# 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
In this section, we will generate a keypair, query it for its public key,
and verify you control its private key. Before you begin, you will need
to:
* [Install the Solana Tool Suite](../install-solana.md)

12
docs/src/cli/transfer-tokens.md
View File

@ -6,7 +6,7 @@ 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
tokens, you will 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.
@ -39,7 +39,7 @@ 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`.
you chose a hardware wallet, use your keypair URL, such as `usb://ledger?key=0`.
### Test-drive your Public Keys
@ -67,7 +67,7 @@ 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
First, we will need a public key to receive our tokens. Create a second
keypair and record its pubkey:
```bash
@ -75,7 +75,7 @@ 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.
public key. We will use it in the next step.
```text
============================================================================
@ -84,7 +84,7 @@ pubkey: GKvqsuNcnwWqPzzuhLmGi4rzzh55FhJtGizkhHaEJqiV
```
```bash
solana transfer --keypair=<SENDER_KEYPAIR> <RECIPIENT_ACCOUNT_ADDRESS> 5 --url http://devnet.solana.com
solana transfer --from=<SENDER_KEYPAIR> <RECIPIENT_ACCOUNT_ADDRESS> 5 --url http://devnet.solana.com
```
where you replace `<SENDER_KEYPAIR>` with the path to a keypair in your wallet,
@ -107,7 +107,7 @@ tokens to transfer. Once you have that collected, you can transfer tokens
with the `solana transfer` command:
```bash
solana transfer --keypair=<SENDER_KEYPAIR> <RECIPIENT_ACCOUNT_ADDRESS> <AMOUNT>
solana transfer --from=<SENDER_KEYPAIR> <RECIPIENT_ACCOUNT_ADDRESS> <AMOUNT>
```
Confirm the updated balances with `solana balance`:

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

@ -52,7 +52,7 @@ usb://ledger/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*.
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.

70
docs/src/remote-wallet/ledger.md
View File

@ -72,81 +72,29 @@ To fix, check the following:
3. On your computer, run:
```text
solana address --keypair usb://ledger
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 key*. When you have multiple Nano S devices connected to the same
*wallet ID*. When you have multiple Nano S devices connected to the same
computer, you can use your wallet key to specify which Ledger hardware wallet
you want to use. Run the same command again, but this time, with its fully
qualified URL:
```text
solana address --keypair usb://ledger/<WALLET_KEY>
solana-keygen pubkey usb://ledger/<WALLET_ID>
```
Confirm it prints the same key as when you entered just `usb://ledger`.
where you replace `<WALLET_ID>` with the output of the first command.
Confirm it prints the same wallet ID as before.
To learn more about USB URLs, see
To learn more about keypair URLs, see
[Specify A Hardware Wallet Key](index.md#specify-a-hardware-wallet-key)
### Set CLI Configuration
Configure the `solana` CLI tool to connect to a particular cluster:
```bash
solana config set --url <CLUSTER_URL> # (i.e. http://devnet.solana.com)
```
If you want to set a Ledger key as the default signer for CLI commands, use the
[CLI configuration settings](../cli/usage.md#solana-config):
```text
solana config set --keypair <LEDGER_URL>
```
For example:
```text
solana config set --keypair usb://ledger?key=0
```
### Check Account Balance
```text
solana balance --keypair usb://ledger?key=12345
```
Or with the default signer:
```text
solana balance
```
### Send SOL via Ledger Device
```text
solana transfer <RECIPIENT> <AMOUNT> --from <LEDGER_URL>
```
Or with the default signer:
```text
solana transfer <RECIPIENT> <AMOUNT>
```
### Delegate Stake with Ledger Device
```text
solana delegate-stake <STAKE_ACCOUNT> <VOTER_ID> --keypair <LEDGER_URL>
```
Or with the default signer:
```text
solana delegate-stake <STAKE_ACCOUNT> <VOTER_ID>
```
Read more about [sending and receiving tokens](../transfer-tokens.md) and
[delegating stake](../delegate-stake.md). You can use your Ledger keypair URL
anywhere you see an option or argument that accepts a `<KEYPAIR>`.
## Support