diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md index 7b5d525175..2a5538303d 100644 --- a/docs/src/SUMMARY.md +++ b/docs/src/SUMMARY.md @@ -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) diff --git a/docs/src/cli/.usage.md.header b/docs/src/cli/.usage.md.header index f9e23e4698..5e1267d613 100644 --- a/docs/src/cli/.usage.md.header +++ b/docs/src/cli/.usage.md.header @@ -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 diff --git a/docs/src/cli/README.md b/docs/src/cli/README.md index 5b1261b9c7..7985c13d44 100644 --- a/docs/src/cli/README.md +++ b/docs/src/cli/README.md @@ -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. diff --git a/docs/src/cli/choose-a-wallet.md b/docs/src/cli/choose-a-wallet.md index 7681268dc9..581f38454a 100644 --- a/docs/src/cli/choose-a-wallet.md +++ b/docs/src/cli/choose-a-wallet.md @@ -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. diff --git a/docs/src/cli/delegate-stake.md b/docs/src/cli/delegate-stake.md new file mode 100644 index 0000000000..50d7d5b572 --- /dev/null +++ b/docs/src/cli/delegate-stake.md @@ -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= stake-account.json --stake-authority= --withdraw-authority= +``` + +`` tokens are transferred from the account at `` 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-authority= --new-stake-authority= +``` + +This will use the existing stake authority `` to authorize a new stake +authority `` on the stake account ``. + +### 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= --seed= --stake-authority= --withdraw-authority= +``` + +`` 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 `` 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= STAKE +``` + +`` is the public key of the `` passed to +`solana create-stake-account`. + +The command will output a derived address, which can be used for the +`` 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= +``` + +`` authorizes the operation on the account with address +``. The stake is delegated to the vote account with +address ``. + +## Deactivate Stake + +Once delegated, you can undelegate stake with the `solana deactivate-stake` +command: + +```bash +solana deactivate-stake --stake-authority= +``` + +`` authorizes the operation on the account with 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= +``` + +`` is the existing stake account, `` is the +withdraw authority, and `` is the number of tokens to transfer to +``. + +## 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= +``` + +`` is the existing stake account, `` is the +stake authority, `` is the keypair for the new account, +and `` 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. diff --git a/docs/src/cli/generate-keys.md b/docs/src/cli/generate-keys.md index 5f9b0bfffa..fab39e6938 100644 --- a/docs/src/cli/generate-keys.md +++ b/docs/src/cli/generate-keys.md @@ -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) diff --git a/docs/src/cli/transfer-tokens.md b/docs/src/cli/transfer-tokens.md index cb4de8dcea..eb86893d06 100644 --- a/docs/src/cli/transfer-tokens.md +++ b/docs/src/cli/transfer-tokens.md @@ -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 ``, 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= 5 --url http://devnet.solana.com +solana transfer --from= 5 --url http://devnet.solana.com ``` where you replace `` 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= +solana transfer --from= ``` Confirm the updated balances with `solana balance`: diff --git a/docs/src/remote-wallet/README.md b/docs/src/remote-wallet/README.md index 017a786ad5..3c661a0f27 100644 --- a/docs/src/remote-wallet/README.md +++ b/docs/src/remote-wallet/README.md @@ -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. diff --git a/docs/src/remote-wallet/ledger.md b/docs/src/remote-wallet/ledger.md index a34066de70..a946a863ce 100644 --- a/docs/src/remote-wallet/ledger.md +++ b/docs/src/remote-wallet/ledger.md @@ -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/ +solana-keygen pubkey usb://ledger/ ``` -Confirm it prints the same key as when you entered just `usb://ledger`. +where you replace `` 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 # (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 -``` - -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 --from -``` - -Or with the default signer: - -```text -solana transfer -``` - -### Delegate Stake with Ledger Device - -```text -solana delegate-stake --keypair -``` - -Or with the default signer: - -```text -solana delegate-stake -``` +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 ``. ## Support