Added information on EEA-compliant and Pantheon-extended privacy (#1765)

Signed-off-by: Adrian Sutton <adrian.sutton@consensys.net>

docs/Privacy/Explanation/Privacy-Groups.md

@@ -0,0 +1,67 @@
+description: Privacy
+<!--- END of page meta data -->
+
+# Privacy Groups 
+
+A privacy group is a group of nodes identified by a unique privacy group ID by Orion. Each private transaction is 
+stored in Orion with the privacy group ID.
+
+The Pantheon nodes maintain the public world state for the blockchain and a private state for each privacy group. 
+The private states contain data that is not shared in the globally replicated world state. Private transactions read 
+and write to the private world state for the privacy group, and read from the public world state.
+
+## Privacy Types 
+
+Pantheon implements two types of privacy: 
+
+* EEA-compliant privacy - private transactions include `privateFor` as the recipient.
+* Pantheon-extended privacy - private transactions include `privacyGroupId` as the recipient.
+
+Both privacy types create privacy groups and store private transactions with their privacy group in Orion. 
+
+![Privacy Groups](../../images/PrivacyGroups.png)
+
+!!! note
+    The Orion nodes are not shown above for clarity only.  To send private transactions, 
+    each Pantheon node must have an associated Orion node. 
+
+### EEA-compliant Privacy 
+
+In our privacy implementation complying with the [EEA Client Specification](https://entethalliance.org/technical-documents/)
+the group of nodes specified by `privateFrom`and `privateFor` form a privacy group and are given a unique 
+privacy group ID by Orion.  
+
+!!! example 
+    The diagram above illustrates two privacy groups enabling: 
+
+    * A, B, and C to send transactions that are private from D 
+    * A, C, and D to send transactions that are private from B 
+
+    Using EEA-compliant privacy, to send private transactions between A, B, and C, A initialises a contract in a private transaction with
+    B and C specified as the `privateFor` and A specified as the `privateFrom`. Initialising the contract 
+    creates a privacy group consisting of A, B, and C. For the ABC private state to remain consistent, 
+    A, B, and C must be included on transactions (as either `privateFrom` or `privateFor`) even if they are 
+    between two of the three parties.
+
+    To send private transactions between A, C, and D, C initialises a different contract in a private transaction with
+    A and D specified as the `privateFor` and C specified as the `privateFrom`. Initialising the contract 
+    creates a privacy group consisting of  A, C, and D. For the ACD private state to remain consistent, 
+    A, C, and D must be included on transactions (as either `privateFrom` or `privateFor`) even if they are 
+    between two of the three parties.
+
+
+### Pantheon-extended Privacy 
+ 
+In our extended privacy implementation, a privacy group is created using [`priv_createPrivacyGroup`](../../Reference/Pantheon-API-Methods.md#priv_createprivacygroup)
+and private transactions sent to the privacy group ID. 
+
+!!! example 
+    Using the same privacy groups as above. 
+
+    Using Pantheon-extended privacy, to send private transactions between A, B, and C, A creates a privacy 
+    group consisting of A, B, and C. The privacy group ID is specified when sending private transactions and 
+    A, B, and C are recipients of all private transactions sent to the privacy group. 
+
+    To send private transactions between A, C, and D, A creates a privacy group consisting of A, C, and D.
+    The privacy group ID of this group is specified when sending private transactions with A, C, and D 
+    as recipients. 

docs/Privacy/Explanation/Privacy-Overview.md

@@ -30,7 +30,7 @@ Private transactions have additional attributes to public Ethereum transactions:
 
 * `privateFrom` - Orion public key of transaction sender
 
-* `privateFor` - Orion public keys of transaction recipients 
+* `privateFor` - Orion public keys of transaction recipients or `privacyGroupId` - [Privacy group to receive transaction](Privacy-Groups.md) 
 
 * `restriction` - Private transactions are `restricted` or `unrestricted`:  
   
@@ -53,37 +53,4 @@ of the Orion nodes sending and receiving the transaction.
 
 !!! important 
     The mapping of Pantheon node addresses to Orion node public keys is off-chain.  That is, the 
-    sender of a private transaction must know the Orion node public key of the recipient.  
- 
-## Privacy Groups 
-
-The group of nodes specified by `privateFrom`and `privateFor` form a privacy group and 
-are given a unique privacy group ID by Orion. The private transaction is stored in Orion with the privacy group ID. 
-
-The Pantheon nodes maintain the public world state for the blockchain and a private state for each privacy group. 
-The private states contain data that is not shared in the globally replicated world state. Private transactions read 
-and write to the private world state for the privacy group, and read from the public world state.
-
-![Privacy Groups](../../images/PrivacyGroups.png)
-
-!!! note
-    The Orion nodes are not shown above for clarity only.  To send private transactions, 
-    each Pantheon node must have an associated Orion node. 
-
-!!! example 
-    The above illustrates two privacy groups enabling: 
-
-    * A, B, and C to send transactions that are private from D 
-    * A, C, and D to send transactions that are private from B 
-
-    To send private transactions between A, B, and C, A initialises a contract in a private transaction with
-    B and C specified as the `privateFor` and A specified as the `privateFrom`. Initialising the contract 
-    creates a privacy group consisting of A, B, and C. For the ABC private state to remain consistent, 
-    A, B, and C must be included on transactions (as either `privateFrom` or `privateFor`) even if they are 
-    between two of the three parties.
-
-    To send private transactions between A, C, and D, C initialises a different contract in a private transaction with
-    A and D specified as the `privateFor` and C specified as the `privateFrom`. Initialising the contract 
-    creates a privacy group consisting of  A, C, and D. For the ACD private state to remain consistent, 
-    A, C, and D must be included on transactions (as either `privateFrom` or `privateFor`) even if they are 
-    between two of the three parties.
+    sender of a private transaction must know the Orion node public key of the recipient.  

docs/Privacy/Explanation/Private-Transaction-Processing.md

@@ -19,7 +19,7 @@ Private transactions are processed as illustrated and described below.
 1. A private transaction is submitted using [eea_sendRawTransaction](../../Reference/Pantheon-API-Methods.md#eea_sendrawtransaction). 
 The signed transaction includes transaction attributes that are specific to private transactions: 
 
-    * `privateFor` specifies the list of recipients
+    * `privateFor` or `privacyGroupId` specifies the list of recipients
     * `privateFrom` specifies the sender
     * `restriction` specifies the transaction is of type [_restricted_](Privacy-Overview.md#private-transactions)
  
@@ -28,7 +28,7 @@ The signed transaction includes transaction attributes that are specific to priv
 1. The Private Transaction Handler sends the private transaction to Orion. 
 
 1. Orion distributes the private transaction directly (that is, point-to-point) to the Orion nodes specified 
-in the `privateFor` attribute. All Orion nodes specified in by `privateFor` and `privateFrom` store the transaction. 
+in `privateFor` or belonging to the privacy group identified by `privacyGroupId`. All recipient Orion nodes store the transaction. 
 The stored transaction is associated with the transaction hash and privacy group ID.
 
 1. Orion returns the transaction hash to the Private Transaction Handler.

mkdocs.yml

@@ -108,6 +108,7 @@ nav:
           - Use the web3.js-eea Client Library: Privacy/How-To/eeajs.md
         - Explanation:
           - Privacy Overview: Privacy/Explanation/Privacy-Overview.md
+          - Privacy Groups: Privacy/Explanation/Privacy-Groups.md
           - Processing Private Transactions: Privacy/Explanation/Private-Transaction-Processing.md
     - Permissioning:
         - Overview: Permissions/Permissioning-Overview.md