From 97f0f73b57286b8e32dad9cf35945c76a2a381b9 Mon Sep 17 00:00:00 2001 From: MadelineMurray <43356962+MadelineMurray@users.noreply.github.com> Date: Mon, 29 Apr 2019 15:58:22 +1000 Subject: [PATCH] Onchain permissioning (#1300) Signed-off-by: Adrian Sutton --- docs/Permissions/Onchain-Permissioning.md | 213 +++++++++++++++++++++ docs/Permissions/Permissioning-Overview.md | 2 +- docs/Reference/Pantheon-CLI-Syntax.md | 10 +- mkdocs.yml | 1 + 4 files changed, 217 insertions(+), 9 deletions(-) create mode 100644 docs/Permissions/Onchain-Permissioning.md diff --git a/docs/Permissions/Onchain-Permissioning.md b/docs/Permissions/Onchain-Permissioning.md new file mode 100644 index 0000000000..eafc9ed97c --- /dev/null +++ b/docs/Permissions/Onchain-Permissioning.md @@ -0,0 +1,213 @@ +description: Onchain Permissioning + + +# Onchain Permissioning + +Onchain permissioning uses smart contracts to store and maintain the node whitelist. Using onchain permissioning +enables all nodes to read the node whitelist from one location. + +!!! note + Pantheon supports onchain permissioning for nodes. Onchain permissioning for accounts will be available + in a future Pantheon release. + +We have provided a set of smart contracts that interface with onchain permissioning in the +[PegaSysEng/permissioning-smart-contracts](https://github.com/PegaSysEng/permissioning-smart-contracts) repository. +We have also provided a management interface to interact with the contracts. + +## Provided Contracts + +The following smart contracts are provided in the [PegaSysEng/permissioning-smart-contracts](https://github.com/PegaSysEng/permissioning-smart-contracts) repository: + +* Ingress - a simple contract functioning as a gateway to the Admin and Rules contracts. The Ingress contract is deployed +to a static address. + +* Rules - stores the node whitelist and node whitelist operations (for example, add and remove). + +* Admin - stores the list of admin accounts and admin list operations (for example, add and remove). + +## Pre-requisites + +For nodes that are going to maintain the nodes whitelist or the list of admin accounts: + +* [NodeJS](https://nodejs.org/en/) v8.9.4 or later + +* [Truffle](https://truffleframework.com/docs/truffle/getting-started/installation) + +## Add Ingress Contract to Genesis File + +Add the Ingress contract to the genesis file for your network by copying it from [`genesis.json`](https://github.com/PegaSysEng/permissioning-smart-contracts/blob/master/genesis.json) +in the [`permissioning-smart-contracts` repository](https://github.com/PegaSysEng/permissioning-smart-contracts): + +```json +"0x0000000000000000000000000000000000009999": { + "comment": "Ingress smart contract", + "balance": "0", + "code": , + "storage": { + + } +} +``` + +!!! important + To support the permissioning contracts, ensure your genesis file includes at least the `constantinopleFixBlock` milestone. + +## Onchain Permissioning Setup + +1. Start your Pantheon node with contract permissioning options: + + * [--permissions-nodes-contract-enabled](../Reference/Pantheon-CLI-Syntax.md#permissions-nodes-contract-enabled) + to enable onchain permissioning + + * [--permissions-nodes-contract-address](../Reference/Pantheon-CLI-Syntax.md#permissions-nodes-contract-address) + set to the address of the Ingress contract in the genesis file (`"0x0000000000000000000000000000000000009999"`) + +1. Create the following environment variables and set to the specified values: + + * `PANTHEON_NODE_PERM_ACCOUNT` - address of account used to interact with the permissioning contracts. + + * `PANTHEON_NODE_PERM_KEY` - private key of the account used to interact with the permissioning contracts. + + * `INGRESS_CONTRACT_ADDRESS` - address of the Ingress contract in the genesis file. + + * `PANTHEON_NODE_PERM_ENDPOINT` - required only if your node is not using the default JSON-RPC host and port (`http://127.0.0.1:8545`). + Set to JSON-RPC host and port. + + !!! note + If your network is not a [free gas network](../Configuring-Pantheon/FreeGas.md), the account used to + interact with the permissioning contracts must have a balance. + +1. Clone the `permissioning-smart-contracts` repository: + + ```bash + git clone https://github.com/PegaSysEng/permissioning-smart-contracts.git + ``` + +1. Change into the `permissioning-smart-contracts` directory and run: + + ```bash + npm install + ``` + +## Deploy Admin and Rules Contracts + +!!! important + Only the first node deploys the admin and rules contract. Subsequent nodes do not migrate the contracts. + + The node deploying the admin and rules contracts must be a miner (PoW networks) or validator (PoA networks). + +In the `permissioning-smart-contracts` directory, deploy the Admin and Rules contracts: + +```bash +truffle migrate --reset +``` + +The Admin and Rules contracts are deployed and the Ingress contract updated with the name and version of the contracts. +The migration logs the addresses of the Admin and Rules contracts. + +!!! important + The account that deploys the contracts is automatically an [Admin account](#add-and-remove-admin-accounts). + +## Add and Remove Nodes from the Whitelist + +!!! note + Only [Admin accounts](#add-and-remove-admin-accounts) can add or remove nodes from the whitelist. + + After deploying the admin and rules contracts, the first node must add itself to the whitelist before + adding other nodes. + +To add or remove nodes: + +1. In the `permissioning-smart-contracts` directory, run the Truffle console: + + ```bash + truffle console + ``` + +1. Open https://permissioning-tools.pegasys.tech/ + +1. Enter the [enode URL](../Configuring-Pantheon/Node-Keys.md#enode-url) of the node to be added or removed. + +1. Click the *Add Node* or *Remove Node* button. The truffle command is displayed. + +1. Click the *Copy to clipboard* button. + +1. Paste the copied command into the Truffle Console. + + When the transaction is included in a block, the transaction receipt is displayed. + + +!!! tip + If you add a running node, the node does not attempt to reconnect to the bootnode and synchronize until + peer discovery restarts. To add a whitelisted node as a peer without waiting for peer discovery to restart, use [`admin_addPeer`](../Reference/JSON-RPC-API-Methods.md#admin_addpeer). + + If the node is added to the whitelist before starting the node, using `admin_addPeer` is not required because + peer discovery is run on node startup. + +## Display Nodes Whitelist + +To display the nodes whitelist, paste the following into the Truffle Console: + +```javascript +Rules.deployed().then(function(instance) {instance.getSize().then(function(txCount) {console.log("size of whitelist: " + txCount); var i=txCount; while(i>=0) {instance.getByIndex(i--).then(function(tx) {console.log(tx)})}});}); +``` + +## Start Other Network Nodes + +For participating nodes that are not going to add or remove nodes from the whitelist: + +1. Start the nodes including the following options: + + * [--permissions-nodes-contract-enabled](../Reference/Pantheon-CLI-Syntax.md#permissions-nodes-contract-enabled) + to enable onhcain permissioning + + * [--permissions-nodes-contract-address](../Reference/Pantheon-CLI-Syntax.md#permissions-nodes-contract-address) + set to the address of the Ingress contract in the genesis file (`"0x0000000000000000000000000000000000009999"`) + + * [--bootnodes](../Reference/Pantheon-CLI-Syntax.md#bootnodes) set to the first node (that is, the node that [deployed + the Admin and Rules contracts](#deploy-admin-and-rules-contracts). + +1. Copy the [enode URL](../Configuring-Pantheon/Node-Keys.md#enode-url) and [have node added to the whitelist](#add-and-remove-nodes-from-the-whitelist). + +For participating nodes that are going to add or remove nodes from the whitelist: + +1. Ensure [prerequisites installed](#pre-requisites). + +1. Complete [permissioning setup](#onchain-permissioning-setup). + +1. Copy the [enode URL](../Configuring-Pantheon/Node-Keys.md#enode-url) and [have node added to the whitelist](#add-and-remove-nodes-from-the-whitelist). + +1. Have account for node that will interact with permissioning contracts added as an [admin account](#add-and-remove-admin-accounts). + +## Add and Remove Admin Accounts + +The account that deploys the Rules contract is automatically an Admin account. Only Admin accounts can +add or remove nodes from the whitelist. + +To add Admin accounts, paste the following commands into Truffle Console: + +```javascript tab="Truffle Console Command" +Admin.deployed().then(function(instance) {instance.addAdmin("").then(function(tx) {console.log(tx)});}); +``` + +```javascript tab="Example" +Admin.deployed().then(function(instance) {instance.addAdmin("0x627306090abaB3A6e1400e9345bC60c78a8BEf57").then(function(tx) {console.log(tx)});}); +``` + +To remove Admin accounts, paste the following commands into Truffle Console: + +```javascript tab="Truffle Console Command" +Admin.deployed().then(function(instance) {instance.removeAdmin("").then(function(tx) {console.log(tx)});}); +``` + +```javascript tab="Example" +Admin.deployed().then(function(instance) {instance.removeAdmin("0x627306090abaB3A6e1400e9345bC60c78a8BEf57").then(function(tx) {console.log(tx)});}); +``` + +### Display Admin Accounts + +To display the list of admin accounts, paste the following into the Truffle Console: + +```javascript +Admin.deployed().then(function(instance) {instance.getAdmins().then(function(tx) {console.log(tx)});}); +``` \ No newline at end of file diff --git a/docs/Permissions/Permissioning-Overview.md b/docs/Permissions/Permissioning-Overview.md index 1cd898569b..15a9a9effc 100644 --- a/docs/Permissions/Permissioning-Overview.md +++ b/docs/Permissions/Permissioning-Overview.md @@ -23,7 +23,7 @@ Updates to local permissioning must be made to the configuration file for each n ## Onchain -Onchain permissioning are specified in a smart contract on the network. Specifying permissioning onchain +Onchain permissioning is specified in a smart contract on the network. Specifying permissioning onchain enables all nodes to read and update permissioning in one location. !!! note diff --git a/docs/Reference/Pantheon-CLI-Syntax.md b/docs/Reference/Pantheon-CLI-Syntax.md index db562fd981..44d54dc1fb 100644 --- a/docs/Reference/Pantheon-CLI-Syntax.md +++ b/docs/Reference/Pantheon-CLI-Syntax.md @@ -644,10 +644,7 @@ Default is the `permissions_config.toml` file in the [data directory](#data-path permissions-nodes-contract-address=xyz ``` -Specifies the contract address for contract-based nodes permissions. - -!!!note - Contract-based nodes permissions are under development and will be available in v1.1. +Specifies the contract address for [onchain node permissioning](../Permissions/Onchain-Permissioning.md). ### permissions-nodes-contract-enabled @@ -663,10 +660,7 @@ Specifies the contract address for contract-based nodes permissions. permissions-nodes-contract-enabled=true ``` -Set to enable contract-based node level permissions. Default is `false`. - -!!!note - Contract-based nodes permissions are under development and will be available in v1.1. +Enables contract-based [onchain node permissioning](../Permissions/Onchain-Permissioning.md). Default is `false`. ### privacy-enabled diff --git a/mkdocs.yml b/mkdocs.yml index 5c2a5064a0..fef9b03334 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -93,6 +93,7 @@ nav: - Permissions: - Overview: Permissions/Permissioning-Overview.md - Local Permissions: Permissions/Local-Permissioning.md + - Onchain Permissions: Permissions/Onchain-Permissioning.md - Using Pantheon: - Transactions: - Creating and Sending Transactions: Using-Pantheon/Transactions/Transactions.md