You are reading Pantheon development version documentation and some displayed features may not be available in the stable release. You can switch to stable version using the version box at screen bottom.

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

• Node Rules - stores the node whitelist and node whitelist operations (for example, add and remove).

## Pre-requisites

For nodes that are going to maintain the nodes whitelist or the list of admin accounts:

## 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 including command line options:

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.

• 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, 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

After deploying the admin and rules contracts, the first node must add itself to the whitelist before adding other nodes.

1. In the permissioning-smart-contracts directory, run the Truffle console:

truffle console

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

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

4. Click the Copy to clipboard button.

5. 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:

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:

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.

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

The account that deploys the Rules contract is automatically an Admin account. Only Admin accounts can add or remove nodes from the whitelist.

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)});});


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