solana-docs 0.0.0

package/src/running-validator/vote-accounts.md

@@ -0,0 +1,219 @@
+---
+title: Vote Account Management
+---
+
+This page describes how to set up an on-chain _vote account_. Creating a vote
+account is needed if you plan to run a validator node on Solana.
+
+## Create a Vote Account
+
+A vote account can be created with the
+[create-vote-account](../cli/usage.md#solana-create-vote-account) command.
+The vote account can be configured when first created or after the validator is
+running. All aspects of the vote account can be changed except for the
+[vote account address](#vote-account-address), which is fixed for the lifetime
+of the account.
+
+### Configure an Existing Vote Account
+
+- To change the [validator identity](#validator-identity), use
+  [vote-update-validator](../cli/usage.md#solana-vote-update-validator).
+- To change the [vote authority](#vote-authority), use
+  [vote-authorize-voter-checked](../cli/usage.md#solana-vote-authorize-voter-checked).
+- To change the [authorized withdrawer](#authorized-withdrawer), use
+  [vote-authorize-withdrawer-checked](../cli/usage.md#solana-vote-authorize-withdrawer-checked).
+- To change the [commission](#commission), use
+  [vote-update-commission](../cli/usage.md#solana-vote-update-commission).
+
+## Vote Account Structure
+
+### Vote Account Address
+
+A vote account is created at an address that is either the public key of a
+keypair file, or at a derived address based on a keypair file's public key and
+a seed string.
+
+The address of a vote account is never needed to sign any transactions,
+but is just used to look up the account information.
+
+When someone wants to [delegate tokens in a stake account](../staking.md),
+the delegation command is pointed at the vote account address of the validator
+to whom the token-holder wants to delegate.
+
+### Validator Identity
+
+The _validator identity_ is a system account that is used to pay for all the
+vote transaction fees submitted to the vote account.
+Because the validator is expected to vote on most valid blocks it receives,
+the validator identity account is frequently
+(potentially multiple times per second) signing transactions and
+paying fees. For this reason the validator identity keypair must be
+stored as a "hot wallet" in a keypair file on the same system the validator
+process is running.
+
+Because a hot wallet is generally less secure than an offline or "cold" wallet,
+the validator operator may choose to store only enough SOL on the identity
+account to cover voting fees for a limited amount of time, such as a few weeks
+or months. The validator identity account could be periodically topped off
+from a more secure wallet.
+
+This practice can reduce the risk of loss of funds if the validator node's
+disk or file system becomes compromised or corrupted.
+
+The validator identity is required to be provided when a vote account is created.
+The validator identity can also be changed after an account is created by using
+the [vote-update-validator](../cli/usage.md#solana-vote-update-validator) command.
+
+### Vote Authority
+
+The _vote authority_ keypair is used to sign each vote transaction the validator
+node wants to submit to the cluster. This doesn't necessarily have to be unique
+from the validator identity, as you will see later in this document. Because
+the vote authority, like the validator identity, is signing transactions
+frequently, this also must be a hot keypair on the same file system as the
+validator process.
+
+The vote authority can be set to the same address as the validator identity.
+If the validator identity is also the vote authority, only one
+signature per vote transaction is needed in order to both sign the vote and pay
+the transaction fee. Because transaction fees on Solana are assessed
+per-signature, having one signer instead of two will result in half the transaction
+fee paid compared to setting the vote authority and validator identity to two
+different accounts.
+
+The vote authority can be set when the vote account is created. If it is not
+provided, the default behavior is to assign it the same as the validator identity.
+The vote authority can be changed later with the
+[vote-authorize-voter-checked](../cli/usage.md#solana-vote-authorize-voter-checked) command.
+
+The vote authority can be changed at most once per epoch. If the authority is
+changed with [vote-authorize-voter-checked](../cli/usage.md#solana-vote-authorize-voter-checked),
+this will not take effect until the beginning of the next epoch.
+To support a smooth transition of the vote signing,
+`solana-validator` allows the `--authorized-voter` argument to be specified
+multiple times. This allows the validator process to keep voting successfully
+when the network reaches an epoch boundary at which the validator's vote
+authority account changes.
+
+### Authorized Withdrawer
+
+The _authorized withdrawer_ keypair is used to withdraw funds from a vote account
+using the [withdraw-from-vote-account](../cli/usage.md#solana-withdraw-from-vote-account)
+command. Any network rewards a validator earns are deposited into the vote
+account and are only retrievable by signing with the authorized withdrawer keypair.
+
+The authorized withdrawer is also required to sign any transaction to change
+a vote account's [commission](#commission), and to change the validator
+identity on a vote account.
+
+Because theft of a authorized withdrawer keypair can give complete control over
+the operation of a validator to an attacker, is is advised to keep the withdraw
+authority keypair in an offline/cold wallet in a secure location.  The withdraw
+authority keypair is not needed during operation of a validator and should not
+stored on the validator itself.
+
+The authorized withdrawer must be set when the vote account is created.  It must
+not be set to a keypair that is the same as either the validator identity
+keypair or the vote authority keypair.
+
+The authorized withdrawer can be changed later with the
+[vote-authorize-withdrawer-checked](../cli/usage.md#solana-vote-authorize-withdrawer-checked)
+command.
+
+### Commission
+
+_Commission_ is the percent of network rewards earned by a validator that are
+deposited into the validator's vote account. The remainder of the rewards
+are distributed to all of the stake accounts delegated to that vote account,
+proportional to the active stake weight of each stake account.
+
+For example, if a vote account has a commission of 10%, for all rewards earned
+by that validator in a given epoch, 10% of these rewards will be deposited into
+the vote account in the first block of the following epoch. The remaining 90%
+will be deposited into delegated stake accounts as immediately active stake.
+
+A validator may choose to set a low commission to try to attract more stake
+delegations as a lower commission results in a larger percentage of rewards
+passed along to the delegator. As there are costs associated with setting up
+and operating a validator node, a validator would ideally set a high enough
+commission to at least cover their expenses.
+
+Commission can be set upon vote account creation with the `--commission` option.
+If it is not provided, it will default to 100%, which will result in all
+rewards deposited in the vote account, and none passed on to any delegated
+stake accounts.
+
+Commission can also be changed later with the
+[vote-update-commission](../cli/usage.md#solana-vote-update-commission) command.
+
+When setting the commission, only integer values in the set [0-100] are accepted.
+The integer represents the number of percentage points for the commission, so
+creating an account with `--commission 10` will set a 10% commission.
+
+## Key Rotation
+
+Rotating the vote account authority keys require special handling when dealing
+with a live validator.
+
+### Vote Account Validator Identity
+
+You will need access to the _authorized withdrawer_ keypair for the vote account to
+change the validator identity. The follow steps assume that
+`~/authorized_withdrawer.json` is that keypair.
+
+1. Create the new validator identity keypair, `solana-keygen new -o ~/new-validator-keypair.json`.
+2. Ensure that the new identity account has been funded, `solana transfer ~/new-validator-keypair.json 500`.
+3. Run `solana vote-update-validator ~/vote-account-keypair.json ~/new-validator-keypair.json ~/authorized_withdrawer.json`
+   to modify the validator identity in your vote account
+4. Restart your validator with the new identity keypair for the `--identity` argument
+
+**Additional steps are required if your validator has stake.**  The leader
+schedule is computed two epochs in advance. Therefore if your old validator
+identity was in the leader schedule, it will remain in the leader schedule for
+up to two epochs after the validator identity change. If extra steps are not
+taken your validator will produce no blocks until your new validator identity is
+added to the leader schedule.
+
+After your validator is restarted with the new identity keypair, per step 4,
+start a second non-voting validator on a different machine with the old identity keypair
+without providing the `--vote-account` argument.
+
+This temporary validator should be run for two full epochs. During this time it will:
+* Produce blocks for the remaining slots that are assigned to your old validator identity
+* Receive the transaction fees and rent rewards for your old validator identity
+
+It is safe to stop this temporary validator when your old validator identity is
+no longer listed in the `solana leader-schedule` output.
+
+### Vote Account Authorized Voter
+
+The _vote authority_ keypair may only be changed at epoch boundaries and
+requires some additional arguments to `solana-validator` for a seamless
+migration.
+
+1. Run `solana epoch-info`. If there is not much time remaining time in the
+   current epoch, consider waiting for the next epoch to allow your validator
+   plenty of time to restart and catch up.
+2. Create the new vote authority keypair, `solana-keygen new -o ~/new-vote-authority.json`.
+3. Determine the current _vote authority_ keypair by running `solana vote-account ~/vote-account-keypair.json`. It may be validator's
+   identity account (the default) or some other keypair. The following steps
+   assume that `~/validator-keypair.json` is that keypair.
+4. Run `solana vote-authorize-voter ~/vote-account-keypair.json ~/validator-keypair.json ~/new-vote-authority.json`.
+   The new vote authority is scheduled to become active starting at the next epoch.
+5. `solana-validator` now needs to be restarted with the old and new vote
+   authority keypairs, so that it can smoothly transition at the next epoch. Add
+   the two arguments on restart: `--authorized-voter ~/validator-keypair.json --authorized-voter ~/new-vote-authority.json`
+6. After the cluster reaches the next epoch, remove the
+   `--authorized-voter ~/validator-keypair.json` argument and restart
+   `solana-validator`, as the old vote authority keypair is no longer required.
+
+### Vote Account Authorized Withdrawer
+
+No special handling is required. Use the `solana vote-authorize-withdrawer` command as needed.
+
+## Close a Vote Account
+
+A vote account can be closed with the
+[close-vote-account](../cli/usage.md#solana-close-vote-account) command.
+Closing a vote account withdraws all remaining SOL funds to a supplied recipient address and renders it invalid as a vote account.
+It is not possible to close a vote account with active stake.

package/src/running-validator.md

@@ -0,0 +1,7 @@
+---
+title: Running a Validator
+---
+
+This section describes how to run a Solana validator node.
+
+There are several clusters available to connect to; see [choosing a Cluster](cli/choose-a-cluster.md) for an overview of each.

package/src/staking/stake-accounts.md

@@ -0,0 +1,141 @@
+---
+title: 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 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.
+
+#### Merging stake accounts
+
+Two stake accounts that have the same authorities and lockup can be merged into
+a single resulting stake account. A merge is possible between two stakes in the
+following states with no additional conditions:
+
+- two deactivated stakes
+- an inactive stake into an activating stake during its activation epoch
+
+For the following cases, the voter pubkey and vote credits observed must match:
+
+- two activated stakes
+- two activating accounts that share an activation epoch, during the activation epoch
+
+All other combinations of stake states will fail to merge, including all "transient"
+states, where a stake is activating or deactivating with a non-zero effective stake.
+
+#### 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](http://explorer.solana.com/accounts)
+by copying and pasting an account address into the search bar.

package/src/staking/stake-programming.md

@@ -0,0 +1,27 @@
+---
+title: Stake Programming
+---
+
+To maximize stake distribution, decentralization, and censorship resistance on
+the Solana network, staking can be performed programmatically. The team
+and community have developed several on-chain and off-chain programs to make
+stakes easier to manage.
+
+#### Stake-o-matic aka Auto-delegation Bots
+
+This off-chain program manages a large population of validators staked by a
+central authority. The Solana Foundation uses an auto-delegation bot to regularly delegate its
+stake to "non-delinquent" validators that meet specified performance requirements. More information can be found on the
+[official announcement](https://forums.solana.com/t/stake-o-matic-delegation-matching-program/790).
+
+#### Stake Pools
+
+This on-chain program pools together SOL to be staked by a manager, allowing SOL
+holders to stake and earn rewards without managing stakes.
+Users deposit SOL in exchange for SPL tokens (staking derivatives) that represent their ownership in the stake pool. The pool
+manager stakes deposited SOL according to their strategy, perhaps using a variant
+of an auto-delegation bot as described above. As stakes earn rewards, the pool and pool tokens
+grow proportionally in value. Finally, pool token holders can send SPL tokens
+back to the stake pool to redeem SOL, thereby participating in decentralization with much
+less work required. More information can be found at the
+[SPL stake pool documentation](https://spl.solana.com/stake-pool).

package/src/staking.md

@@ -0,0 +1,117 @@
+---
+title: Staking on Solana
+---
+
+_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._
+
+By staking your SOL tokens, you help secure the network and
+[earn rewards](implemented-proposals/staking-rewards.md) while doing so.
+
+You can stake by delegating your tokens to 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 delegated to a validator, the more often this validator
+is chosen to write new transactions to the ledger. The more transactions
+the validator writes, the more rewards the validator and its delegators earn.
+Validators who configure their systems to be able to process more transactions
+earn proportionally more rewards and
+because they 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_. Since 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.
+
+You risk losing tokens when staking through a process known as
+_slashing_. Slashing involves the 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.
+
+When a validator is slashed, all token holders who have delegated stake to that
+validator 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. More details on the slashing roadmap can
+be found
+[here](proposals/optimistic-confirmation-and-slashing.md#slashing-roadmap).
+
+Rewards and slashing align validator and token holder interests which helps keep the network
+secure, robust and performant.
+
+
+## How do I stake my SOL tokens?
+
+You can stake SOL by moving your tokens
+into a wallet that supports staking.   The wallet provides steps to create a stake account
+and do the delegation.
+
+#### Supported Wallets
+
+Staking operations are supported by the following wallet solutions:
+
+- Phantom.app in conjunction with a seed phrase or a Ledger Nano.
+  Check out Phantom's [guide to staking](https://phantom.app/blog/solana-staking-in-just-3-clicks) for details.
+
+- SolFlare.com in conjunction with a keystore file or a Ledger Nano.
+  Check out our [guide to using SolFlare](wallet-guide/solflare.md) for details.
+
+- Solana command line tools can perform all stake operations in conjunction
+  with a CLI-generated keypair file wallet, a paper wallet, or with a connected
+  Ledger Nano.
+  [Staking commands using the Solana Command Line Tools](cli/delegate-stake.md).
+
+- [Exodus](https://www.exodus.com/) wallet. They make the process very simple,
+  but you cannot choose a validator: they assign you to their partner validator.
+  See their [FAQ](https://support.exodus.com/article/1551-solana-staking-faq)
+  for details.
+
+- [Binance](https://www.binance.com/) and [FTX](https://ftx.com/) exchanges.
+  Note that you cannot choose a validator with these services: they assign you
+  to their partner validator.
+
+#### Create a Stake Account
+
+Follow the wallet's instructions for creating a staking account.  This account
+will be of a different type than one used to simply send and receive tokens.
+
+#### Select a Validator
+
+Follow the wallet's instructions for selecting a validator.  You can get
+information about potentially performant validators from the links below.
+The Solana Foundation does 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. Do your own due diligence.
+
+#### Delegate your Stake
+
+Follow the wallet's instructions for delegating your to your chosen validator.
+
+## Stake Account Details
+
+For more information about the operations and permissions associated with a
+stake account, please see [Stake Accounts](staking/stake-accounts.md)

package/src/storage_rent_economics.md

@@ -0,0 +1,17 @@
+---
+title: Storage Rent Economics
+---
+
+Each transaction that is submitted to the Solana ledger imposes costs. Transaction fees paid by the submitter, and collected by a validator, in theory, account for the acute, transactional, costs of validating and adding that data to the ledger. Unaccounted in this process is the mid-term storage of active ledger state, necessarily maintained by the rotating validator set. This type of storage imposes costs not only to validators but also to the broader network as active state grows so does data transmission and validation overhead. To account for these costs, we describe here our preliminary design and implementation of storage rent.
+
+Storage rent can be paid via one of two methods:
+
+Method 1: Set it and forget it
+
+With this approach, accounts with two-years worth of rent deposits secured are exempt from network rent charges. By maintaining this minimum-balance, the broader network benefits from reduced liquidity and the account holder can rest assured that their `Account::data` will be retained for continual access/usage.
+
+Method 2: Pay per byte
+
+If an account has less than two-years worth of deposited rent the network charges rent on a per-epoch basis, in credit for the next epoch. This rent is deducted at a rate specified in genesis, in lamports per kilobyte-year.
+
+For information on the technical implementation details of this design, see the [Rent](implemented-proposals/rent.md) section.