Added example at end of step-by-step

Author: jkbbwr

source/blockchain.rst

@@ -3,21 +3,21 @@
 Blockchain
 ==========
 
-The Credits Blockchain Framework as an application is a distributed software service that runs across
+The Credits Blockchain Framework as an application is a distributed software service that runs on
 multiple servers called :ref:`Nodes <architecture-blockchain-node>`. Every node holds a copy
 of the Credits blockchain as a data structure. This data structure consists of cryptographically
 connected :ref:`Blocks <blockchain-block>` and :ref:`States <blockchain-state>`. New blocks and
-states are added to the blochchain by :ref:`applying transactions <blockchain-applying-transactions>`
+states are added to the blockchain by :ref:`applying transactions <blockchain-applying-transactions>`
 and electing the best blocks through node :ref:`consensus <blockchain-consensus>`.
 
 .. _blockchain-state:
 
 Blockchain State
 ^^^^^^^^^^^^^^^^
 
-State is simply just a key value map of data. Credits Framework has one global state object,
+The State is simply just a key-value map of data. Credits Framework has one global state object,
 this is comprised of many different smaller states. There can be multiple different
-substates that can contain any information, all that is important is that the key of the
+substates that can contain any information, all that is important is that every key in the
 state is a string. An example of a traditional state as shown:
 
 .. code-block:: json
@@ -36,7 +36,7 @@ state is a string. An example of a traditional state as shown:
 
 In the example above there is a ``balances`` state and a ``loans`` state, these states
 can have many arbitrary number of key value pairs. Usually credits addresses are used
-as the key in a state but this doesn't always need to be the case. State is ordered
+as the key in a state but this doesn't always need to be the case. The State is ordered
 by insertion order and is hashed to provide a state hash.
 
 
@@ -45,11 +45,11 @@ by insertion order and is hashed to provide a state hash.
 Blockchain Block
 ^^^^^^^^^^^^^^^^
 
-In the simplest terms a block is just a collection of :ref:`transactions <transaction>`.
+In the simplest terms, a block is just a collection of :ref:`transactions <transaction>`.
 Blocks are formed by taking valid unconfirmed transactions from the internal transactions
 pool and making a block that contains these transactions. Once the block is formed
 it is distributed in the network and nodes can decide to vote and commit to this block.
-A block also contains information of the state of the world that it is built on. By
+A block also contains information on the state of the world that it is built on. By
 referencing the state, a node can take the block, check that it is starting in the same
 place as the creator of the block and then apply the transactions.
 
@@ -60,11 +60,11 @@ Onboarding transactions
 ^^^^^^^^^^^^^^^^^^^^^^^
 
 Onboarding transaction, transform or proof means generally to get it accepted into the
-node's unconfirmed transactions pool. In case of PaaS deployment the onboarding happens
+node's unconfirmed transactions pool. In case of PaaS deployment, the onboarding happens
 by sending the marshalled transaction to the node HTTP API. In other more complex
 deployments the HTTP API gateway can be replaced with other transport, e.g. TCP socket,
 CLI interface, RPC interface etc. Onboarding here serves as a transport agnostic term
-for act of accepting transaction into the node.
+for the act of accepting transaction into the node.
 
 
 .. _blockchain-applying-transactions:
@@ -115,17 +115,51 @@ Any :ref:`Applicable <interfaces-applicable>` object should be able to apply its
 
 .. _blockchain-consensus:
 
-Blockchain Consensus
+Blockchain consensus
 ^^^^^^^^^^^^^^^^^^^^
 
