Hyperledger Besu: Hands-on Private Networks

Recap: From Landscape to Keyboard

In Module 16 you surveyed the enterprise blockchain landscape — Besu, Fabric, Corda, Indy, Quorum — and learned when you would reach for each one. This module is different: it is the only hands-on module in Part 3. By the end, you will be running a real 4-node Besu network on your laptop and deploying a Solidity contract to it.

What is Besu?

Hyperledger Besu is an open-source Ethereum client written in Java, built by ConsenSys and donated to the Linux Foundation's Hyperledger project in 2019. It is the only Ethereum client hosted at Hyperledger, and the only one designed from day one for both public mainnet and private enterprise networks.

Consensus: IBFT 2.0 and QBFT

Public Ethereum uses Proof of Stake. Bitcoin uses Proof of Work. Neither makes sense for a private consortium where you already know and trust (or contractually constrain) the validators. Besu instead offers two Byzantine Fault Tolerant consensus algorithms designed for this exact setting.

IBFT 2.0 vs QBFT — Quick Comparison

Both algorithms share the same fundamental guarantees (instant finality, (N−1)/3 fault tolerance, on-chain validator voting). The differences are mostly in robustness, specification, and recommendation status.

Network Setup: A 4-Node QBFT Cluster

Enough theory. Let's build a real 4-node QBFT network running locally in Docker Compose. This is the exact workflow you would use for a development or staging environment, scaled down to fit on your laptop.

1. Generate the Blockchain Config

Besu ships with a powerful subcommand, besu operator generate-blockchain-config, which takes a small JSON input and produces a full genesis file plus one key pair per validator. You specify the number of validators, the consensus algorithm (QBFT), the chain ID, and a list of pre-funded accounts. Besu does the rest.

The Config Input File

{
  "genesis": {
    "config": {
      "chainId": 1337,
      "londonBlock": 0,
      "qbft": {
        "blockperiodseconds": 2,
        "epochlength": 30000,
        "requesttimeoutseconds": 4
      }
    },
    "nonce": "0x0",
    "gasLimit": "0x1fffffffffffff",
    "difficulty": "0x1",
    "alloc": {
      "0xfe3b557e8fb62b89f4916b721be55ceb828dbd73": {
        "balance": "1000000000000000000000"
      }
    }
  },
  "blockchain": {
    "nodes": {
      "generate": true,
      "count": 4
    }
  }
}

2. Run the Generator

A single command turns that input into a full network configuration. You get a genesis.json and a folder per validator containing its private key, public key, and address.

# Produces ./networkFiles/genesis.json and ./networkFiles/keys/*
besu operator generate-blockchain-config \
  --config-file=qbft-config.json \
  --to=networkFiles \
  --private-key-file-name=key

3. Compose the 4-Node Network

Now wire up the nodes with Docker Compose. Node 1 exposes 8545 as the public RPC endpoint (the one you point Hardhat at). Nodes 2–4 join it via P2P. All four are validators in the QBFT set.

# 4-node Besu QBFT private network
services:
  besu-node1:
    image: hyperledger/besu:latest
    volumes:
      - ./networkFiles/genesis.json:/config/genesis.json
      - ./networkFiles/keys/node1:/opt/besu/keys
    ports:
      - "8545:8545"
    command:
      - --genesis-file=/config/genesis.json
      - --node-private-key-file=/opt/besu/keys/key
      - --rpc-http-enabled
      - --rpc-http-host=0.0.0.0
      - --rpc-http-api=ETH,NET,QBFT,WEB3,ADMIN
      - --host-allowlist=*
      - --min-gas-price=0

  besu-node2:
    image: hyperledger/besu:latest
    volumes:
      - ./networkFiles/genesis.json:/config/genesis.json
      - ./networkFiles/keys/node2:/opt/besu/keys
    command:
      - --genesis-file=/config/genesis.json
      - --node-private-key-file=/opt/besu/keys/key
      - --bootnodes=enode://<node1-pubkey>@besu-node1:30303
      - --min-gas-price=0

  besu-node3:
    image: hyperledger/besu:latest
    volumes:
      - ./networkFiles/genesis.json:/config/genesis.json
      - ./networkFiles/keys/node3:/opt/besu/keys
    command:
      - --genesis-file=/config/genesis.json
      - --node-private-key-file=/opt/besu/keys/key
      - --bootnodes=enode://<node1-pubkey>@besu-node1:30303
      - --min-gas-price=0

  besu-node4:
    image: hyperledger/besu:latest
    volumes:
      - ./networkFiles/genesis.json:/config/genesis.json
      - ./networkFiles/keys/node4:/opt/besu/keys
    command:
      - --genesis-file=/config/genesis.json
      - --node-private-key-file=/opt/besu/keys/key
      - --bootnodes=enode://<node1-pubkey>@besu-node1:30303
      - --min-gas-price=0

