Enhanced permissions quickstart updates (#223)

* adding in a tutorial re enhanced permissions * updates * updates * updates * updates * updates * pr-review-fixes * fixing broken links * Add initial edits. Signed-off-by: bgravenorst <[email protected]> Co-authored-by: Joshua Fernandes <[email protected]>
Consensys · May 11, 2022 · 94a42a9 · 94a42a9
1 parent 6956f8d
commit 94a42a9
Show file tree

Hide file tree

Showing 4 changed files with 133 additions and 11 deletions.
diff --git a/docs/tutorials/contracts/account-funds-transfers.md b/docs/tutorials/contracts/account-funds-transfers.md
@@ -71,7 +71,7 @@ Before making the transaction, the script checks the balances of both accounts t
     }
     ```
 
-For reference, the Quorum Developer Quickstart provides an [example of a funds transfer script](https://github.com/ConsenSys/quorum-dev-quickstart/blob/master/files/goquorum/smart_contracts/scripts/eth_tx.js).
+For reference, the Quorum Developer Quickstart provides an [example of a funds transfer script](https://github.com/ConsenSys/quorum-dev-quickstart/blob/master/files/goquorum/smart_contracts/privacy/scripts/eth_tx.js).
 
 ## Using `eth_sendTransaction`
 

diff --git a/docs/tutorials/contracts/calling-contract-functions.md b/docs/tutorials/contracts/calling-contract-functions.md
@@ -14,7 +14,7 @@ Use the [Quorum Developer Quickstart](../quorum-dev-quickstart/index.md) to rapi
 ## Interact with public contracts
 
 This tutorial uses the
-[`SimpleStorage.sol`](https://github.com/ConsenSys/quorum-dev-quickstart/blob/master/files/common/smart_contracts/contracts/SimpleStorage.sol)
+[`SimpleStorage.sol`](https://github.com/ConsenSys/quorum-dev-quickstart/blob/master/files/common/smart_contracts/privacy/contracts/SimpleStorage.sol)
 contract:
 
 ```js
