besu/docs/Permissions/Onchain-Permissioning.md

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 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 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 v8.9.4 or later

• Truffle

Add Ingress Contract to Genesis File

Add the Ingress contract to the genesis file for your network by copying it from genesis.json in the permissioning-smart-contracts repository:

"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 with contract permissioning options:

   • --permissions-nodes-contract-enabled to enable onchain permissioning

   • --permissions-nodes-contract-address set to the address of the Ingress contract in the genesis file ("0x0000000000000000000000000000000000009999")

2. 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, the account used to interact with the permissioning contracts must have a balance.

3. Clone the permissioning-smart-contracts repository:

   git clone https://github.com/PegaSysEng/permissioning-smart-contracts.git
   

4. Change into the permissioning-smart-contracts directory and run:

   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:

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 Nodes from the Whitelist

!!! note
Only 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:

   truffle console 
   

2. Open https://permissioning-tools.pegasys.tech/

3. Enter the enode URL of the node to be added or removed.

4. Click the Add Node or Remove Node button. The truffle command is displayed.

5. Click the Copy to clipboard button.

6. 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.

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:

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 to enable onhcain permissioning

   • --permissions-nodes-contract-address set to the address of the Ingress contract in the genesis file ("0x0000000000000000000000000000000000009999")

   • --bootnodes set to the first node (that is, the node that deployed the Admin and Rules contracts.

2. Copy the enode URL and have node added to the whitelist.

For participating nodes that are going to add or remove nodes from the whitelist:

1. Ensure prerequisites installed.

2. Complete permissioning setup.

3. Copy the enode URL and have node added to the whitelist.

4. Have account for node that will interact with permissioning contracts added as an admin account.

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:

Admin.deployed().then(function(instance) {instance.addAdmin("<Admin Account>").then(function(tx) {console.log(tx)});});

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:

Admin.deployed().then(function(instance) {instance.removeAdmin("<Admin Account>").then(function(tx) {console.log(tx)});});

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:

Admin.deployed().then(function(instance) {instance.getAdmins().then(function(tx) {console.log(tx)});});