Add staking guide to docs (#10609)

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)

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