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.
Last update: February 23, 2021

Upgrade the permissioning contracts

The following tutorial describes the steps to upgrade the permissioning contracts to the latest version when using onchain permissioning.

The following instructions assume that the user is upgrading contracts that implement version 1 of the permissioning contract interface.


For the development server to run the dapp:


Listed on the right-hand side of the page are the steps to create a permissioned network.

1. Get the latest contracts and install dependencies


Pull the latest changes if you already have a cloned repository using the git pull command inside the permissioning-smart-contracts directory.

  1. Clone the permissioning-smart-contracts repository:

    git clone
  2. Change into the permissioning-smart-contracts directory and run:

    yarn install

2. Build the project

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

yarn run build

3. Update environment variables


This step is only required if upgrading from v1.1.0 or earlier release of the permissioning contract to v2.0.0 or later.

  1. If they exist, delete the following environment variables:

  2. If they exist, rename the following environment variables:


4. Deploy the contract

If using a .env file to configure environment variables, then copy the file to the permissioning-smart-contracts directory.

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

yarn truffle migrate --reset


Copy the NodeIngress and AccountIngress contract addresses which are displayed in the output. These must be specified when restarting the nodes.

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

6. Restart Besu nodes

Restart the Besu nodes and include the updated NodeIngress and AccountIngress contract addresses and permissioning contract interface version.

besu --data-path=data --genesis-file=../cliqueGenesis.json --permissions-accounts-contract-enabled --permissions-accounts-contract-address "0x3d49d1eF2adE060a33c6E6Aa213513A7EE9a6241" --permissions-nodes-contract-enabled  --permissions-nodes-contract-address "0x4E72770760c011647D4873f60A3CF6cDeA896CD8" --permissions-nodes-contract-version=2 --rpc-http-enabled --rpc-http-cors-origins="*" --rpc-http-api=ADMIN,ETH,NET,PERM,CLIQUE --host-allowlist="*"

In the command, the following options have been updated:

7. Add nodes to the allowlist

In the Permissioning Management Dapp started earlier add the nodes to the allowlist.

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