@@ -40,7 +40,7 @@ contract SimpleStorage {
 Once the contract is deployed, you can perform a read operation using the `get` function call and a write operation
 using the `set` function call.
 This tutorial uses the [web3js](https://www.npmjs.com/package/web3) library to interact with the contract.
-The Quorum Developer Quickstart provides a [full example of a public contract script](https://github.com/ConsenSys/quorum-dev-quickstart/blob/master/files/goquorum/smart_contracts/scripts/public_tx.js).
+The Quorum Developer Quickstart provides a [full example of a public contract script](https://github.com/ConsenSys/quorum-dev-quickstart/blob/master/files/goquorum/smart_contracts/privacy/scripts/public_tx.js).
 
 ### 1. Perform a read operation
 
@@ -90,7 +90,7 @@ This private contracts example uses the same `SimpleStorage.sol` contract as in
 [public contracts example](#interact-with-public-contracts), but it uses the
 [`eth_sendRawPrivateTransaction`](../../reference/api-methods.md#eth_sendrawprivatetransaction) method to interact with the contract.
 Both read and write operations are performed using the `eea_sendRawTransaction` API call.
-The Quorum Developer quickstart provides a [full example of a private contract script](https://github.com/ConsenSys/quorum-dev-quickstart/blob/master/files/goquorum/smart_contracts/scripts/private_tx_web3.js).
+The Quorum Developer quickstart provides a [full example of a private contract script](https://github.com/ConsenSys/quorum-dev-quickstart/blob/master/files/goquorum/smart_contracts/privacy/scripts/private_tx.js).
 
 ### 1. Perform a read operation
 

diff --git a/docs/tutorials/contracts/deploying-contracts.md b/docs/tutorials/contracts/deploying-contracts.md
@@ -22,7 +22,7 @@ Use the [Quorum Developer Quickstart](../quorum-dev-quickstart/index.md) to rapi
 
 You first need to create a smart contract.
 The following examples use the
-[`SimpleStorage.sol`](https://github.com/ConsenSys/quorum-dev-quickstart/blob/master/files/common/smart_contracts/contracts/SimpleStorage.sol)
+[`SimpleStorage.sol`](https://github.com/ConsenSys/quorum-dev-quickstart/blob/master/files/common/smart_contracts/privacy/contracts/SimpleStorage.sol)
 smart contract.
 
 Create a new file called `compile.js` with the following content:
@@ -223,7 +223,7 @@ As the example demonstrates, once the transaction `tx` is created, you can sign
 You can then serialize it and call `eth_sendSignedTransaction` to deploy the contract.
 
 For reference, the Developer Quickstart provides an
-[example of a public transaction script](https://github.com/ConsenSys/quorum-dev-quickstart/blob/master/files/goquorum/smart_contracts/scripts/public_tx.js).
+[example of a public transaction script](https://github.com/ConsenSys/quorum-dev-quickstart/blob/master/files/goquorum/smart_contracts/privacy/scripts/public_tx.js).
 
 ## Private contracts
 
@@ -302,7 +302,7 @@ transaction from Member1.
     ```
 
 For reference, the Developer Quickstart provides an
-[example of a private transaction script using web3](https://github.com/ConsenSys/quorum-dev-quickstart/blob/master/files/goquorum/smart_contracts/scripts/private_tx_web3.js).
+[example of a private transaction script using web3](https://github.com/ConsenSys/quorum-dev-quickstart/blob/master/files/goquorum/smart_contracts/privacy/scripts/private_tx.js).
 
 ### 3. Using `priv.generateAndSendRawTransaction`
 
@@ -370,4 +370,4 @@ Create a new file `private_tx_web3js_quorum.js`(or run the following commands in
 * `data` - Binary of the contract (in this example there's also a constructor initialization value appended to the binary value).
 
 For reference, the Developer Quickstart provides an
-[example of a private transaction script](https://github.com/ConsenSys/quorum-dev-quickstart/blob/master/files/goquorum/smart_contracts/scripts/private_tx.js).
+[example of a private transaction script](https://github.com/ConsenSys/quorum-dev-quickstart/blob/master/files/goquorum/smart_contracts/privacy/scripts/private_tx.js).
diff --git a/docs/tutorials/quorum-dev-quickstart/using-the-quickstart.md b/docs/tutorials/quorum-dev-quickstart/using-the-quickstart.md
@@ -17,6 +17,7 @@ The Quorum Developer Quickstart uses the GoQuorum Docker image to run a private
 * [Node.js and NPM](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) version 14 or higher
 * [Docker and Docker-compose](https://docs.docker.com/compose/install/)
 * [Truffle](https://www.trufflesuite.com/truffle) development framework
+* [Solc](https://github.com/ethereum/solidity/releases/tag/v0.5.17)
 * [`curl` command line](https://curl.haxx.se/download.html)
 * [MetaMask](https://metamask.io/)
 
@@ -244,10 +245,10 @@ Member3Quorum RPC: http://localhost:20004
 Member1Tessera: http://localhost:9083
 ```
 
-Navigate to the `smart_contracts` directory and deploy the private transaction:
+Navigate to the `smart_contracts/privacy` directory and deploy the private transaction:
 
 ```bash
-cd smart_contracts
+cd smart_contracts/privacy
 npm install
 node scripts/private_tx.js
 ```
@@ -370,7 +371,7 @@ Get the value of the contract to confirm that only Member1 and Member3 can see t
     ```
 
 Member2 can't read the state.
-Look in `smart_contracts/node scripts/private_tx.js` to confirm that `123` was the value set when the contract was updated.
+Look in `smart_contracts/privacy/node scripts/private_tx.js` to confirm that `123` was the value set when the contract was updated.
 
 ### Write to the contract with `set()`
 
@@ -414,6 +415,127 @@ All nodes are validating the same blockchain of transactions, with the private t
 in place of the transaction data, and only the parties to the private transactions can view and update the state of the
 private contracts.
 
+## Permissions
+
+GoQuorum supports two types of permissions:
+
+* [Basic permissioning](../../configure-and-manage/configure/permissioning/basic-permissions.md): Controls
+which peers can connect to a given node. This permissioning method is specific to a given node, and is
+configured by placing a file with a list of allowed peers (similar to `static-nodes.json`), called
+`permissioned-nodes.json` in the `data` directory of a GoQuorum node.
+* [Enhanced Permissions](../../concepts/permissions-overview.md#enhanced-network-permissioning) is a smart-contract-based
+permissioning model designed for enterprise-level needs and is applicable to all peers on the network.
+
+This example deploys permissioning contracts then uses API calls to set appropriate permissions.
+
+First we'll select a `GuardianAccount` or an admin account. In thies example we'll use the account of Validator1
+which has an address of `0xed9d02e382b34818e88b88a309c7fe71e65f419d`, and we'll connect to Validator1's RPC endpoint
+`http://127.0.0.1:21001`.
+
+The next step is to compile the contracts and deploy them in a specific order. The `contracts` directory
+(`smart_contracts/permissioning/contracts`) has two versions of contracts.
+
+* `version 1`: Permissioning rules are applied during transaction entry using the permissioning
+data stored in node memory.
+* `version 2`: Permissioning rules are applied at the during transaction entry
+and block minting using the data stored in the permissioning contracts. This tutorial uses `version 2` because it is
+more robust and suited for enterprise use.
+
+The folder contains the following contracts:
+
+* `PermissionsInterface.sol`: Provides an external interface, and internal proxy to `PermissionsImplementation.sol`.
+* `PermissionsImplementation.sol`: Contains the logic of the permissions-related functionality.
+* `OrgManager.sol`: Implements logic for all organization management functionality.
+* `AccountManager.sol`: Implements logic for all account management functionality.
+* `NodeManager.sol`: Contains the node management functionality.
+* `RoleManager.sol`：Implements logic for all role management functionality.
+* `VoterManager.sol`: Implements account voter and voting functionality.
+
+Navigate to the `smart_contracts/permissioning` directory and then compile the contracts:
+
+```bash
+cd smart_contracts/permissioning
+npm install
+./scripts/compile.sh
+```
+
+Next, deploy the contracts and once complete, execute the `init` function of `PermissionsUpgradable.sol`
+with the `GuardianAccount` address specified earlier. This is wrapped up into a single script
+that you can run:
+
+```bash
+node ./scripts/deploy.js
+```
+
+When completed, a `permission-config.json` file is created which contains the addresses of the
+contracts and any accounts that serve as admins. In this example we've used all accounts, if you
+deploy these contracts in a production network, please select only those which need to be admins.
+
+The file looks similar to:
+
+```bash
+{
+    "permissionModel": "v2",
+    "upgradableAddress": "0x1932c48b2bf8102ba33b4a6b545c32236e342f34",
+    "interfaceAddress": "0x4d3bfd7821e237ffe84209d8e638f9f309865b87",
+    "implAddress": "0xfe0602d820f42800e3ef3f89e1c39cd15f78d283",
+    "nodeMgrAddress": "0x8a5e2a6343108babed07899510fb42297938d41f",
+    "accountMgrAddress": "0x9d13c6d3afe1721beef56b55d303b09e021e27ab",
+    "roleMgrAddress": "0x1349f3e1b8d71effb47b840594ff27da7e603d17",
+    "voterMgrAddress": "0xd9d64b7dc034fafdba5dc2902875a67b5d586420",
+    "orgMgrAddress" : "0x938781b9796aea6376e40ca158f67fa89d5d8a18",
+    "nwAdminOrg": "ADMINORG",
+    "nwAdminRole" : "ADMIN",
+    "orgAdminRole" : "ORGADMIN",
+    "accounts":["0xed9d02e382b34818e88b88a309c7fe71e65f419d", "0xca843569e3427144cead5e4d5999a3d0ccf92b8e", ....],
+    "subOrgBreadth" : 3,
+    "subOrgDepth" : 4
+}
+```
+
+Where:
+
+* `permissionModel` is the Permission model used (v1 or v2).
+* `upgradableAddress` is the address of the deployed `PermissionsUpgradable.sol `contract.
+* `interfaceAddress` is the address of the deployed `PermissionsInterface.sol` contract.
+* `implAddress` is the address of the deployed `PermissionsImplementation.sol` contract.
+* `nodeMgrAddress` is the address of the deployed `NodeManager.sol` contract.
+* `accountMgrAddress` is the address of the deployed `AccountManager.sol` contract.
+* `roleMgrAddress` is the address of the deployed `RoleManager.sol` contract.
+* `voterMgrAddress` is the address of the deployed `VoterManager.sol` contract.
+* `orgMgrAddress` is the address of the deployed `OrgManager.sol` contract.
+* `nwAdminOrg` - Name of the initial organization to be created as a part of the network boot up
+    with a new permissions model. This organization owns all the initial nodes and network
+    administrator accounts at network boot up.
+* `nwAdminRole` - Role ID assigned to the network administrator accounts.
+* `orgAdminRole` - Role ID assigned to the organization administrator account.
+* `accounts` - Initial list of accounts linked to the network administrator organization and assigned
+    the network administrator role. These accounts have complete control of the network and can propose
+    and approve new organizations into the network.
+* `subOrgBreadth` - Number of sub-organizations that any organization can have.
+* `subOrgDepth` - Maximum depth of the sub-organization hierarchy allowed in the network.
+
+The last step is to copy the above `permission-config.json` into the `data` directory of each GoQuorum node and
+restart the nodes. This can be done by running the script:
+
+```bash
+./scripts/copyAndRestart.sh
+```
+
+Once the network starts up you can use the [API methods](../../configure-and-manage/manage/enhanced-permissions.md)
+to add or remove permissions.
+
+!!! warning "Important considerations for production"
+
+    During network initialisation a few things happen:
+
+    * A network admin organization is created with the `nwAdminOrg` name that was specified in the
+        `permission-config.json`. All nodes which are part of the `static-nodes.json` will be automatically assigned
+        to this organization
+    * A network admin role is created with the `nwAdminRole` name specified in the `permission-config.json`
+    * All accounts given in the `accounts` array of the `permission-config.json` file are assigned the network
+        admin role. These accounts can propose and approve new organizations in the network.
+
 ## Use Remix
 
 You can connect your nodes to [Remix](http://remix.ethereum.org) by using the [GoQuorum Plugin](remix.md).