Horusfeathers patch 1

README.md

@@ -1,4 +1,4 @@
 # documentation
 
-This document is a tutorial that wants to offer Java developers all the needed information to build a complete blockchain application on the Horizen sidechain system.
-Apart from Java competency, this tutorial assumes that the reader has at least a high level understanding of how blockchain-based distributed software works. 
+This is a tutorial that provides Java developers all the information required to build a complete blockchain application on the Horizen sidechain system.
+This tutorial assumes that the reader has advanced java experience and an intermediate understanding of how blockchain-based distributed software works. 

docs/conf.py

@@ -20,12 +20,12 @@
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #sys.path.insert(0, os.path.abspath('.'))
 
-# -- General configuration ------------------------------------------------
+# -- General Configuration ------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
 #needs_sphinx = '1.0'
 
-# Add any Sphinx extension module names here, as strings. They can be
+# Add any Sphinx extension module names here as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
@@ -45,7 +45,7 @@
 # The encoding of source files.
 #source_encoding = 'utf-8-sig'
 
-# The master toctree document.
+# The master doctree document.
 master_doc = 'index'
 
 # General information about the project.
@@ -75,7 +75,7 @@
 # directories to ignore when looking for source files.
 exclude_patterns = ['_build']
 
-# The reST default role (used for this markup: `text`) to use for all
+# The RST default role (used for this markup: `text`) to use for all
 # documents.
 #default_role = None
 
@@ -106,8 +106,8 @@
 # a list of builtin themes.
 html_theme = 'default'
 
-# Theme options are theme-specific and customize the look and feel of a theme
-# further.  For a list of options available for each theme, see the
+# Theme options are theme-specific and customize the look and feel of a theme.
+# For a list of options available for each theme, see the
 # documentation.
 #html_theme_options = {}
 
@@ -127,7 +127,7 @@
 html_logo = 'images/Horizen_UBD_white.svg'
 
 # The name of an image file (within the static path) to use as favicon of the
-# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# docs.  This file should be a Windows icon file (.ico) being  16x16 or 32x32
 # pixels large.
 html_favicon = 'images/Horizen_favicon_32x32.png'
 
@@ -197,7 +197,7 @@
 htmlhelp_basename = 'Horizen Sidechains SDK'
 
 
