Merge pull request #31 from GenesisKernel/develop

Sync master with develop

source/concepts/blockchain-basics.rst

@@ -0,0 +1,68 @@
+Blockchain in general terms
+###########################
+
+This section explains, in general terms, how blockchain technology works. 
+
+Blockchain
+==========
+
+A blockchain is a distributed *ledger* of *operations* performed on a *global state* by *nodes* of a blockchain network.
+
+The ledger is cryptographically protected from falsification. Any attempts to retrospectively alter the ledger require significant effort and are evident to the blockchain network members.
+
+
+Nodes
+=====
+
+Members of a blockchain network are called *nodes*. Each node owns a copy of the global state and a copy of the ledger. There is no central server or authority that holds master copies. Instead, nodes use the ledger to agree upon what the global state must be.
+
+
+Global state
+============
+
+The *global state* is a set of data. Most common implementation of a global state is a database. 
+
+The global state is mutable. It can be changed with operations that nodes write to the ledger. For example, a database entry with the asset owner name can be changed, so that a new person owns the asset.
+
+
+Ledger
+======
+
+The *ledger* (or *blockchain*) is a list of operations that were performed on a global state. 
+
+The ledger is immutable. The blockchain technology makes it so that operations written to the ledger cannot be modified or removed at a later date. For example, there is no way to back-out the operation that states that the asset owner name was changed at some point.
+
+
+Transactions and blocks
+=======================
+
+The operations that nodes write to the ledger are called *transactions*.
+
+Every blockchain network node can write transactions to the ledger. When a node writes a transaction to the ledger, it signs the transaction with node's private key. 
+
+.. note::
+
+	For the sake of simplicity, it is assumed here that transactions are generated by nodes and are signed with a node's private key. This is a basic transaction flow. In |platform|, the transaction flow is more complex, as explained in :doc:`/concepts/blockchain-layers`.
+
+A selected node (*validating node*) checks that the transaction is valid and can be written to the ledger. If it is so, this node generates a new *block* in the blockchain and signs it. A block usually holds several transactions.
+
+
+This block is passed to other network nodes that validate the block. If the block is valid, they include it in their ledger and perform all the transactions from this block on their copy of the global state. Once all nodes have validated the block, the network have reached *consensus*. This block is considered valid by all the nodes of a blockchain network, and the global state is the same for all the nodes.
+
+.. note::
+
+    |platform| uses a proof-of-authority consensus mechanism. Only the selected nodes called *validating nodes* can generate new blocks. 
+
+    Other blockchain-based projects use different consensus mechanisms. For example, bitcoin cryptocurrency uses prof-of-work mechanism, where a node that solved a complex equation is awarded a right to create a new block. 
+
+
+Example
+=======
+
+For example, three friends own a collection of expensive automobiles, which are stored in a hangar. Each friend has a list of automobiles in the hangar and a log of operations for the hangar. 
+
+In blockchain terms, three friends are network nodes, the hangar is a global state, the automobiles in the hangar are data stored in the global state, the log of operations is a ledger, and entries in this log are transactions.
+
+Now, for example, one of the friends buys a new automobile and decides to add it to the hangar. He sends a message to his friends. The message says that he has added a Buick 1961 to the hangar. One of the friends (appointed for this task) validates this claim, for example, by contacting the hangar personnel and checking if the new automobile is really there. If this message is valid, he adds a new entry to his copy of the operations log and adjusts his list of automobiles. He also tells all other friends what he has changed in his operations log. Other friends check that the change was correct and adjust their list of automobiles in the hangar. When all three friends have accepted the change in their ledger and adjusted their list of automobiles, the change was finalized.
+
+In blockchain terms, one of the network nodes generated a transaction and sent it to other nodes. One of the validating nodes then validated this transaction and added a new block to the ledger. This block was sent to other network nodes who validated it, added it to the blockchain, and changed their global state accordingly. Once all nodes have made the changes to the ledger and to the global state, it is said that the network have reached the consensus.

source/concepts/blockchain-layers.rst