+There are many different Consensus mechanisms. Two of the common mechanisms that are talked about in
+blockchain are Proof of Work and Proof of Stake.  
+
+
+Proof of Work
+-------------
+Proof of work is the more commonly talked about mechanism for achieving consensus. Proof of work 
+requires that a contributor do a deterministically difficult amount of work that is then easy to check. 
+Bitcoin does this by making miners hash until they get the longest string of zeroes this 
+artificially slows down block creation in the bitcoin network. 
+Anyone can mine blocks but given the current normalize difficulty it takes a long time for 
+non-specialized hardware to mine a valid block. Think of this as like a lottery,
+everyone is turning a crank and one person is rewarded every x minutes.
+
+
+Proof of Stake
+--------------
+
+Proof of stake is far more like a traditional election model. Everyone locks up some value as a promise of their 
+good intentions inside the system and then there are fixed voting rounds where each person votes using the weight of the value locked 
+up. In an example both Alice and Bob stake 50 value into the system, they both have equal votes but neither have
+majority. Both together can vote and provide majority for confirming a block. Anyone can propose a block but only
+those with stake can vote.
+
+
+Credits consensus
+-----------------
+
+Consensus in Credits is at its heart Proof of Stake. Validators bond value against as a promise of their honest intentions.
+Validators attempt to create valid blocks of unconfirmed transactions. These blocks are distributed between the validators.
+Each validator picks a block to vote on (currently this is the first valid block seen) and then tells the network of their
+intention to vote for this block. Once enough votes have been cast for that block to have a winning concensus everyone announces
+their intention to commit to that block. With enough voters committed to a block it becomes ratified history and the state of the 
+world is upgraded.
 
 .. _blockchain-structure:
 
 Blockchain structure
 ^^^^^^^^^^^^^^^^^^^^
 
-Building from states and blocks the chain can be created. Because credits
-has intermediate states its not a direct link from block to block, instead a
+Building from states and blocks the chain can be created. Because Credits blockchain
+has intermediate states it's not a direct link from block to block, instead, a
 block is formed from the current state, and then the application of that block to
 current state forms the next state.
 
@@ -234,6 +268,7 @@ Leaving it with a final state of:
         }
     }
 
-From here onwards other transactions can happen, further mutating global state and adding blocks
-to the chain. The process will run indefinitely as long as there is a quorum of nodes in the
-network and new valid transactions are coming in.
+From here onwards other transactions can happen, further mutating global state
+and adding new blocks to the chain. The process will run indefinitely as
+long as there is a quorum of nodes in the network and new valid transactions
+are coming in.

source/getting_started.rst

@@ -22,7 +22,7 @@ G-Cloud platform onboarding
 
 In order to sign-up for our G-Cloud offering, you will need to go through our
 :ref:`onboarding process <gcloud-onboarding-process>`, including verifying your
-organization as a qualified UK government agency.
+organisation as a qualified UK government agency.
 
 
 How to interact with the system

source/interfaces.rst

@@ -8,8 +8,8 @@ Interfaces
 Marshallable
 ^^^^^^^^^^^^
 
-The Marshallable interface provides the nessasary methods to convert fully
-realised instances into more primative maps and to reverse the process by
+The Marshallable interface provides the necessary methods to convert fully
+realised instances into more primitive maps and to reverse the process by
 converting these maps back into instances.
 
 FQDN
@@ -37,8 +37,8 @@ unmarshalling process to locate an associated Class to instanciate.
 marshall
 --------
 
-Marshalling is the process of converting a instance into a map of primative
-variables which can be then serialized. This allows libraries like ``json`` and
+Marshalling is the process of converting an instance into a map of primitive
+variables which can be then serialised. This allows libraries like ``json`` and
 ``msgpack`` to use their ``dumps`` methods to convert the output of
 ``marshall`` to a string or series of bytes suitable for transport over the
 network. The ``fqdn`` used by the framework to resolve the implementor's class
@@ -59,7 +59,7 @@ Marshallable object should also marshall any of it's subcomponents.
 unmarshall
 ----------
 
-Once a marshalled object has been recieved, the unmarshall method may be used to
+Once a marshalled object has been received, the unmarshall method may be used to
 reverse the process. Like marshalling, unmarshalling should also be performed on
 all subcomponents to fully resolve the object.
 
@@ -82,8 +82,8 @@ all subcomponents to fully resolve the object.
 Applicable
 ^^^^^^^^^^
 