-# -- Options for LaTeX output ---------------------------------------------
+# -- Options for LaTeX Output ---------------------------------------------
 
 latex_elements = {
 # The paper size ('letterpaper' or 'a4paper').
@@ -239,7 +239,7 @@
 #latex_domain_indices = True
 
 
-# -- Options for manual page output ---------------------------------------
+# -- Options for Manual Page Output ---------------------------------------
 
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
@@ -252,7 +252,7 @@
 #man_show_urls = False
 
 
-# -- Options for Texinfo output -------------------------------------------
+# -- Options for Texinfo Output -------------------------------------------
 
 # Grouping the document tree into Texinfo files. List of tuples
 # (source start file, target name, title, author,

docs/introduction/03-Cross-chain-transfer-protocol.rst

@@ -6,19 +6,20 @@ The Cross-Chain Transfer Protocol (“CCTP”) defines the communication between
 
 At a high level, it defines two basic operations:
 
-   * **Forward Transfer**
-   * **Backward Transfer**
+   * **forward transfer**
+   * **backward transfer**
 
-While all Sidechains know and follow the mainchain, which is an established and stable reality, mainchain needs to be made aware of the existence of every sidechain. So, Sidechains first must be declared in the mainchain.
 
-We can declare a new Sidechain by using the following RPC command:
+While all sidechains know and follow the mainchain, which is an established and stable reality, the mainchain needs to be made aware of the existence of every sidechain. So, sidechains must be declared in mainchain first.
+
+We can declare a new sidechain by using the following RPC command:
 
 .. code:: Bash
 
    sc_create withdrawalEpochLength "address" amount "verification key" "vrfPublickKey" "genSysConstant"
 
-The command specifies where the first forward transfer coins are sent, as well as the epoch length, that defines the frequency, in blocks, of the backward transfers submissions (see the “backward transfers” paragraph below). The sc_create command also includes the cryptographic key to receive coins back from a Sidechain. The verification key guarantees that the received coins were processed according to a matching proving system.
-As a consequence of the sidechain declaration command, a unique sidechain id will be assigned to that sidechain, that from that moment on can be used for every operation related to that specific sidechain:
+The command specifies where the first forward transfer coins are sent, as well as the epoch length that defines the frequency - in blocks - of the backward transfers submissions (see the “backward transfers” paragraph below). The sc_create command also includes the cryptographic key to receive coins back from a sidechain. The verification key guarantees that the received coins were processed according to a matching proving system.
+As a consequence of the sidechain declaration command, a unique sidechain id will be assigned to that sidechain, from that moment on can be used for every operation related to that specific sidechain:
 
 .. code:: json
 
@@ -32,17 +33,21 @@ As a consequence of the sidechain declaration command, a unique sidechain id wil
 Forward Transfer
 ================
 
-A forward transfer sends coins from the mainchain to a sidechain. The Horizen Mainchain supports a “Forward Transfer” transaction type, that specifies the sidechain destination (sidechain id and receiver address) and the amounts of ZEN coins to be sent. From a mainchain perspective, the transferred coins are destroyed, they are only represented in the total balance of that particular sidechain.
-On the Sidechain side, the SDK provides all the functionalities that support Forward Transfers, so that a transferred amount is “converted” into a new Sidechain Box.
+
+A forward transfer sends coins from the mainchain to a sidechain. The Horizen mainchain supports a forward transfer transaction type, that specifies the sidechain destination (sidechain id and receiver address) and the amounts of ZEN to be sent. From a mainchain perspective, the transferred coins are destroyed, they are only represented in the total balance of that particular sidechain.
+On the sidechain side, the SDK provides all the functionalities that support forward transfers, so that a transferred amount is “converted” into a new sidechain box.
+
 
 Backward Transfer
 =================
 
 A backward transfer moves coins back from a sidechain to a mainchain destination.
-A Backward Transfer is initiated by a **Withdrawal Request** which is a sidechain transaction issued by the coin owners. The request specifies the mainchain destination, and the amount. More precisely, the withdrawal request owner will create a WithdrawalRequestBox that destroys the specified amount of coins in a sidechain. This is not enough to move those coins back to the mainchain though: we need to wait the end of the withdrawal epoch, when all the coins specified in that epoch’s Withdrawal Requests are listed in a single Certificate, that is the propagated to the mainchain.
-The Certificate includes a succinct cryptographic proof that the rules associated with the declared verifying key have been respected. Certificates are processed by the mainchain consensus, which recreates the coins as specified by the certificate, only checking that the proof verifies, and that the coins received by a sidechain are not  more than the amount sent to it.
+
+A backward transfer is initiated by a **withdrawal request** which is a sidechain transaction issued by the coin owner. The request specifies the mainchain destination, and the amount. More precisely, the withdrawal request owner will create a WithdrawalRequestBox that destroys the specified amount of coins in a sidechain. This is not enough to move those coins back to the mainchain though. We need to wait the end of the withdrawal epoch, when all the coins specified in that epoch’s withdrawal requests are listed in a single certificate, that is the propagated to the mainchain.
+The certificate includes a succinct cryptographic proof that the rules associated with the declared verifying key have been respected. Certificates are processed by mainchain consensus, which recreates the coins specified by the certificate, only checking that the proof verifies and that the coins received by a sidechain are not  more than the amount sent to it.
+
 
 Summary
 =======
 
-The Cross-Chain Transfer Protocol assumes that proofs are generated with a specific proving system, but does not limit the logic of the computation that is proven by the proving system (the “circuit”). So, sidechain developers could implement the proving system that they want and need, to prove the legitimacy of backward transfers. The examples provided with the SDK implement a sample proving system, that proves that the certificate was signed by a minimum number of certifiers, whose key identities were declared at sidechain creation time. This is just a demo circuit; production sidechains require robust circuits (see the Latus recursive model in the Zendoo paper).
+The Cross-Chain Transfer Protocol assumes that proofs are generated with a specific proving system, but does not limit the logic of the computation that is proven by the proving system (the “circuit”). So, sidechain developers could implement the proving system that they want and need, to prove the legitimacy of backward transfers. The examples provided with the SDK implement a sample proving system, that proves that the certificate was signed by a minimum number of certifiers, whose key identities were declared at sidechain creation time. This is just a demo circuit, production sidechains require robust circuits (see the Latus recursive model in the Zendoo paper).