Spliting index.md file for 1.9.x

contracts/eosio.bios/include/eosio.bios/eosio.bios.hpp

@@ -7,25 +7,6 @@
 #include <eosio/privileged.hpp>
 #include <eosio/producer_schedule.hpp>
 
-/**
- * EOSIO Contracts
- *
- * The design of the EOSIO blockchain calls for a number of smart contracts that are run at a
- * privileged permission level in order to support functions such as block producer registration and
- * voting, token staking for CPU and network bandwidth, RAM purchasing, multi-sig, etc. These smart
- * contracts are referred to as the system, token, msig and wrap (formerly known as sudo) contracts.
- *
- * This repository contains examples of these privileged contracts that are useful when deploying,
- * managing, and/or using an EOSIO blockchain. They are provided for reference purposes:
- * - eosio.bios
- * - eosio.system
- * - eosio.msig
- * - eosio.wrap
- *
- * The following unprivileged contract(s) are also part of the system.
- * - eosio.token
- */
-
 namespace eosiobios {
 
    using eosio::action_wrapper;
@@ -85,6 +66,11 @@ namespace eosiobios {
                                      (schedule_version)(new_producers))
    };
 
+   /**
+    * The `eosio.bios` is the first sample of system contract provided by `block.one` through the EOSIO platform. It is a minimalist system contract because it only supplies the actions that are absolutely critical to bootstrap a chain and nothing more. This allows for a chain agnostic approach to bootstrapping a chain.
+    * 
+    * Just like in the `eosio.system` sample contract implementation, there are a few actions which are not implemented at the contract level (`newaccount`, `updateauth`, `deleteauth`, `linkauth`, `unlinkauth`, `canceldelay`, `onerror`, `setabi`, `setcode`), they are just declared in the contract so they will show in the contract's ABI and users will be able to push those actions to the chain via the account holding the `eosio.system` contract, but the implementation is at the EOSIO core level. They are referred to as EOSIO native actions.
+    */
    class [[eosio::contract("eosio.bios")]] bios : public eosio::contract {
       public:
          using contract::contract;
@@ -182,8 +168,6 @@ namespace eosiobios {
          [[eosio::action]]
          void setcode( name account, uint8_t vmtype, uint8_t vmversion, const std::vector<char>& code ) {}
 
-         /** @}*/
-
          /**
           * Set abi action sets the abi for contract identified by `account` name. Creates an entry in the abi_hash_table
           * index, with `account` name as key, if it is not already present and sets its value with the abi hash.

contracts/eosio.msig/include/eosio.msig/eosio.msig.hpp

@@ -6,12 +6,15 @@
 #include <eosio/transaction.hpp>
 
 namespace eosio {
-    
+
    /**
-    * @defgroup eosiomsig eosio.msig
-    * @ingroup eosiocontracts
-    * eosio.msig contract defines the structures and actions needed to manage the proposals and approvals on blockchain.
-    * @{
+    * The `eosio.msig` system contract allows for creation of proposed transactions which require authorization from a list of accounts, approval of the proposed transactions by those accounts required to approve it, and finally, it also allows the execution of the approved transactions on the blockchain.
+    *
+    * In short, the workflow to propose, review, approve and then executed a transaction it can be described by the following:
+    * - first you create a transaction json file,
+    * - then you submit this proposal to the `eosio.msig` contract, and you also insert the account permissions required to approve this proposal into the command that submits the proposal to the blockchain,
+    * - the proposal then gets stored on the blockchain by the `eosio.msig` contract, and is accessible for review and approval to those accounts required to approve it,
+    * - after each of the appointed accounts required to approve the proposed transactions reviews and approves it, you can execute the proposed transaction. The `eosio.msig` contract will execute it automatically, but not before validating that the transaction has not expired, it is not cancelled, and it has been signed by all the permissions in the initial proposal's required permission list.
     */
    class [[eosio::contract("eosio.msig")]] multisig : public contract {
       public:
@@ -156,5 +159,4 @@ namespace eosio {
 
          typedef eosio::multi_index< "invals"_n, invalidation > invalidations;
    };
-   /** @}*/ // end of @defgroup eosiomsig eosio.msig
 } /// namespace eosio

contracts/eosio.system/include/eosio.system/eosio.system.hpp

@@ -78,19 +78,20 @@ namespace eosiosystem {
    static constexpr int64_t  default_inflation_pay_factor  = 50000;   // producers pay share = 10000 / 50000 = 20% of the inflation
    static constexpr int64_t  default_votepay_factor        = 40000;   // per-block pay share = 10000 / 40000 = 25% of the producer pay
 
-   /**
-    * eosio.system contract
-    * 
-    * eosio.system contract defines the structures and actions needed for blockchain's core functionality.
-    * - Users can stake tokens for CPU and Network bandwidth, and then vote for producers or
-    *    delegate their vote to a proxy.
-    * - Producers register in order to be voted for, and can claim per-block and per-vote rewards.
-    * - Users can buy and sell RAM at a market-determined price.
-    * - Users can bid on premium names.
-    * - A resource exchange system (REX) allows token holders to lend their tokens,
-    *    and users to rent CPU and Network resources in return for a market-determined fee.
-    */
-
+  /**
+   * The `eosio.system` smart contract is provided by `block.one` as a sample system contract, and it defines the structures and actions needed for blockchain's core functionality.
+   * 
+   * Just like in the `eosio.bios` sample contract implementation, there are a few actions which are not implemented at the contract level (`newaccount`, `updateauth`, `deleteauth`, `linkauth`, `unlinkauth`, `canceldelay`, `onerror`, `setabi`, `setcode`), they are just declared in the contract so they will show in the contract's ABI and users will be able to push those actions to the chain via the account holding the `eosio.system` contract, but the implementation is at the EOSIO core level. They are referred to as EOSIO native actions.
+   * 
+   * - Users can stake tokens for CPU and Network bandwidth, and then vote for producers or
+   *    delegate their vote to a proxy.
+   * - Producers register in order to be voted for, and can claim per-block and per-vote rewards.
+   * - Users can buy and sell RAM at a market-determined price.
+   * - Users can bid on premium names.
+   * - A resource exchange system (REX) allows token holders to lend their tokens,
+   *    and users to rent CPU and Network resources in return for a market-determined fee.
+   */
+
    // A name bid, which consists of:
    // - a `newname` name that the bid is for
    // - a `high_bidder` account name that is the one with the highest bid so far

contracts/eosio.system/include/eosio.system/exchange_state.hpp

@@ -8,11 +8,6 @@ namespace eosiosystem {
    using eosio::asset;
    using eosio::symbol;
 
-   /**
-    * @addtogroup eosiosystem
-    * @{
-    */
-
    /**
     * Uses Bancor math to create a 50/50 relay between two asset types.
     *
@@ -50,5 +45,4 @@ namespace eosiosystem {
    };
 
    typedef eosio::multi_index< "rammarket"_n, exchange_state > rammarket;
-   /** @}*/ // enf of @addtogroup eosiosystem
 } /// namespace eosiosystem

contracts/eosio.system/include/eosio.system/native.hpp

@@ -17,10 +17,6 @@ namespace eosiosystem {
    using eosio::permission_level;
    using eosio::public_key;
 
-   /**
-    * @addtogroup eosiosystem
-    * @{
-    */
    /**
     * A weighted permission.
     *
@@ -264,5 +260,4 @@ namespace eosiosystem {
          using setcode_action = eosio::action_wrapper<"setcode"_n, &native::setcode>;
          using setabi_action = eosio::action_wrapper<"setabi"_n, &native::setabi>;
    };
-   /** @}*/ // @addtogroup eosiosystem
 }

contracts/eosio.system/include/eosio.system/rex.results.hpp

@@ -9,9 +9,9 @@ using eosio::asset;
 using eosio::name;
 
 /**
- * The actions `buyresult`, `sellresult`, `rentresult`, and `orderresult` of `rex.results` are all no-ops. 
- * They are added as inline convenience actions to `rentnet`, `rentcpu`, `buyrex`, `unstaketorex`, and `sellrex`. 
- * An inline convenience action does not have any effect, however, 
+ * The actions `buyresult`, `sellresult`, `rentresult`, and `orderresult` of `rex.results` are all no-ops.
+ * They are added as inline convenience actions to `rentnet`, `rentcpu`, `buyrex`, `unstaketorex`, and `sellrex`.
+ * An inline convenience action does not have any effect, however,
  * its data includes the result of the parent action and appears in its trace.
  */
 class [[eosio::contract("rex.results")]] rex_results : eosio::contract {

contracts/eosio.token/include/eosio.token/eosio.token.hpp

@@ -14,8 +14,13 @@ namespace eosio {
    using std::string;
 
    /**
-    * eosio.token contract defines the structures and actions that allow users to create, issue, and manage
-    * tokens on EOSIO based blockchains.
+    * The `eosio.token` sample system contract defines the structures and actions that allow users to create, issue, and manage tokens for EOSIO based blockchains. It demonstrates one way to implement a smart contract which allows for creation and management of tokens. It is possible for one to create a similar contract which suits different needs. However, it is recommended that if one only needs a token with the below listed actions, that one uses the `eosio.token` contract instead of developing their own.
+    * 
+    * The `eosio.token` contract class also implements two useful public static methods: `get_supply` and `get_balance`. The first allows one to check the total supply of a specified token, created by an account and the second allows one to check the balance of a token for a specified account (the token creator account has to be specified as well).
+    * 
+    * The `eosio.token` contract manages the set of tokens, accounts and their corresponding balances, by using two internal multi-index structures: the `accounts` and `stats`. The `accounts` multi-index table holds, for each row, instances of `account` object and the `account` object holds information about the balance of one token. The `accounts` table is scoped to an eosio account, and it keeps the rows indexed based on the token's symbol.  This means that when one queries the `accounts` multi-index table for an account name the result is all the tokens that account holds at the moment.
+    * 
+    * Similarly, the `stats` multi-index table, holds instances of `currency_stats` objects for each row, which contains information about current supply, maximum supply, and the creator account for a symbol token. The `stats` table is scoped to the token symbol.  Therefore, when one queries the `stats` table for a token symbol the result is one single entry/row corresponding to the queried symbol token if it was previously created, or nothing, otherwise.
     */
    class [[eosio::contract("eosio.token")]] token : public contract {
       public:

contracts/eosio.wrap/include/eosio.wrap/eosio.wrap.hpp

@@ -6,16 +6,11 @@
 
 namespace eosio {
    /**
-    * @defgroup eosiowrap eosio.wrap
-    * @ingroup eosiocontracts
-    * eosio.wrap contract simplifies Block Producer superuser actions by making them more readable and easier to audit.
-
-    * It does not grant block producers any additional powers that do not already exist within the
-    * system. Currently, 15/21 block producers can already change an account's keys or modify an
-    * account's contract at the request of ECAF or an account's owner. However, the current method
-    * is opaque and leaves undesirable side effects on specific system accounts.
-    * eosio.wrap allows for a cleaner method of implementing these important governance actions.
-    * @{
+    * The `eosio.wrap` system contract allows block producers to bypass authorization checks or run privileged actions with 15/21 producer approval and thus simplifies block producers superuser actions. It also makes these actions easier to audit.
+    *
+    * It does not give block producers any additional powers or privileges that do not already exist within the EOSIO based blockchains. As it is implemented, in an EOSIO based blockchain, 15/21 block producers can change an account's permissions or modify an account's contract code if they decided it is beneficial for the blockchain and community. However, the current method is opaque and leaves undesirable side effects on specific system accounts, and thus the `eosio.wrap `contract solves this matter by providing an easier method of executing important governance actions.
+    *
+    * The only action implemented by the `eosio.wrap` system contract is the `exec` action. This action allows for execution of a transaction, which is passed to the `exec` method in the form of a packed transaction in json format via the 'trx' parameter and the `executer` account that executes the transaction. The same `executer` account will also be used to pay the RAM and CPU fees needed to execute the transaction.
     */
    class [[eosio::contract("eosio.wrap")]] wrap : public contract {
       public:
@@ -25,18 +20,19 @@ namespace eosio {
           * Execute action.
           *
           * Execute a transaction while bypassing regular authorization checks.
+          * 
+          * Preconditions:
+          * - Requires authorization of eosio.wrap which needs to be a privileged account.
           *
+          * Postconditions:
+          * - Deferred transaction RAM usage is billed to 'executer'          *
+          * 
           * @param executer - account executing the transaction,
           * @param trx - the transaction to be executed.
-          *
-          * @pre Requires authorization of eosio.wrap which needs to be a privileged account.
-          *
-          * @post Deferred transaction RAM usage is billed to 'executer'
           */
          [[eosio::action]]
          void exec( ignore<name> executer, ignore<transaction> trx );
 
          using exec_action = eosio::action_wrapper<"exec"_n, &wrap::exec>;
    };
-   /** @}*/ // end of @defgroup eosiowrap eosio.wrap
 } /// namespace eosio

docs/01_key-concepts/01_system.md

@@ -0,0 +1,24 @@
+---
+content_title: System contracts, system accounts, privileged accounts
+link_text: System contracts and 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.
+
+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.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.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.|
+|eosio.ram|No|No|The account that keeps track of the SYS balances based on users actions of buying or selling RAM.|
+|eosio.ramfee|No|No|The account that keeps track of the fees collected from users RAM trading actions: 0.5% from the value of each trade goes into this account.|
+|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.| 

docs/01_key-concepts/02_ram.md

@@ -0,0 +1,12 @@
+---
+content_title: RAM as resource
+link_text: RAM as resource
+---
+
+RAM is the memory, storage space, where the blockchain stores data. If your contract needs to store data on the blockchain, like in a database, then it can store it in the blockchain's RAM using either a `multi-index table`, which is explained [here](https://developers.eos.io/eosio-home/docs/data-persistence) or a `singleton`, its definition can be found [here](https://github.com/EOSIO/eosio.cdt/blob/master/libraries/eosiolib/singleton.hpp) and a sample of its usage [here](https://github.com/EOSIO/eosio.contracts/blob/master/contracts/eosio.system/include/eosio.system/eosio.system.hpp).
+
+The EOSIO-based blockchains are known for their high performance, which is achieved also because the data stored on the blockchain is using RAM as the storage medium, and thus access to blockchain data is very fast, helping the performance benchmarks to reach levels no other blockchain has been able to.
+
+RAM is a very important 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 1KiB (1024 bytes) per day, thus increasing constantly the supply of RAM for the price of RAM to not grow too high because of the increased demand from blockchain applications; also RAM it is used in executing many actions that are available on the blockchain, creating a new account 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).

docs/01_key-concepts/03_cpu.md

@@ -0,0 +1,6 @@
+---
+content_title: CPU as resource
+link_text: CPU as 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.

docs/01_key-concepts/04_net.md

@@ -0,0 +1,6 @@
+---
+content_title: NET as resource
+link_text: NET as 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.