-The ``Applicable`` interface provides the nessasary methods for objects to
-perform manipulations against state.
+The ``Applicable`` interface provides the necessary methods for objects to
+perform manipulations against the state.
 
 verify
 ------
@@ -108,7 +108,7 @@ apply
 -----
 
 The ``apply`` method should manipulate and return state. In the event of an
-error, return an errornous Result.
+error, return an erroneous Result.
 
 .. code-block:: python
    :linenos:
@@ -137,7 +137,7 @@ sign
 The ``sign`` method should accept a ``credits.key.SigningKey`` and sign some
 sort of challenge stored within the implementor. Then return a new instance of
 the implementor with both the signature and the associated
-``credits.key.VerifyingKey``. These additional variables can then for example
+``credits.key.VerifyingKey``. These additional variables can then, for example,
 be used in conjunction with the ``Applicable.verify`` method to check if the
 implementor has been signed.
 

source/step_by_step.rst

@@ -8,7 +8,7 @@ To create a custom permissioned blockchain with Credits framework you will
 need to go through these steps:
 
  - create required transforms, proofs and transactions
- - test and verify validity of the code in your local dev environment
+ - test and verify the validity of the code in your local dev environment
  - start your private blockchain network and upload the code
  - create your client application using the same transactions
  - hook your client to the network via node API and start transacting on the blockchain
@@ -19,13 +19,13 @@ need to go through these steps:
 Create transforms and other modules
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-In the simplest scenario you will need to only implement your transforms. You
+In the simplest scenario, you will need to only implement your transforms. You
 can use ``SingleKeyProof`` provided in the Common library as a default way to
 prove transaction validity with one signing key per signature. And your
 transaction in the simplest scenario can also be the default ``Transaction``
 provided in the common library.
 
-In simplest case you may have just one transform. The transform must implement
+So in this simplest case, you may have just one transform. The transform must implement
 ``credits.transform.Transform``. You can find more details on implementing
 transforms and actual examples in :ref:`Transform <transform>` documentation.
 
@@ -85,9 +85,9 @@ Note that ``check_transform`` is not a substitute for standard Unit Testing,
 you should also perform standard unit testing of your Transform's ``verify()``
 and ``apply()`` methods to check that all potential outcomes are covered.
 
-You can find a full example of Transform creation and testing in checktransform.py_.
+You can find a full example of Transform creation and testing in check_transform.py_.
 
-.. _checktransform.py: https://github.com/CryptoCredits/credits-common/blob/develop/examples/checktransform.py
+.. _check_transform.py: https://github.com/CryptoCredits/credits-common/blob/develop/examples/check_transform.py
 
 
 .. _step-by-step-get-network-upload:
@@ -97,18 +97,18 @@ Get a blockchain network and upload your code
 
 Once your modules are written and tested locally - it's time to deploy a test
 blockchain network and see it in action. The easiest way to do this is to use
-our public PaaS, which is at the moment avaialable for free. You can register
+our public PaaS, which is at the moment available for free. You can register
 via the REST API and get a running network in few HTTP requests.
 
 If you're working for a government agency and looking to use our GCloud PaaS API - the process is
 essentially same, except that your PaaS account will be disabled by default until we'll get you
 through the formal onboarding process.
 
 The most complicated option would be to get Credits framework running on your own infrastructure.
-This is technically possible and not that complex, since we ship it in handy prebuilt Docker containers,
+This is technically possible and not that complex since we ship it in handy prebuilt Docker containers,
 but since at the moment Credits Core is a proprietary software - you will have to go through sales channel
-first and purchase license before we'll be able to hand the software to you.
-Also the PaaS registration and network bootstrap guide will not apply in this case.
+first and purchase a license before we'll be able to hand the software to you.
+Also, the PaaS registration and network bootstrap guide will not apply in this case.
 
 Below are the API call steps needed to register with public PaaS and create 
 a test blockchain network.
@@ -148,7 +148,7 @@ Patch token
 
 After creating the organisation you need to patch your token with rights
 definitions to be able to access it. By default you would probably want to
