Hyperledger Besu Blockchain Deployment

Deploying Blockchain on Hyperledger Besu

Hyperledger Besu is the only enterprise Ethereum client under Apache 2.0 license, written in Java. Key difference from Geth and Erigon: Besu supports permissioned networks via smart contract-based permissioning, multiple enterprise consensus algorithms (QBFT, IBFT 2.0, Clique), and natively integrates with Hyperledger ecosystem.

Choose Besu when you need EVM-compatibility (Solidity smart contracts, Hardhat/Foundry tools, MetaMask out-of-box) plus network participant control — unlike Fabric where you need custom chaincode for each operation.

Permissioned Network Architecture

┌──────────────────────────────────────────────────────┐
│                    Besu Network                       │
│                                                       │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐           │
│  │ Bootnode │  │Validator1│  │Validator2│ ...        │
│  │(no vote) │  │(QBFT)    │  │(QBFT)    │           │
│  └────┬─────┘  └────┬─────┘  └────┬─────┘           │
│       └─────────────┴─────────────┘                   │
│                    P2P Network                         │
│                                                       │
│  ┌──────────────────────────────────────────────┐    │
│  │         Permissioning Contracts               │    │
│  │  NodePermissioning  AccountPermissioning      │    │
│  └──────────────────────────────────────────────┘    │
└──────────────────────────────────────────────────────┘

QBFT vs IBFT 2.0: Consensus Choice

QBFT (Quorum Byzantine Fault Tolerance) — recommended for new networks. Finality immediately after block inclusion, no forks. Tolerates up to (n-1)/3 Byzantine nodes — with 4 validators survive 1 malicious.

IBFT 2.0 — predecessor to QBFT, similar properties, less performant with larger validator sets. Kept for backward compatibility.

Clique — PoA algorithm, analog of Ethereum Goerli. Less strict finality guarantees, simpler operation. For dev/staging.

Minimum validators for QBFT: 4 (tolerates 1 failure). Production: 4–7 validators from different organizations.

Genesis File

{
  "config": {
    "chainId": 1337,
    "berlinBlock": 0,
    "londonBlock": 0,
    "qbft": {
      "blockperiodseconds": 2,
      "epochlength": 30000,
      "requesttimeoutseconds": 4,
      "blockreward": "0",
      "validatorcontractaddress": "0x0000000000000000000000000000000000008888"
    }
  },
  "nonce": "0x0",
  "timestamp": "0x5b3d92d7",
  "gasLimit": "0x1fffffffffffff",
  "difficulty": "0x1",
  "mixHash": "0x63746963616c2062797a616e74696e65206661756c7420746f6c6572616e6365",
  "coinbase": "0x0000000000000000000000000000000000000000",
  "alloc": {
    "0xfe3b557e8fb62b89f4916b721be55ceb828dbd73": {
      "privateKey": "...",
      "comment": "validator 1",
      "balance": "0xad78ebc5ac6200000"
    }
  },
  "extraData": "0x..."
}

extraData for QBFT must contain RLP-encoded list of initial validator addresses. Use besu operator generate-blockchain-config to generate genesis with keys:

besu operator generate-blockchain-config \
  --config-file=qbftConfigFile.json \
  --to=networkFiles \
  --private-key-file-name=key

Generates genesis.json + directories for each node with keys and enode URL.

Docker Compose for Local Network

version: '3.8'

services:
  bootnode:
    image: hyperledger/besu:latest
    command: |
      --node-private-key-file=/opt/besu/keys/bootnode/key
      --data-path=/opt/besu/data
      --genesis-file=/opt/besu/config/genesis.json
      --rpc-http-enabled=true
      --rpc-http-host=0.0.0.0
      --rpc-http-port=8545
      --rpc-http-api=ETH,NET,QBFT,ADMIN,WEB3
      --host-allowlist=*
      --rpc-http-cors-origins=all
      --p2p-port=30303
      --logging=INFO
    volumes:
      - ./config:/opt/besu/config:ro
      - ./keys:/opt/besu/keys:ro
      - bootnode-data:/opt/besu/data
    ports:
      - "8545:8545"
      - "30303:30303"

  validator1:
    image: hyperledger/besu:latest
    depends_on: [bootnode]
    command: |
      --node-private-key-file=/opt/besu/keys/validator1/key
      --data-path=/opt/besu/data
      --genesis-file=/opt/besu/config/genesis.json
      --bootnodes=enode://${BOOTNODE_PUBKEY}@bootnode:30303
      --rpc-http-enabled=true
      --rpc-http-host=0.0.0.0
      --rpc-http-port=8546
      --rpc-http-api=ETH,NET,QBFT
      --p2p-port=30304
    volumes:
      - ./config:/opt/besu/config:ro
      - ./keys:/opt/besu/keys:ro
      - validator1-data:/opt/besu/data

volumes:
  bootnode-data:
  validator1-data:

Permissioning: Participant Control

Besu supports two permissioning levels:

Node permissioning — which nodes can connect to P2P network. Smart contract-based: list of allowed enode URLs stored in contract, updated dynamically without node restart.

Account permissioning — which accounts can send transactions and deploy contracts. Also via contract.

# Enable permissioning in node config
--permissions-nodes-contract-enabled=true
--permissions-nodes-contract-address=0x0000000000000000000000000000000000009999
--permissions-accounts-contract-enabled=true  
--permissions-accounts-contract-address=0x0000000000000000000000000000000000008888

Permissioning contracts deployed at genesis (add to alloc with bytecode) or after network starts. Besu provides reference implementation:

git clone https://github.com/ConsenSys/permissioning-smart-contracts
cd permissioning-smart-contracts
npm install
# Deploy via Hardhat specifying initial validators and nodes

Monitoring and Management

# List current validators via QBFT API
curl -X POST --data '{"jsonrpc":"2.0","method":"qbft_getValidatorsByBlockNumber","params":["latest"],"id":1}' \
  http://localhost:8545

# Add new validator (requires BFT majority voting)
curl -X POST --data '{"jsonrpc":"2.0","method":"qbft_proposeValidatorVote","params":["0xNewValidatorAddress",true],"id":1}' \
  http://localhost:8545

Grafana + Prometheus: Besu exports metrics to Prometheus format on port 9545 (--metrics-enabled=true --metrics-host=0.0.0.0 --metrics-port=9545). Official Grafana dashboard: github.com/ConsenSys/quorum-monitoring.

Integration with Existing Tools

Besu is EVM-compatible, so work without changes:

• Hardhat/Foundry — contract deployment, tests
• MetaMask — add custom network via Custom RPC
• ethers.js / web3.js / viem — no code changes
• OpenZeppelin contracts — fully compatible
• The Graph — can deploy local graph-node for indexing

Difference: private/permissioned node is your own RPC endpoint, not public.

Typical Deployment Phases