4. Start the Network

With the compose file in place, a single docker compose up -d spins up all four validators. Within a few seconds, they will elect a proposer, agree on the genesis, and start producing empty blocks. You now have a private Ethereum network on your laptop.

# Launch all four validators in the background
docker compose up -d

# Check the block number through node1 RPC
curl -X POST --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' \
  -H "Content-Type: application/json" \
  http://localhost:8545

Deploying Contracts: Everything You Already Know

Here is the best part: your Hardhat project from Part 2 just works. There is no “Besu SDK,” no special compiler, no proprietary library. You add one network entry to hardhat.config.ts, point it at localhost:8545, and you are live on your consortium chain.

The hardhat.config.ts Diff

The only real change is a new entry in the networks block. Chain ID 1337 must match the chainId in your QBFT genesis file. Accounts are the pre-funded addresses from your config (ETH preset): Besu has no concept of gas faucets on a private chain, you simply seed addresses in the genesis.

// hardhat.config.ts
import type { HardhatUserConfig } from "hardhat/config";
import "@nomicfoundation/hardhat-toolbox";

const config: HardhatUserConfig = {
  solidity: "0.8.24",
  networks: {
    besu: {
      url: "http://localhost:8545",
      chainId: 1337,
      accounts: [
        "0x8f2a559490...pre-funded-from-genesis"
      ],
      gasPrice: 0
    }
  }
};

export default config;

Sample Contract — Vault

A minimal Vault contract that lets a depositor lock ETH for a given withdrawal time. This is deliberately simple — the point is to show that your Part 2 Solidity workflow is untouched.

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;

contract Vault {
    mapping(address => uint256) public balances;
    mapping(address => uint256) public unlockAt;

    event Deposited(address indexed who, uint256 amount, uint256 unlock);
    event Withdrawn(address indexed who, uint256 amount);

    function deposit(uint256 lockSeconds) external payable {
        require(msg.value > 0, "zero deposit");
        balances[msg.sender] += msg.value;
        unlockAt[msg.sender] = block.timestamp + lockSeconds;
        emit Deposited(msg.sender, msg.value, unlockAt[msg.sender]);
    }

    function withdraw() external {
        require(block.timestamp >= unlockAt[msg.sender], "still locked");
        uint256 amount = balances[msg.sender];
        balances[msg.sender] = 0;
        (bool ok, ) = msg.sender.call{value: amount}("");
        require(ok, "transfer failed");
        emit Withdrawn(msg.sender, amount);
    }
}

Deploy with Ignition

Exactly the same Ignition module and the same CLI command as in Module 14 — the only difference is the --network besu flag.

# ignition/modules/Vault.ts
// import { buildModule } from "@nomicfoundation/hardhat-ignition/modules";
// export default buildModule("VaultModule", (m) => {
//   const vault = m.contract("Vault");
//   return { vault };
// });

# Deploy to your Besu network
npx hardhat ignition deploy ignition/modules/Vault.ts --network besu

Permissioning

In a public Ethereum network, anyone can run a node and anyone can submit transactions from any address. That is a feature on mainnet and a bug in a regulated consortium. Besu's permissioning system lets you control exactly who can connect to your network and who can transact on it.

Private Transactions

Even in a permissioned consortium, you rarely want every member to see every transaction. Two banks negotiating a bilateral deal do not want a third bank watching the numbers. Besu solves this with privacy groups, backed by a companion component called Tessera.

Exercise & Self-Check

Time to get your hands dirty. The exercises below walk you from zero to a running Besu network with a deployed contract and a permissioning rule. Do at least the first three on real hardware — the muscle memory matters.