-add all permissions at once, however in more complex access cases you may
+add all permissions at once, however, in more complex access cases you may
 have different tokens with specific access rights configured on each.
 See full permissions list in the :ref:`Paas API<paas-api>`.
 
@@ -162,9 +162,10 @@ Create network
 
 Assuming you have already developed and tested locally your transforms
 you can now provide it to bootstrap your blockchain. Please notice that module
-inclusion is a path to local file. You need to supply the module contents unescaped
-and fully intact including the linebreaks to preserve validity of the Python source,
-so it's not possible to include it's contents directly into the ``curl`` call string.
+inclusion is a path to a local file. You need to supply the module contents unescaped
+and fully intact including the line breaks to preserve the validity of the
+Python source, so it's not possible to include it's contents directly into
+the ``curl`` call string.
 
 .. code-block:: bash
 
@@ -207,11 +208,11 @@ Once your network is up and running - you can create the client side application
 for it. Essentially you will need to use the same modules that were uploaded to
 the network, but incorporate it into the client side application.
 
-Of course the bulk of your clientside application is something we cannot
+Of course, the bulk of your clientside application is something we cannot
 define, it may be a web system, a mobile app, an IoT device etc.
-However the general requirements will be that it has to be able to
+However, the general requirements will be that it has to be able to
 persistently store client's keys, and will conform to the
-Transforms and Proofs interaces uploaded into the blockchain.
+Transforms and Proofs interfaces uploaded into the blockchain.
 
 As an example here is the simple Python script that implements
 generating user's keys, dumping those to disk (persistence), creating valid
@@ -220,12 +221,49 @@ Transaction and sending it to the node's URL provided.
 
 .. code-block:: python
     :linenos:  
-    print("hi")
 
+    #!/usr/bin/env python
+    # -*- coding: utf-8 -*-
+    import requests
+    from credits.key import ED25519SigningKey
+    from credits.address import CreditsAddressProvider
+    from credits.proof import SingleKeyProof
+    from credits.transaction import Transaction
 
-You can also find this example in the blockchain_client.py_.
+    # create a key for Alice using default key provider
+    alice_key = ED25519SigningKey.new()
 
-.. _blockchain_client.py: https://github.com/CryptoCredits/credits-common/blob/develop/examples/blockchain_client.py
+    # create Alice's address using default address provider
+    alice_address = CreditsAddressProvider(alice_key.to_string()).get_address()
+
+    # Saving the key to disk by marshalling it
+    with open("alice_key.json", "w") as out:
+        out.write(alice_key.marshall()
+
+    # Loading it would be also simple when you'll need it
+    # with open("alice_key.json") as keyfile:
+    #    payload = json.load(keyfile)
+    #    alice_key = ED25519SigningKey.unmarshall(None, payload)
+
+    # create transform to send credits from Alice to Bob
+    transform = BalanceTransform(amount=100, addr_from=alice_address, addr_to="bob_address")
+
+    # sign the needed proof with Alice' key
+    proof = SingleKeyProof(alice_address, 1, transform.get_challenge()).sign(alice_key)
+
+    # form a transaction
+    transaction = Transaction(transform, {alice_address: proof})
+
+    # POST your transaction to the node in your network
+    requests.post("https://public.credits.works/api/v1/node/<your_node_name>/api/v1/transaction", 
+        headers={"Authorization": "<your_api_key>"},        
+        data={"transaction": json.dumps(transaction.marshall())}
+    )
+
+
+You can also find this example in the sample_client.py_.
+
+.. _sample_client.py: https://github.com/CryptoCredits/credits-common/blob/develop/examples/sample_client.py
 
 
 .. _step-by-step-connect-and-start:
@@ -234,7 +272,7 @@ Connect client application to the blockchain
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Once the application is written and deployed you can start transacting
-on the blockchain. If everything is done correcly before - nothing blockchain
-specific is needed at this step.
+on the blockchain. If everything is done correctly in the previous steps
+- nothing blockchain specific is needed at this level.