From 3b813db42f67b9cd4d1c3de562ea0683dfe296bf Mon Sep 17 00:00:00 2001 From: "mergify[bot]" <37929162+mergify[bot]@users.noreply.github.com> Date: Mon, 14 Jun 2021 06:56:39 +0000 Subject: [PATCH] minor fixes to punctuation and typos (#17881) (#17923) * fix minor typos and punctuation * fix minor typos and punctuation * rewording for clarity and typo corrections * rewording for clarity and typo corrections * rewording for clarity and typo corrections Co-authored-by: Gregg Dourgarian (cherry picked from commit 54155f875ad1c11e1b90daa9c5ba5e5a9024618f) Co-authored-by: Haik Dulgarian --- .../developing/programming-model/accounts.md | 80 ++++++++++--------- docs/src/staking.md | 63 ++++++--------- 2 files changed, 67 insertions(+), 76 deletions(-) diff --git a/docs/src/developing/programming-model/accounts.md b/docs/src/developing/programming-model/accounts.md index 283252806e..2c60c6373a 100644 --- a/docs/src/developing/programming-model/accounts.md +++ b/docs/src/developing/programming-model/accounts.md @@ -5,14 +5,14 @@ title: "Accounts" ## Storing State between Transactions If the program needs to store state between transactions, it does so using -_accounts_. Accounts are similar to files in operating systems such as Linux. -Like a file, an account may hold arbitrary data and that data persists beyond +_accounts_. Accounts are similar to files in operating systems such as Linux in +that they may hold arbitrary data that persists beyond the lifetime of a program. Also like a file, an account includes metadata that tells the runtime who is allowed to access the data and how. Unlike a file, the account includes metadata for the lifetime of the file. That -lifetime is expressed in "tokens", which is a number of fractional native -tokens, called _lamports_. Accounts are held in validator memory and pay +lifetime is expressed by a number of fractional native +tokens called _lamports_. Accounts are held in validator memory and pay ["rent"](#rent) to stay there. Each validator periodically scans all accounts and collects rent. Any account that drops to zero lamports is purged. Accounts can also be marked [rent-exempt](#rent-exemption) if they contain a sufficient @@ -24,10 +24,10 @@ uses an _address_ to look up an account. The address is a 256-bit public key. ## Signers Transactions may include digital [signatures](terminology.md#signature) -corresponding to the accounts' public keys referenced by the transaction. When a -corresponding digital signature is present it signifies that the holder of the -account's private key signed and thus "authorized" the transaction and the -account is then referred to as a _signer_. Whether an account is a signer or not +corresponding to the accounts' public keys referenced by the transaction. Such +signatures signify that the holder of the +account's private key signed and thus "authorized" the transaction. In this case, +the account is referred to as a _signer_. Whether an account is a signer or not is communicated to the program as part of the account's metadata. Programs can then use that information to make authority decisions. @@ -41,21 +41,22 @@ modify a read-only account, the transaction is rejected by the runtime. ## Executable -If an account is marked "executable" in its metadata then it is considered a -program which can be executed by including the account's public key an +If an account is marked "executable" in its metadata, then it is considered a +program which can be executed by including the account's public key in an instruction's [program id](transactions.md#program-id). Accounts are marked as executable during a successful program deployment process by the loader that -owns the account. For example, during BPF program deployment, once the loader -has determined that the BPF bytecode in the account's data is valid, the loader +owns the account. When a program is deployed to the execution engine (BPF deployment), +the loader determines that the bytecode in the account's data is valid. +If so, the loader permanently marks the program account as executable. Once executable, the runtime enforces that the account's data (the program) is immutable. ## Creating -To create an account a client generates a _keypair_ and registers its public key -using the `SystemProgram::CreateAccount` instruction with preallocated a fixed -storage size in bytes. The current maximum size of an account's data is 10 -megabytes. +To create an account, a client generates a _keypair_ and registers its public key +using the `SystemProgram::CreateAccount` instruction with a fixed +storage size in bytes preallocated. +The current maximum size of an account's data is 10 megabytes. An account address can be any arbitrary 256 bit value, and there are mechanisms for advanced users to create derived addresses @@ -64,13 +65,15 @@ for advanced users to create derived addresses Accounts that have never been created via the system program can also be passed to programs. When an instruction references an account that hasn't been -previously created the program will be passed an account that is owned by the -system program, has zero lamports, and zero data. But, the account will reflect -whether it is a signer of the transaction or not and therefore can be used as an +previously created, the program will be passed an account with no data and zero lamports +that is owned by the system program. + +Such newly created accounts reflect +whether they sign the transaction and therefore can be used as an authority. Authorities in this context convey to the program that the holder of the private key associated with the account's public key signed the transaction. The account's public key may be known to the program or recorded in another -account and signify some kind of ownership or authority over an asset or +account, signifying some kind of ownership or authority over an asset or operation the program controls or performs. ## Ownership and Assignment to Programs @@ -89,19 +92,22 @@ data and credit the account. For security purposes, it is recommended that programs check the validity of any account it reads but does not modify. -The security model enforces that an account's data can only be modified by the -account's `Owner` program. Doing so allows the program to trust that the data -passed to them via accounts they own will be in a known and valid state. The -runtime enforces this by rejecting any transaction containing a program that -attempts to write to an account it does not own. But, there are also cases -where a program may merely read an account they think they own and assume the -data has only been written by themselves and thus is valid. But anyone can -issues instructions to a program, and the runtime does not know that those -accounts are expected to be owned by the program. Therefore a malicious user +This is because a malicious user could create accounts with arbitrary data and then pass these accounts to the -program in the place of a valid account. The arbitrary data could be crafted in +program in place of valid accounts. The arbitrary data could be crafted in a way that leads to unexpected or harmful program behavior. +The security model enforces that an account's data can only be modified by the +account's `Owner` program. This allows the program to trust that the data +passed to them via accounts they own. The +runtime enforces this by rejecting any transaction containing a program that +attempts to write to an account it does not own. + +If a program were to not check account validity, it might read an account +it thinks it owns but doesn't. Anyone can +issue instructions to a program, and the runtime does not know that those +accounts are expected to be owned by the program. + To check an account's validity, the program should either check the account's address against a known value or check that the account is indeed owned correctly (usually owned by the program itself). @@ -109,6 +115,7 @@ correctly (usually owned by the program itself). One example is when programs use a sysvar account. Unless the program checks the account's address or owner, it's impossible to be sure whether it's a real and valid sysvar account merely by successful deserialization of the account's data. + Accordingly, the Solana SDK [checks the sysvar account's validity during deserialization](https://github.com/solana-labs/solana/blob/a95675a7ce1651f7b59443eb146b356bc4b3f374/sdk/program/src/sysvar/mod.rs#L65). A alternative and safer way to read a sysvar is via the sysvar's [`get()` @@ -116,15 +123,14 @@ function](https://github.com/solana-labs/solana/blob/64bfc14a75671e4ec3fe969ded0 which doesn't require these checks. If the program always modifies the account in question, the address/owner check -isn't required because modifying an unowned (could be the malicious account with -the wrong owner) will be rejected by the runtime, and the containing transaction -will be thrown out. +isn't required because modifying an unowned account will be rejected by the runtime, +and the containing transaction will be thrown out. ## Rent Keeping accounts alive on Solana incurs a storage cost called _rent_ because the -cluster must actively maintain the data to process any future transactions on -it. This is different from Bitcoin and Ethereum, where storing accounts doesn't +blockchain cluster must actively maintain the data to process any future transactions. +This is different from Bitcoin and Ethereum, where storing accounts doesn't incur any costs. The rent is debited from an account's balance by the runtime upon the first @@ -190,8 +196,8 @@ if the transferred lamports are less than or equal to 2,439. ### Rent exemption Alternatively, an account can be made entirely exempt from rent collection by -depositing at least 2 years-worth of rent. This is checked every time an -account's balance is reduced and rent is immediately debited once the balance +depositing at least 2 years worth of rent. This is checked every time an +account's balance is reduced, and rent is immediately debited once the balance goes below the minimum amount. Program executable accounts are required by the runtime to be rent-exempt to diff --git a/docs/src/staking.md b/docs/src/staking.md index 05352e60a7..b86b88b2f2 100644 --- a/docs/src/staking.md +++ b/docs/src/staking.md @@ -6,57 +6,51 @@ _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 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! +By staking your SOL tokens, you help secure the network and +[earn rewards](implemented-proposals/staking-rewards.md) while doing so. -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. +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 a validator has delegated to them, the more often this validator +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 they and their delegators earn. +the validator writes, the more rewards the validator and its 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. +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_. As validators earn more +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, in order to attract more -delegated stake. +to offer the lowest commission for their services. -There is a risk of loss of tokens when staking, through a process known as +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. -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 +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). -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. +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? -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. +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 @@ -81,20 +75,13 @@ Staking operations are supported by the following wallet solutions: #### 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). +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 -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. +Follow the wallet's instructions for selecting a validator. You can get +information about potentially performant validators from the links below. The Solana Labs team and the Solana Foundation do not recommend any particular validator. @@ -116,13 +103,11 @@ To view block production statistics, use the Solana command-line tools: - `solana block-production` The Solana team does not make recommendations on how to interpret this -information. Potential delegators should do their own due diligence. +information. Do your 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. +Follow the wallet's instructions for delegating your to your chosen validator. ## Stake Account Details