@@ -0,0 +1,154 @@
+.. -- Conditionals Genesis / Apla -------------------------------------------------
+
+.. backend GitHub repo name and link
+.. |backend_gh| replace:: `go-genesis`_
+.. _go-genesis: https://github.com/GenesisKernel/go-genesis 
+.. .. |backend_gh| replace:: `go-apla`_
+.. .. _go-apla: https://github.com/AplaProject/go-apla
+
+
+.. frontend GitHub repo name and link
+.. |frontend_gh| replace:: `genesis-front`_
+.. _genesis-front: https://github.com/GenesisKernel/genesis-front   
+.. .. |frontend_gh| replace:: `apla-front`_
+.. .. _apla-front: https://github.com/AplaProject/apla-front 
+
+
+
+About |platform| blockchain
+###########################
+
+This section explains how |platform| works with blockchain. 
+
+
+Tip of the iceberg
+==================
+
+If you are interested in developing |platform| apps, using them, or managing ecosystems, then you probably don't need to know anything about the |platform| blockchain at all.
+
+In |platform|, the blockchain and the blockchain network are hidden from ecosystem members, administrators, and even app developers. Instead, |platform| provides interfaces for all these groups of users. These interfaces provide access to the top layer of a blockchain: its tamper-proof distributed *global state*. 
+
+
+App developers
+--------------
+
+In technical terms, the *global state* is a set of data. |platform|'s implementation of its global state is a database. From the app developer standpoint, applications interact with this database by querying, inserting, and updating the database tables.
+
+|platform| applications are a collection of contracts and pages that interact with tables. 
+
+Under the hood, contracts are executed by writing transactions to the blockchain. These transactions invoke contract code, which is executed by the blockchain network nodes, which leads to changes in the global state, the database. For an app developer, a contract is a function. When it is executed, data is written to the database. Pages are like scripts. Page code is a set of :doc:`Protypo </topics/templates2>` functions. Some of these functions display page elements, other fetch data from the database. No knowledge of transactions, block generation or consensus algorithms is required from an application developer to work with |platform| blockchain.
+
+
+Ecosystem members
+-----------------
+
+In |platform|, apps written by app developers work inside autonomous software environments called *ecosystems*. An ecosystem typically serves a certain purpose and combines many apps created to support different aspects of this purpose.
+
+To get access to the apps of an ecosystem, a user must become an *ecosystem member*. One user can be a member of many ecosystems.
+
+Ecosystem members can view and modify the database from application pages, like they would do in a common web application: by filling forms, pressing buttons, and navigating pages.
+
+
+Ecosystem and platform apps
+---------------------------
+
+Apps can be divided by scope into *ecosystem apps* and *platform apps*.
+
+*Ecosystem apps* implement some certain functionality or business process specific to an ecosystem. An ecosystem app is available only in its ecosystem.
+
+*Platform apps* are available in all ecosystems. Any app can be developed as a platform app. |platform| developers provide platform apps that support core functionality for ecosystem governance, such as apps for votings, notifications, and ecosystem member roles management.
+
+.. todo::
+
+    Move this to ecosystem intro
+
+
+Under the hood
+==============
+
+The layers
+----------
+
+Under the top layer that is visible to ecosystem members and app developers, lies the "engine" of |platform|, its node network and blockchain protocols.
+
+You can think of |platform| as having several layers: 
+
+    - User interfaces layer
+
+        Ecosystem members interact with applications via pages and page elements.
+
+    - Apps layer
+
+        App developers interact with global state (database tables) via contract and page code.
+
+    - Global state layer
+
+        Global state (database) is updated and synchronized based on the operations written to the distributed ledger of operations (blockchain).
+
+    - Blockchain layer
+
+        Distributed ledger of operations is updated with new blocks. New blocks hold the operations (transactions) that must be performed on the global state.
+
+    - Node network layer
+
+        Network nodes implement |platform| blockchain protocol. They distribute transactions in the node network, validate these transactions and generate new blocks. Blocks are, in turn, distributed and validated by network nodes. The distributed ledger is kept synchronized for all nodes in a network. If conflicts occur, nodes agree upon which block chains are considered valid and rollback the invalid block chains.
+
+    - Transactions layer
+
+        Transactions that are basis for block generation and blockchain protocol itself are a result of actions performed at the top layer. As explained in :ref:`implementation`, transactions are automatically generated by |platform| frontend, Molis client. 
+
+        When a user or a developer makes an action such as clicking a button on a page or executing a contract from the code editor, Molis converts this action into a transaction and sends it to the network node that it is connected to. 
+
+
+Thus, the top layer is connected to the bottom layer and the transaction flow goes in the opposite direction: 
+
+    - A user action in the user interface creates a transaction.
+
+    - The transaction gets included in a block.
+
+    - The block is included in the blockchain.
+
+    - Changes in the blockchain cause changes in the global state, the action is applied to the database.
+
+    - The database changes are displayed in the app.
+
+
+.. _implementation:
+
+The implementation
+------------------
+
+.. todo::
+
+    When detailed docs about implementation (daemons) are ready, link them here and to the blockchain chapter below. 
+
+
+Two main components of |platform| are its backend, |backend_gh|, and Molis client, |frontend_gh|.
+
+
+Molis client: 
+
+    - Provides a user interface for |platform|.
+
+    - Provides an IDE for app development.
+
+    - Stores private keys of user accounts and performs authorization.
+
+    - Requests app page data from the database, and displays app pages to users.
+
+    - Sends transactions to the backend via :doc:`REST API</reference/api2>`. 
+
+        Transactions are created automatically for user actions that require a transaction. For example, when an app developer executes a contract from the IDE, Molis converts this action into a transaction.
+
+
+The backend: 
+
+    - Keeps the global state (the database) of the node.
+    - Implements all |platform| blockchain protocols.
+    - Executes contract code in a :doc:`virtual machine </topics/vm>`.
+    - Executes page code in a :doc:`template engine </topics/templates2>`. The result is page data that can be used by Molis client.
+    - Implements :doc:`REST API</reference/api2>`.
+
+.. todo::
+
+    Make the templates link refer to a more specific heading: Interface Template Engine.