mirror of https://github.com/hyperledger/besu
[PAN-2881] [PAN-2885] Updated onchain permissioning to include accounts and dapp (#1652)
Signed-off-by: Adrian Sutton <adrian.sutton@consensys.net>pull/2/head
MadelineMurray
5 years ago
committed by
GitHub
parent
286368bb7b
commit
1ccd3acbfe
@ -1,225 +0,0 @@ |
||||
description: Onchain Permissioning |
||||
<!--- END of page meta data --> |
||||
|
||||
# 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. |
||||
|
||||
* Node 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": <stripped>, |
||||
"storage": { |
||||
<stripped> |
||||
} |
||||
} |
||||
``` |
||||
|
||||
!!! important |
||||
To support the permissioning contracts, ensure your genesis file includes at least the `constantinopleFixBlock` milestone. |
||||
|
||||
## Onchain Permissioning Setup |
||||
|
||||
1. Start your Pantheon node including command line 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"`) |
||||
|
||||
* [--rpc-http-enabled](../Reference/Pantheon-CLI-Syntax.md#rpc-http-enabled) to enable JSON-RPC |
||||
|
||||
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. |
||||
|
||||
* `NODE_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/Pantheon-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 |
||||
NodeRules.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). |
||||
|
||||
## Bootnodes |
||||
|
||||
When a node is added to the network, it connects to the bootnodes until it synchronizes to the chain head regardless of |
||||
node permissions. Once in sync, the permissioning rules are applied and connections to bootnodes are dropped if not permitted by node |
||||
permissions. |
||||
|
||||
If a sychronized node loses all peer connections (that is, it has 0 peers), it reconnects to the bootnodes regardless of node |
||||
permissions. When the node has connected to 1 or more non-bootnodes, connections to bootnodes are dropped if not permitted by node |
||||
permissions. |
||||
|
||||
## 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("<Admin Account>").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("<Admin Account>").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)});}); |
||||
``` |
||||
@ -0,0 +1,166 @@ |
||||
description: Setting up and using onchain Permissioning |
||||
<!--- END of page meta data --> |
||||
|
||||
# Getting Started with Onchain Permissioning |
||||
|
||||
The following steps describe bootstrapping a local permissioned network using a Pantheon node and a |
||||
development server to run the Permissioning Management Dapp. |
||||
|
||||
To start a network with onchain permissioning: |
||||
|
||||
1. [Install pre-requisites](#pre-requisites) |
||||
1. [Add the ingress contracts to the genesis file](#add-ingress-contracts-to-genesis-file) |
||||
1. [Set environment variables](#set-environment-variables) |
||||
1. [Start first node with onchain permissioning and the JSON-RPC HTTP service enabled](#onchain-permissioning-command-line-options) |
||||
1. [Clone the permissioning contracts repository and install dependencies](#clone-contracts-and-install-dependencies) |
||||
1. [Deploy the permissioning contracts](#deploy-contracts) |
||||
1. [Start the development server for the Permissioning Management Dapp](#start-the-permissioning-management-dapp) |
||||
1. [Add the first node to the nodes whitelist](#update-nodes-whitelist) |
||||
|
||||
## Pre-requisites |
||||
|
||||
For the development server to run the dapp: |
||||
|
||||
* [NodeJS](https://nodejs.org/en/) v10.16.0 or later |
||||
* [Yarn](https://yarnpkg.com/en/) v1.15 or later |
||||
* Browser with [MetaMask installed](https://metamask.io/) |
||||
|
||||
To deploy the permissioning contracts: |
||||
|
||||
* [Truffle](https://truffleframework.com/docs/truffle/getting-started/installation) |
||||
|
||||
## Add Ingress Contracts to Genesis File |
||||
|
||||
!!! tip |
||||
If the network is using only account or nodes permissioning, add only the relevant ingress contract to the |
||||
genesis file. |
||||
|
||||
Add the Ingress contracts to the genesis file for your network by copying them 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 |
||||
|
||||
"0x0000000000000000000000000000000000008888": { |
||||
"comment": "Account Ingress smart contract", |
||||
"balance": "0", |
||||
"code": <stripped>, |
||||
"storage": { |
||||
<stripped> |
||||
} |
||||
} |
||||
|
||||
"0x0000000000000000000000000000000000009999": { |
||||
"comment": "Node Ingress smart contract", |
||||
"balance": "0", |
||||
"code": <stripped>, |
||||
"storage": { |
||||
<stripped> |
||||
} |
||||
} |
||||
``` |
||||
|
||||
!!! important |
||||
To support the permissioning contracts, ensure your genesis file includes at least the `constantinopleFixBlock` milestone. |
||||
|
||||
## Set Environment Variables |
||||
|
||||
Create the following environment variables and set to the specified values: |
||||
|
||||
* `PANTHEON_NODE_PERM_ACCOUNT` - account to deploy the permissioning contracts and become the first admin account. |
||||
|
||||
* `PANTHEON_NODE_PERM_KEY` - private key of the account to deploy the permissioning contracts. |
||||
|
||||
* `ACCOUNT_INGRESS_CONTRACT_ADDRESS` - address of the Account Ingress contract in the genesis file. |
||||
|
||||
* `NODE_INGRESS_CONTRACT_ADDRESS` - address of the Node 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. When bootstrapping the network, the specified node is used to deploy the contracts and is the first node |
||||
in the network. |
||||
|
||||
!!! important |
||||
The account specified must be a miner (PoW networks) or validator (PoA networks). |
||||
|
||||
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. |
||||
|
||||
## Onchain Permissioning Command Line Options |
||||
|
||||
All nodes participating in a permissioned network must include the command line options to enable account and/or |
||||
node permissioning: |
||||
|
||||
* [--permissions-accounts-contract-enabled](../../Reference/Pantheon-CLI-Syntax.md#permissions-accounts-contract-enabled) |
||||
to enable onchain accounts permissioning |
||||
|
||||
* [--permissions-accounts-contract-address](../../Reference/Pantheon-CLI-Syntax.md#permissions-accounts-contract-address) |
||||
set to the address of the Account Ingress contract in the genesis file (`"0x0000000000000000000000000000000000008888"`) |
||||
|
||||
* [--permissions-nodes-contract-enabled](../../Reference/Pantheon-CLI-Syntax.md#permissions-nodes-contract-enabled) |
||||
to enable onchain nodes permissioning |
||||
|
||||
* [--permissions-nodes-contract-address](../../Reference/Pantheon-CLI-Syntax.md#permissions-nodes-contract-address) |
||||
set to the address of the Node Ingress contract in the genesis file (`"0x0000000000000000000000000000000000009999"`) |
||||
|
||||
## Clone Project and Install Dependencies |
||||
|
||||
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 |
||||
yarn install |
||||
``` |
||||
|
||||
## Build Project |
||||
|
||||
In the `permissioning-smart-contracts` directory, build the project: |
||||
|
||||
```bash |
||||
yarn run build |
||||
``` |
||||
|
||||
## Deploy Contracts |
||||
|
||||
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](#update-accounts-or-admin-accounts-whitelists). |
||||
|
||||
## Start the Development Server for the Permissioning Management Dapp |
||||
|
||||
1. In the `permissioning-smart-contracts` directory, start the web server serving the Dapp: |
||||
|
||||
```bash |
||||
yarn start |
||||
``` |
||||
|
||||
The Dapp is displayed at [http://localhost:3000](http://localhost:3000). |
||||
|
||||
1. Ensure MetaMask is connected to your local node (by default `http://localhost:8545`). |
||||
|
||||
A MetaMask notification is displayed requesting permission for Pantheon Permissioning to |
||||
connect to your account. |
||||
|
||||
1. Click the _Connect_ button. |
||||
|
||||
The Dapp is displayed with the account specified by the `PANTHEON_NODE_PERM_ACCOUNT` environment variable |
||||
in the _Whitelisted Accounts_ and _Admin Accounts_ tabs. |
||||
|
||||
!!! note |
||||
Only [admin accounts](#update-accounts-or-admin-accounts-whitelists) can add or remove nodes from the whitelist. |
||||
|
||||
## Add First Node to Whitelist |
||||
|
||||
The first node must [add itself to the whitelist](Updating-Whitelists.md#update-nodes-whitelist) before adding other nodes. |
||||
|
||||
@ -0,0 +1,55 @@ |
||||
description: Onchain Permissioning |
||||
<!--- END of page meta data --> |
||||
|
||||
# Onchain Permissioning |
||||
|
||||
Onchain permissioning uses smart contracts to store and maintain the node, account, and admin whitelists. |
||||
Using onchain permissioning enables all nodes to read the whitelists from a single source, the blockchain. |
||||
|
||||
!!! important |
||||
The dependency chain for our implementation of onchain permissioning includes [web3j](https://github.com/web3j/web3j) which is |
||||
LGPL licensed. |
||||
|
||||
## Permissioning Contracts |
||||
|
||||
The permissioning smart contracts are provided in the [PegaSysEng/permissioning-smart-contracts](https://github.com/PegaSysEng/permissioning-smart-contracts) repository: |
||||
|
||||
* Ingress contracts for nodes and accounts - proxy contracts defined in the genesis file that defer the permissioning logic to the |
||||
Node Rules and Account Rules contracts. The Ingress contracts are deployed to static addresses. |
||||
|
||||
* Node Rules - stores the node whitelist and node whitelist operations (for example, add and remove). |
||||
|
||||
* Account Rules - stores the accounts whitelist and account whitelist operations (for example, add and remove). |
||||
|
||||
* Admin - stores the list of admin accounts and admin list operations (for example, add and remove). There is |
||||
one list of admin accounts for node and accounts. |
||||
|
||||
## Permissioning Management Dapp |
||||
|
||||
The [Permissioning Management Dapp](Getting-Started-Onchain-Permissioning.md) is provided to view |
||||
and maintain the whitelists. |
||||
|
||||
!!! tip |
||||
Before v1.2, we provided a [management interface using Truffle](https://docs.pantheon.pegasys.tech/en/1.1.4/Permissions/Onchain-Permissioning/). |
||||
The management interface using Truffle is deprecated and we recommend using the Dapp for an improved user experience. |
||||
|
||||
### Whitelists |
||||
|
||||
Permissioning implements three whitelists: |
||||
|
||||
* [Accounts](Getting-Started-Onchain-Permissioning.md#update-accounts-or-admin-accounts-whitelists) can submit |
||||
transactions to the network |
||||
|
||||
* [Nodes](Getting-Started-Onchain-Permissioning.md#update-nodes-whitelist) can participate in the network |
||||
|
||||
* [Admins](Getting-Started-Onchain-Permissioning.md#update-accounts-or-admin-accounts-whitelists) are accounts that |
||||
can update the accounts and nodes whitelists |
||||
|
||||
## Bootnodes |
||||
|
||||
When a node is added to the network, it connects to the bootnodes until it synchronizes to the chain head regardless of |
||||
node permissions. Once in sync, the permissioning rules in the Account Rules and Node Rules smart contracts are applied. |
||||
|
||||
If a sychronized node loses all peer connections (that is, it has 0 peers), it reconnects to the bootnodes to |
||||
rediscover peers. |
||||
|
||||
@ -0,0 +1,46 @@ |
||||
description: Updating onchain whitelists |
||||
<!--- END of page meta data --> |
||||
|
||||
## Update Nodes Whitelist |
||||
|
||||
To add a node to the nodes whitelist: |
||||
|
||||
1. In the _Whitelisted Nodes_ tab of the Permissioning Management Dapp, click the _Add Whitelisted Nodes_ |
||||
button. The add node window is displayed. |
||||
|
||||
2. Enter the [enode URL](../../Configuring-Pantheon/Node-Keys.md#enode-url) of the node to be added and click |
||||
the _Add Whitelisted Node_ button. |
||||
|
||||
To remove a node from the nodes whitelist: |
||||
|
||||
1. In the _Whitelisted Nodes_ tab of the Permissioning Management Dapp, hover over the row of the node to remove. |
||||
A trash can is displayed. |
||||
|
||||
1. Click on the trash can. |
||||
|
||||
!!! 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/Pantheon-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. |
||||
|
||||
## Update Accounts Whitelists |
||||
|
||||
To add an account to the accounts whitelist: |
||||
|
||||
1. In the _Whitelisted Accounts_ tab of the Permissioning Management Dapp, click the _Add Whitelisted Account_ |
||||
button. The add account window is displayed. |
||||
|
||||
1. Enter the account address in the _Account Address_ field and click the _Add Whitelisted Account_ button. |
||||
|
||||
To remove an account from the accounts whitelist: |
||||
|
||||
1. In the _Whitelisted Accounts_ tab of the Permissioning Management Dapp, hover over the |
||||
row of the account to be removed. A trash can is displayed. |
||||
|
||||
1. Click on the trash can. |
||||
|
||||
## Update Admins |
||||
|
||||
Admins are added or removed in the same way as accounts except in the _Admin Accounts_ tab. |
||||
Loading…
Reference in new issue