Skip to content
You are reading Hyperledger Besu 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.

Updated on September 11, 2020

Get started with onchain permissioning

The following steps describe bootstrapping a permissioned network using a Hyperledger Besu node and a development server to run the Permissioning Management Dapp.

Note

Production environments require a webserver to host the Permissioning Management Dapp.

To start a network with onchain permissioning:

  1. Install the prerequisites
  2. Add the ingress contracts to the genesis file
  3. Set the environment variables
  4. Start first node with onchain permissioning and the JSON-RPC HTTP service enabled
  5. Clone the permissioning contracts repository and install dependencies
  6. Build the project
  7. Deploy the permissioning contracts
  8. Start the webserver for the Permissioning Management Dapp
  9. Add the first node to the nodes allowlist.

Prerequisites

For the development server to run the dapp:

Add the ingress contracts to the genesis file

Tip

If the network is using only account or node 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 in the permissioning-smart-contracts repository:

"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 the environment variables

Create the following environment variables and set to the specified values:

  • BESU_NODE_PERM_ACCOUNT - account to deploy the permissioning contracts and become the first admin account.
  • BESU_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.
  • BESU_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, Besu uses the specified node to deploy the contracts and is the first node in the network.
  • CHAIN_ID The chainID from the genesis file.

Tip

A simple way to set multiple environment variables is to create a file called .env with the required settings

NODE_INGRESS_CONTRACT_ADDRESS=0x0000000000000000000000000000000000009999
ACCOUNT_INGRESS_CONTRACT_ADDRESS=0x0000000000000000000000000000000000008888
BESU_NODE_PERM_ACCOUNT=627306090abaB3A6e1400e9345bC60c78a8BEf57
BESU_NODE_PERM_KEY=c87509a1c067bbde78beb793e6fa76530b6382a4c0241e5e4a9ec0a0f44dc0d3
CHAIN_ID=2018

Onchain permissioning command line options

Important

The specified node must be producing blocks, that is, be a miner (PoW networks) or validator (PoA networks).

To allow MetaMask to connect, the node must have JSON-RPC HTTP enabled, and have --rpc-http-cors-origins set to allow MetaMask.

If your network is not a free gas network, the account used to interact with the permissioning contracts must have a balance.

To enable account and/or node permissioning, all nodes participating in a permissioned network must include the command line options:

example command line:

besu --permissions-accounts-contract-enabled --permissions-accounts-contract-address "0x0000000000000000000000000000000000008888" --permissions-nodes-contract-enabled  --permissions-nodes-contract-address "0x0000000000000000000000000000000000009999" --genesis-file=genesis.json --rpc-http-enabled --rpc-http-cors-origins="*" --miner-enabled --miner-coinbase=fe3b557e8fb62b89f4916b721be55ceb828dbd73

Clone the contracts and install dependencies

  1. Clone the permissioning-smart-contracts repository:

    git clone https://github.com/PegaSysEng/permissioning-smart-contracts.git
    
  2. Change into the permissioning-smart-contracts directory and run:

    yarn install
    

Build the project

In the permissioning-smart-contracts directory, build the project:

yarn run build

Deploy the contracts

In the permissioning-smart-contracts directory, deploy the Admin and Rules contracts:

yarn truffle migrate --reset

This also updates the Ingress contract with the name and version of the Admin and Rules contracts. The migration logs the addresses of the Admin and Rules contracts.

Important

The account that deploys the contracts is automatically an [admin account].

Start the webserver for the Permissioning Management Dapp

Note

Production environments require a webserver to host the Permissioning Management Dapp.

  1. In the permissioning-smart-contracts directory, start the webserver serving the Dapp:

    yarn start
    

    The Dapp displays at http://localhost:3000.

  2. Ensure MetaMask connects to your local node (by default http://localhost:8545).

    A MetaMask notification displays requesting permission for Besu Permissioning to connect to your account.

  3. Click the Connect button.

    The Dapp displays with the account specified by the BESU_NODE_PERM_ACCOUNT environment variable in the Accounts and Admins tabs.

Note

Only admin accounts can add or remove nodes from the permission list.

Add the first node to the allowlist

The first node must add itself to the allowlist before adding other nodes.

Questions or feedback? You can discuss issues and obtain free support on Hyperledger Besu chat channel.
For Hyperledger Besu community support, contact the mailing list besu@lists.hyperledger.org