Skip to content
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.

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

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.

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

  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)});});
Questions or feedback? You can discuss issues and obtain free support on Pantheon Gitter channel.
For paid professional support by PegaSys, contact us at [email protected]