diff --git a/.gitbook.yaml b/.gitbook.yaml index 4a9bcde4fc..f9bb600960 100644 --- a/.gitbook.yaml +++ b/.gitbook.yaml @@ -15,4 +15,4 @@ redirects: wallet/cli-wallets/remote-wallet: ./hardware-wallets/README.md wallet/cli-wallets/remote-wallet/ledger: ./hardware-wallets/ledger.md wallet/cli-wallets/file-system-wallet: ./file-system-wallet/README.md - wallet/support: ./wallet-guide/support.md + wallet/support: ./wallet-guide/support.md \ No newline at end of file diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md index 05aa7a3f87..350cde7950 100644 --- a/docs/src/SUMMARY.md +++ b/docs/src/SUMMARY.md @@ -12,6 +12,8 @@ * [Ledger Hardware Wallet](hardware-wallets/ledger.md) * [File System Wallet](file-system-wallet/README.md) * [Support / Troubleshooting](wallet-guide/support.md) +* [Staking Guide](staking/README.md) + * [Stake Account Details](staking/stake-accounts.md) * [Command Line Guide](cli/README.md) * [Install the Solana Command Line Tool Suite](cli/install-solana-cli-tools.md) * [Command Line Conventions](cli/conventions.md) diff --git a/docs/src/cli/delegate-stake.md b/docs/src/cli/delegate-stake.md index 9c0d11e1f9..40cea498ab 100644 --- a/docs/src/cli/delegate-stake.md +++ b/docs/src/cli/delegate-stake.md @@ -1,19 +1,15 @@ # Delegate Stake - -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. +This page describes the workflow and commands needed to create and manage stake +accounts, and to delegate your stake accounts to a validator using the Solana +command-line tools. The [stake accounts](../staking/stake-accounts.md) +document provides an overview of stake account features and concepts. ## 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. +the [stake account address](../staking/stake-accounts.md#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 @@ -22,9 +18,7 @@ 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 @@ -42,7 +36,7 @@ solana create-stake-account --from stake-account.json \ 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, +actions, you will use the `--stake-authority` or `--withdraw-authority` keypair, not stake-account.json. View the new stake account with the `solana stake-account` command: @@ -61,14 +55,8 @@ Withdraw Authority: EXU95vqs93yPeCeAU7mPPu6HbRUmTFPEiGug9oCdvQ5F ``` ### 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 and withdraw authorities](../staking/stake-accounts.md#understanding-account-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: diff --git a/docs/src/staking/README.md b/docs/src/staking/README.md new file mode 100644 index 0000000000..91fcb1950d --- /dev/null +++ b/docs/src/staking/README.md @@ -0,0 +1,111 @@ +*Note before reading: All references to increases in values are in absolute +terms with regards to balance of SOL. +This document makes no suggestion as to the monetary value of SOL at any time.* + +# Staking on Solana + +Staking your SOL tokens on Solana is the best way you can help secure the world's +highest-performing blockchain network, and +[earn rewards](../implemented-proposals/staking-rewards.md) for doing so! +Inflation and network rewards are *NOT* presently implemented on Solana's +Mainnet Beta network, but may be enabled in the future. + +Solana is a Proof-of-Stake (PoS) network with delegations, which means that +anyone who holds SOL tokens can choose to delegate some of their SOL to one or +more validators, who process transactions and run the network. + +Delegating stake is a shared-risk shared-reward financial model that may provide +returns to holders of tokens delegated for a long period. +This is achieved by aligning the financial incentives of the token-holders +(delegators) and the validators to whom they delegate. + +The more stake a validator has delegated to them, the more often this validator +is chosen to write new transactions to the ledger. The more transactions +the validator writes, the more rewards they and their delegators earn. +Validators who configure their systems to be able to process more transactions +at a time not only earn proportionally more rewards for doing so, they also +keep the network running as fast and as smoothly as possible. + +Validators incur costs by running and maintaining their systems, and this is +passed on to delegators in the form of a fee collected as a percentage of +rewards earned. This fee is known as a *commission*. As validators earn more +rewards the more stake is delegated to them, they may compete with one another +to offer the lowest commission for their services, in order to attract more +delegated stake. + +There is a risk of loss of tokens when staking, through a process known as +*slashing*. Slashing is *NOT* presently enabled on Solana's Mainnet Beta +network, but may be implemented in the future. Slashing involves the automatic +removal and destruction of a portion of a validator's delegated stake in +response to intentional malicious behavior, such as creating invalid +transactions or censoring certain types of transactions or network participants. +If a validator is slashed, all token holders who have delegated stake to that +validator will lose a portion of their delegation. While this means an immediate +loss for the token holder, it also is a loss of future rewards for the validator +due to their reduced total delegation. + +It is the goal of the network rewards and slashing to align both validators' +and token holders' financial incentives, which in turn help keeps the network +secure, robust and performing at its best. + +*Note: Network rewards for stakers and validators are not presently enabled on +Mainnet Beta.* + +*Note: Slashing is not implemented on Mainnet Beta at this time.* + + +## How do I stake my SOL tokens? +In order to stake tokens on Solana, you first will need to transfer some SOL +into a wallet that supports staking, then follow the steps or instructions +provided by the wallet to create a stake account and delegate your stake. +Different wallets will vary slightly in their process for this but the general +description is below. + +#### Supported Wallets +Currently, staking operation are only supported by wallets that can interact +with the Solana command line tools, including Ledger Nano S and paper wallet. + +[Staking commands using the Solana Command Line Tools](../cli/delegate-stake.md) + +#### Create a Stake Account +A stake account is a different type of account from a wallet address +that is used to simply send and receive SOL tokens to other addresses. If you +have received SOL in a wallet address you control, you can use some of +these tokens to create and fund a new stake account, which will have a different +address than the wallet you used to create it. +Depending on which wallet you are using the steps to create a stake account +may vary slightly. Not all wallets support stake accounts, see +[Supported Wallets](#supported-wallets). + +#### Select a Validator +After a stake account is created, you will likely want to delegate the SOL +to a validator node. Below are a few places where you can get information about +the validators who are currently participating in running the network. +The Solana Labs team and the Solana Foundation do not recommend any particular +validator. + +The Mainnet Beta validators introduce themselves and their services on this +Solana Forum thread: + - https://forums.solana.com/t/validator-information-thread + +The site solanabeach.io is built and maintained by one of our validators, +Staking Facilities. It provides a some high-level graphical information about +the network as a whole, as well as a list of each validator and some recent +performance statistics about each one. + - https://solanabeach.io + +To view block production statistics, use the Solana command-line tools: + - `solana validators` + - `solana block-production` + +The Solana team does not make recommendations on how to interpret this +information. Potential delegators should do their own due diligence. + +#### Delegate your Stake +Once you have decided to which validator or validators you will delegate, use +a supported wallet to delegate your stake account to the validator's vote +account address. + +## Stake Account Details +For more information about the operations and permissions associated with a +stake account, please see [Stake Accounts](stake-accounts.md) diff --git a/docs/src/staking/stake-accounts.md b/docs/src/staking/stake-accounts.md new file mode 100644 index 0000000000..e7f4dc066a --- /dev/null +++ b/docs/src/staking/stake-accounts.md @@ -0,0 +1,116 @@ +## Stake Account Structure +A stake account on Solana can be used to delegate tokens to validators on +the network to potentially earn rewards for the owner of the stake account. +Stake accounts are created and managed differently than a traditional wallet +address, known as a *system account*. A system account is only able to send and +receive SOL from other accounts on the network, whereas a stake account supports +more complex operations needed to manage a delegation of tokens. + +Stake accounts on Solana also work differently than those of other Proof-of-Stake +blockchain networks that you may be familiar with. This document describes the +high-level structure and functions of a Solana stake account. + +#### Account Address +Each stake account has a unique address which can be used to look up the account +information in the command line or in any network explorer tools. However, +unlike a wallet address in which the holder of the address's keypair controls +the wallet, the keypair associated with a stake account address does not necessarily have +any control over the account. In fact, a keypair or private key may not even +exist for a stake account's address. + +The only time a stake account's address has a keypair file is when [creating +a stake account using the command line tools](../cli/delegate-stake.md#create-a-stake-account), +a new keypair file is created first only to ensure that the stake account's +address is new and unique. + +#### Understanding Account Authorities +Certain types of accounts may have one or more *signing authorities* +associated with a given account. An account authority is used to sign certain +transactions for the account it controls. This is different from +some other blockchain networks where the holder of the keypair associated with +the account's address controls all of the account's activity. + +Each stake account has two signing authorities specified by their respective address, +each of which is authorized to perform certain operations on the stake account. + +The *stake authority* is used to sign transactions for the following operations: + - Delegating stake + - Deactivating the stake delegation + - Splitting the stake account, creating a new stake account with a portion of the + funds in the first account + - Merging two undelegated stake accounts into one + - Setting a new stake authority + +The *withdraw authority* signs transactions for the following: + - Withdrawing un-delegated stake into a wallet address + - Setting a new withdraw authority + - Setting a new stake authority + +The stake authority and withdraw authority are set when the stake account is +created, and they can be changed to authorize a new signing address at any time. +The stake and withdraw authority can be the same address or two different +addresses. + +The withdraw authority keypair holds more control over the account as it is +needed to liquidate the tokens in the stake account, and can be used to reset +the stake authority if the stake authority keypair becomes lost or compromised. + +Securing the withdraw authority against loss or theft is of utmost importance +when managing a stake account. + +#### Multiple Delegations +Each stake account may only be used to delegate to one validator at a time. +All of the tokens in the account are either delegated or un-delegated, or in the +process of becoming delegated or un-delegated. To delegate a fraction of your +tokens to a validator, or to delegate to multiple validators, you must create +multiple stake accounts. + +This can be accomplished by creating multiple stake accounts from a wallet +address containing some tokens, or by creating a single large stake account +and using the stake authority to split the account into multiple accounts +with token balances of your choosing. + +The same stake and withdraw authorities can be assigned to multiple +stake accounts. + +Two stake accounts that are not delegated and that have the same authorities +and lockup can be merged into a single resulting stake account. + +#### Delegation Warmup and Cooldown +When a stake account is delegated, or a delegation is deactivated, the operation +does not take effect immediately. + +A delegation or deactivation takes several [epochs](../terminology.md#epoch) +to complete, with a fraction of the delegation becoming active or inactive at +each epoch boundary after the transaction containing the instructions has been +submitted to the cluster. + +There is also a limit on how much total stake can become delegated or +deactivated in a single epoch, to prevent large sudden changes in stake across +the network as a whole. Since warmup and cooldown are dependent on the behavior +of other network participants, their exact duration is difficult to predict. +Details on the warmup and cooldown timing can be found +[here](../cluster/stake-delegation-and-rewards.md#stake-warmup-cooldown-withdrawal). + +#### Lockups +Stake accounts can have a lockup which prevents the tokens they hold from being +withdrawn before a particular date or epoch has been +reached. While locked up, the stake account can still be delegated, un-delegated, +or split, and its stake and withdraw authorities can be changed as normal. Only +withdrawal into a wallet address is not allowed. + +A lockup can only be added when a stake account is first created, but it can be +modified later, by the *lockup authority* or *custodian*, the address of which +is also set when the account is created. + +#### Destroying a Stake Account +Like other types of accounts on the Solana network, a stake account that has a +balance of 0 SOL is no longer tracked. If a stake account is not delegated +and all of the tokens it contains are withdrawn to a wallet address, the account +at that address is effectively destroyed, and will need to be manually +re-created for the address to be used again. + +#### Viewing Stake Accounts +Stake account details can be viewed on the Solana Explorer by copying and pasting +an account address into the search bar. + - http://explorer.solana.com/accounts diff --git a/docs/src/wallet-guide/apps.md b/docs/src/wallet-guide/apps.md index 6ce7758b10..bc1dda619e 100644 --- a/docs/src/wallet-guide/apps.md +++ b/docs/src/wallet-guide/apps.md @@ -4,9 +4,12 @@ experience for most people who are new or experienced with using crypto wallets. ## Trust Wallet [Trust Wallet](https://trustwallet.com/) is an app for iOS and Android. This is -currently the easiest and fastest way to get set up with a new wallet on Solana. +currently the easiest and fastest way to get set up with a new wallet to send +and receive SOL tokens on the Solana network. The app is free and getting your wallet set up only takes a few minutes. +*Note: Trust Wallet does not support stake accounts or staking operations* + ### Trust Wallet Security Tokens held in Trust Wallet are only as secure as the device on which the app is diff --git a/docs/src/wallet-guide/trust-wallet.md b/docs/src/wallet-guide/trust-wallet.md index 5d8e466bda..fd3455de3e 100644 --- a/docs/src/wallet-guide/trust-wallet.md +++ b/docs/src/wallet-guide/trust-wallet.md @@ -1,6 +1,7 @@ # Trust Wallet Trust Wallet is an app for your smartphone or tablet and is the fastest and -simplest way for most users to get started with a Solana wallet. +simplest way for most users to get started with a Solana wallet to send and +receive tokens. ## Install Trust Wallet