EOSIO · lparisc · Nov 6, 2020 · Nov 6, 2020 · Nov 6, 2020
diff --git a/docs/01_key-concepts/01_system.md b/docs/01_key-concepts/01_system.md
@@ -1,18 +1,18 @@
 ---
 content_title: System contracts, system accounts, privileged accounts
-link_text: System contracts and accounts, privileged accounts
+link_text: System contracts, system accounts, privileged accounts
 ---
 
-At the genesis of an EOSIO based blockchain, there is only one account present, `eosio` account, which is the main `system account`. There are other `system account`s, created by `eosio` account, which control specific actions of the `system contract`s [mentioned in previous section](../#system-contracts-defined-in-eosio.contracts). __Note__ the terms `system contract` and `system account`. `Privileged accounts` are accounts which can execute a transaction while skipping the standard authorization check. To ensure that this is not a security hole, the permission authority over these accounts is granted to `eosio.prods` system account.
+At the genesis of an EOSIO-based blockchain, there is only one account present, `eosio` account, which is the main `system account`. There are other `system account`s, created by `eosio` account, which control specific actions of the `system contract`s [mentioned in previous section](../#system-contracts-defined-in-eosio.contracts). __Note__ the terms `system contract` and `system account`. `Privileged accounts` are accounts which can execute a transaction while skipping the standard authorization check. To ensure that this is not a security hole, the permission authority over these accounts is granted to `eosio.prods` system account.
 
 As you just learned the relation between a `system account` and a `system contract`, it is also important to remember that not all system accounts contain a system contract, but each system account has important roles in the blockchain functionality, as follows:
 
 |Account|Privileged|Has contract|Description|
 |---|---|---|---|
-|eosio|Yes|It contains the `eosio.system` contract|The main system account on an EOSIO based blockchain.|
+|eosio|Yes|It contains the `eosio.system` contract|The main system account on an EOSIO-based blockchain.|
 |eosio.msig|Yes|It contains the `eosio.msig` contract|Allows the signing of a multi-sig transaction proposal for later execution if all required parties sign the proposal before the expiration time.|
 |eosio.wrap|Yes|It contains the `eosio.wrap` contract.|Simplifies block producer superuser actions by making them more readable and easier to audit.|
-|eosio.token|No|It contains the `eosio.token` contract.|Defines the structures and actions allowing users to create, issue, and manage tokens on EOSIO based blockchains.|
+|eosio.token|No|It contains the `eosio.token` contract.|Defines the structures and actions allowing users to create, issue, and manage tokens on EOSIO-based blockchains.|
 |eosio.names|No|No|The account which is holding funds from namespace auctions.|
 |eosio.bpay|No|No|The account that pays the block producers for producing blocks. It assigns 0.25% of the inflation based on the amount of blocks a block producer created in the last 24 hours.|
 |eosio.prods|No|No|The account representing the union of all current active block producers permissions.|
@@ -21,4 +21,4 @@ As you just learned the relation between a `system account` and a `system contra
 |eosio.saving|No|No|The account which holds the 4% of network inflation.|
 |eosio.stake|No|No|The account that keeps track of all SYS tokens which have been staked for NET or CPU bandwidth.|
 |eosio.vpay|No|No|The account that pays the block producers accordingly with the votes won. It assigns 0.75% of inflation based on the amount of votes a block producer won in the last 24 hours.|
-|eosio.rex|No|No|The account that keeps track of fees and balances resulted from REX related actions execution.| 
+|eosio.rex|No|No|The account that keeps track of fees and balances resulted from REX related actions execution.|
diff --git a/docs/01_key-concepts/02_ram.md b/docs/01_key-concepts/02_ram.md
@@ -1,6 +1,6 @@
 ---
-content_title: RAM as resource
-link_text: RAM as resource
+content_title: RAM as system resource
+link_text: RAM as system resource
 ---
 
 ## What is RAM
@@ -23,10 +23,17 @@ The EOSIO-based blockchains are known for their high performance, which is achie
 
 ## RAM Importance
 
-RAM is a very important resource because of the following reasons
+RAM is a very important system resource because of the following reasons:
 
-- It is a limited resource, each EOSIO-based blockchain can have a different policy and rules around RAM; for example the public EOS blockchain started with 64GB of RAM and after that the block producers decided to increase the memory with 1KB per block, thus increasing constantly the supply of RAM for its price to not grow too high due to the increased demand from blockchain applications.
+- It is a limited resource, each EOSIO-based blockchain can have different policies and rules around RAM; for example the public EOS blockchain started with 64GB of RAM and after that the block producers decided to increase the memory with 1KB per block, thus increasing constantly the supply of RAM for its price to not grow too high due to the increased demand from blockchain applications.
 
 - RAM is used in executing many actions sent to the blockchain; creating a new account action, for example, it needs to store in the blockchain memory the new account's information; also when an account accepts a new type of token a new record has to be created, somewhere in the blockchain memory, that holds the balance of the new token accepted, and that memory, the storage space on the blockchain, has to be purchased either by the account that transfers the token or by the account that accepts the new token type.
 
-RAM is a scarce resource priced according to the unique Bancor liquidity algorithm which is implemented in the system contract [here](https://github.com/EOSIO/eos/blob/905e7c85714aee4286fa180ce946f15ceb4ce73c/contracts/eosio.system/exchange_state.hpp).
+- The smart contract can not store any additional information if it consumes all its allocated RAM. To continue to save data in the blockchain database, one, or both of the following conditions must be met:
+
+  - A portion of the occupied RAM is freed by the smart contract.
+  - More RAM is allocated to the smart contract account through the RAM buying process.
+
+RAM is a scarce resource priced according to the unique Bancor liquidity algorithm which is implemented in the system contract [here](https://github.com/EOSIO/eos/blob/905e7c85714aee4286fa180ce946f15ceb4ce73c/contracts/eosio.system/exchange_state.hpp).
+
+The RAM system resource must be purchased using the system token. Refer to the [cleos manual](https://developers.eos.io/manuals/eos/v2.0/cleos/how-to-guides/how-to-buy-ram) to learn how to buy RAM via the command line interface.
diff --git a/docs/01_key-concepts/03_cpu.md b/docs/01_key-concepts/03_cpu.md
@@ -1,6 +1,10 @@
 ---
-content_title: CPU as resource
-link_text: CPU as resource
+content_title: CPU as system resource
+link_text: CPU as system resource
 ---
 
-CPU is processing power, the amount of CPU an account has is measured in microseconds, it is referred to as `cpu bandwidth` on the cleos get account command output and represents the amount of processing time an account has at its disposal when pushing actions to a contract.
+The system resource CPU provides processing power to blockchain accounts. The amount of CPU an account has is measured in microseconds and it is referred to as `cpu bandwidth` on the `cleos get account` command output. The `cpu bandwidth` represents the amount of processing time an account has at its disposal when actions sent to its contract are executed by the blockchain. When a transaction is executed by the blockchain it consumes CPU and NET, therefore sufficient CPU must be staked in order for transactions to complete.
+
+For more details about EOSIO staking refer to the following:
+* [Staking Mechanism](https://developers.eos.io/welcome/latest/overview/technical_features#staking-mechanism).
+* [Staking on EOSIO-based blockchains](05_stake.md)
diff --git a/docs/01_key-concepts/04_net.md b/docs/01_key-concepts/04_net.md
@@ -1,6 +1,10 @@
 ---
-content_title: NET as resource
-link_text: NET as resource
+content_title: NET as system resource
+link_text: NET as system resource
 ---
 
-As CPU and RAM, NET is also a very important resource in EOSIO-based blockchains. NET is the network bandwidth measured in bytes of transactions and it is referred to as `net bandwidth` on the cleos get account command. This resource like CPU must be staked so that a contract's transactions can be executed.
+NET, as CPU and RAM, is a very important system resource in EOSIO-based blockchains. NET is measured by the byte size of the transactions saved in the blockchain database and it is referred to as `net bandwidth` on the cleos get account command result. When a transaction is executed by the blockchain it consumes CPU and NET, therefore sufficient NET must be staked in order for transactions to complete.
+
+For more details about EOSIO staking refer to the following:
+* [Staking Mechanism](https://developers.eos.io/welcome/latest/overview/technical_features#staking-mechanism).
+* [Staking on EOSIO-based blockchains](05_stake.md)
diff --git a/docs/01_key-concepts/05_stake.md b/docs/01_key-concepts/05_stake.md
@@ -1,6 +1,50 @@
 ---
-content_title: Staking on EOSIO based blockchains
-link_text: Staking on EOSIO based blockchains
+content_title: Staking on EOSIO-based blockchains
+link_text: Staking on EOSIO-based blockchains
 ---
 
-On EOSIO based blockchains, to be able to deploy and then interact with a smart contract via its implemented actions it needs to be backed up by resources allocated on the account where the smart contract is deployed to. The three resource types an EOSIO smart contract developer needs to know about are RAM, CPU and NET. You can __stake__ CPU and NET and you can __buy__ RAM. You will also find that staking/unstaking is at times referred to as delegating/undelegating. The economics of staking is also to provably commit to a promise that you'll hold the staked tokens, either for NET or CPU, for a pre-established period of time, in spite of inflation caused by minting new tokens in order to reward BPs for their services every 24 hours.
+## System Resources
+
+EOSIO-based blockchains work with three system resources:
+
+* [RAM](02_ram.md)
+* [CPU](03_cpu.md)
+* [NET](04_net.md)
+
+## How To Allocate System Resources
+
+EOSIO-based blockchain accounts need sufficient system resources, RAM, CPU and NET, to interact with the smart contracts deployed on the blockchain.
+
+### Stake NET and CPU
+
+The CPU and NET system resources are allocated by the account owner via the staking mechanism. Refer to the [cleos manual](https://developers.eos.io/manuals/eos/v2.0/cleos/how-to-guides/how-to-stake-resource) on how to do it via the command line interface.
+
+You will also find that staking/unstaking is at times referred to as delegating/undelegating. The economics of staking is also to provably commit to a promise that you will hold the staked tokens, either for NET or CPU, for a pre-established period of time, in spite of inflation caused by minting new tokens in order to reward BPs for their services every 24 hours.
+
+When you stake tokens for CPU and NET, you gain access to system resources proportional to the total amount of tokens staked by all other users for the same system resource at the same time. This means you can execute transactions at no cost but in the limits of the staked tokens. The staked tokens guarantee the proportional amount of resources regardless of any variations in the free market.
+
+If an account consumes all its allocated CPU and NET resources, it has two options:
+
+* It can wait for the blockchain to replenish the consumed resources. You can read more details below about the [system resources replenish algorithm].(05_stake.md#System-Resources-Replenish-Algorithm).
+* It can allocate more resources through the staking mechanism.
+
+When an account uses the allocated resources, the amount that can be used in one transaction is limited by predefine [maximum CPU](https://developers.eos.io/manuals/eosio.cdt/latest/structeosio_1_1blockchain__parameters#variable-max_transaction_cpu_usage), [minimum CPU](https://developers.eos.io/manuals/eosio.cdt/latest/structeosio_1_1blockchain__parameters#variable-min_transaction_cpu_usage), and [maximum NET](https://developers.eos.io/manuals/eosio.cdt/latest/structeosio_1_1blockchain__parameters#variable-max_transaction_net_usage) limits. Transactions executed by the blockchain contain one or more actions, and each transaction must consume an amount of CPU and NET which is in the limits defined by the aforementioned blockchain settings.
+
+#### System Resources Replenish Algorithm
+
+EOSIO-based blockchains replenish automatically the consumed CPU and NET system resources. Before a transaction is executed, by the blockchain, it first calculates how many resources the account executing the transaction can consume. The calculation uses an exponential moving average with linear extrapolation when data is missing, and it multiplies the currently accumulated average by `(number of blocks in the window - number of blocks since last update) / (number of blocks in the window)`. The window is set as 24 hours window.
+
+This formula has the following outcomes:
+
+* If an account waited `number of blocks in the window` without executing any transaction it resets to zero usage.
+
+* If an account issues a transaction with every block it would always be `(number of blocks in the window - 1) / (number of blocks in the window)`, a very small value, very close to zero. Mathematically it _never_ reaches zero but the EOSIO implementation truncates off the tiny numbers to zero.
+
+* The accounts that execute transactions more often than the ones that execute less transactions, replenish their resources slower than the later. In other words, the more transactions an account executes the slower the replenish of resources.
+
+[[info]]
+| The blockchain calculates and updates the remaining resources, for the accounts which execute transactions, with each block, before each transaction is executed. As time passes, as explained above, the consumed system resources are gradually replenished, and the available system resources increase, or decrease, depending on how many transactions an account executes. After waiting for some time, if you check the available resources balance and expect to see it increased, because your account did not executed any transactions, you will not see it updated. That is because it gets updated only before a transaction is executed. Therefore in order to see the available resources you have to execute a transaction. This is counter intuitive and the next versions will improve this aspect.
+
+### Buy RAM
+
+The RAM resource must be bought using the system token. Refer to the [cleos manual](https://developers.eos.io/manuals/eos/v2.0/cleos/how-to-guides/how-to-buy-ram) to learn how to do it via the command line interface. When an account consumes all its allocated RAM can not store any additional information on the blockchain database until it frees some of the occupied RAM or more RAM is allocated to the account through the RAM buying process.
diff --git a/docs/01_key-concepts/06_vote.md b/docs/01_key-concepts/06_vote.md
@@ -1,6 +1,6 @@
 ---
-content_title: Voting on EOSIO based blockchains
-link_text: Voting on EOSIO based blockchains
+content_title: Voting on EOSIO-based blockchains
+link_text: Voting on EOSIO-based blockchains
 ---
 
-In a EOSIO-based network the blockchain is kept alive by nodes which are interconnected into a mesh, communicating with each other via peer to peer protocols. Some of these nodes are elected, via a __voting__ process, by the token holders to be producer nodes. They produce blocks, validate them and reach consensus on what transactions are allowed in each block, their order, and what blocks are finalized and stored forever in the blockchain memory. This way the governance, the mechanism by which collective decisions are made, of the blockchain is achieved through the 21 active block producers which are appointed by token holders' __votes__. It's the 21 active block producers which continuously create the blockchain by creating blocks, and securing them by validating them, and reaching consensus. Consensus is reached when 2/3+1 active block producers agree on validity of a block, that is all transactions contained in it and their order.
+In a EOSIO-based network the blockchain is kept alive by nodes which are interconnected between each other, communicating with each other via peer to peer protocols. Some of these nodes are elected, via a voting process, by the token holders to be producer nodes. They produce blocks, validate them and reach consensus on what transactions are allowed in each block, their order, and what blocks are finalized and stored forever in the blockchain. This way the governance, the mechanism by which collective decisions are made, of the blockchain is achieved through the 21 active block producers which are appointed by token holders' votes. It's the 21 active block producers which continuously create the blockchain by creating blocks, and securing them by validating them, and reaching consensus. Consensus is reached when 2/3+1 active block producers agree on validity of a block, that is all transactions contained in it and their order. The 21 producers is the default value however it can be configured to be higher or smaller to meet each business case requirements.