Hyperledger Besu Enterprise Ethereum Quickstart Guide

Hyperledger Besu stands as a leading enterprise-grade Ethereum client designed for businesses seeking to leverage blockchain technology with full compatibility with the public Ethereum mainnet. This guide walks you through setting up a private enterprise Ethereum network using Hyperledger Besu, interacting via JSON-RPC, deploying decentralized applications (DApps) with Truffle, and monitoring node performance—all in a secure, controlled environment.

Whether you're a developer exploring enterprise blockchain or an architect evaluating solutions, this hands-on tutorial delivers practical insights into building and managing permissioned Ethereum networks.

Setting Up Your Enterprise Ethereum Network

The fastest way to get started with Hyperledger Besu is by using the official besu-quickstart repository. This preconfigured setup leverages Docker to spin up a realistic multi-node network in minutes.

Begin by cloning the quickstart repository:

git clone https://github.com/PegaSysEng/besu-quickstart.git

Navigate into the project directory:

cd besu-quickstart

Launch the network using the provided script:

./run.sh

This command builds the necessary Docker images and starts six Besu nodes across four containers, including:

• A bootnode for peer discovery
• A mining node that creates new blocks
• Regular nodes for transaction processing
• An RPC node for external access

Upon completion, you'll see output listing all active Docker containers and their status. Each container exposes critical services on specific ports, enabling seamless integration with development tools and monitoring platforms.

👉 Discover how enterprise blockchain can transform your business operations today.

Accessing Network Endpoints and Services

After launching the network, you’ll receive a summary of available endpoints:

JSON-RPC HTTP service endpoint : http://localhost:32768/jsonrpc  
JSON-RPC WebSocket service endpoint : ws://localhost:32768/jsonws  
GraphQL HTTP service endpoint : http://localhost:32768/graphql  
Web block explorer address : http://localhost:32768  
Prometheus address : http://localhost:32768/prometheus/graph  
Grafana address : http://localhost:32768/grafana-dashboard

These endpoints empower developers and operators:

• JSON-RPC HTTP/WS: For DApp interactions and wallet integrations (e.g., MetaMask)
• GraphQL: Enables flexible querying of blockchain data
• Block Explorer: Visualize blocks, transactions, and addresses in real time
• Prometheus & Grafana: Monitor node health, sync status, and performance metrics

To redisplay these endpoints at any time, run:

./list.sh

This is especially useful when managing multiple environments or troubleshooting connectivity issues.

Exploring Blockchain Data with the Web Block Explorer

The built-in block explorer provides a user-friendly interface for inspecting your private network. Open your browser and navigate to http://localhost:32768.

Here, you can:

• View the latest blocks and their details (gas used, timestamp, miner)
• Inspect individual transactions (from/to addresses, value, status)
• Search by block number, transaction hash, or Ethereum address using the search bar (magnifying glass icon)

You'll notice six active Besu nodes:

• One bootnode
• One mining node
• Four regular nodes

This distributed architecture mimics real-world enterprise deployments, offering fault tolerance and scalability.

Monitoring Node Health with Prometheus and Grafana

Operational visibility is crucial in enterprise environments. Besu integrates seamlessly with industry-standard monitoring tools:

• Prometheus collects time-series metrics such as block height, peer count, and memory usage.
• Grafana visualizes these metrics through customizable dashboards.

Access Grafana at http://localhost:32768/grafana-dashboard to view preconfigured panels showing:

• Network synchronization status
• Transaction throughput
• Node uptime and resource consumption

These insights help identify bottlenecks, ensure high availability, and support proactive maintenance—key requirements for production blockchain systems.

Interacting with Besu via JSON-RPC

Besu fully supports the Ethereum JSON-RPC API, enabling programmatic interaction with the blockchain.

Use curl to query node information. For example, check the client version:

curl -X POST --data '{
  "jsonrpc":"2.0",
  "method":"web3_clientVersion",
  "params":[],
  "id":1
}' http://localhost:32768/jsonrpc

Response:

{ "jsonrpc": "2.0", "id": 1, "result": "besu/..." }

Check connected peers:

curl -X POST --data '{
  "jsonrpc":"2.0",
  "method":"net_peerCount",
  "params":[],
  "id":1
}' http://localhost:32768/jsonrpc

Result: "0x6" indicates six connected peers.

Get the latest block number:

curl -X POST --data '{
  "jsonrpc":"2.0",
  "method":"eth_blockNumber",
  "params":[],
  "id":1
}' http://localhost:32768/jsonrpc

👉 Learn how secure blockchain infrastructure powers next-gen financial applications.

Deploying DApps with Truffle on Besu

Truffle simplifies smart contract development and deployment. Let’s deploy the classic Pet Shop DApp on our Besu network.

Install Truffle globally:

npm install -g truffle

Create a project directory:

mkdir pet-shop-tutorial && cd pet-shop-tutorial

Download the Pet Shop box:

truffle unbox pet-shop

Install the HD wallet provider:

npm install --save @truffle/hdwallet-provider

Update truffle-config.js with your RPC endpoint and private key:

const PrivateKeyProvider = require("@truffle/hdwallet-provider");
const privateKey = "8f2a55949038a9610f50fb23b5883af3b4ecb3c3bb792cbcefbd1542c692be63";

module.exports = {
  networks: {
    quickstartWallet: {
      provider: () => new PrivateKeyProvider(privateKey, "http://localhost:32768/jsonrpc"),
      network_id: "*"
    }
  }
};

Deploy contracts:

truffle migrate --network quickstartWallet

Run tests:

truffle test --network quickstartWallet

All transactions are processed on your private Besu network—secure, fast, and gas-free.

Managing the Network Lifecycle

Control your environment with simple scripts:

• Stop the network (keeps containers):

  ./stop.sh

• Resume operation:

  ./resume.sh

• Fully remove containers and data:

  ./remove.sh

These commands streamline development workflows and ensure clean state management between test cycles.

Frequently Asked Questions

Q: What is Hyperledger Besu used for?
A: Besu is an open-source Ethereum client tailored for enterprise use, supporting both public and private networks with features like permissioning, privacy, and enterprise-grade monitoring.

Q: Does Besu support smart contracts?
A: Yes. Besu fully supports Solidity-based smart contracts and is compatible with tools like Truffle, Hardhat, and Remix.

Q: Can I connect MetaMask to my Besu network?
A: Absolutely. Add a custom RPC network in MetaMask using the JSON-RPC endpoint (http://localhost:32768/jsonrpc) and import one of the predefined accounts.

Q: Is mining enabled in this setup?
A: Yes. The quickstart uses Proof-of-Authority (IBFT 2.0), where the designated miner node generates blocks automatically.

Q: How do I add more nodes to the network?
A: You can extend the Docker Compose configuration or use static nodes files to bootstrap additional instances.

Q: Is this suitable for production?
A: While this tutorial uses a simplified setup, Besu itself is production-ready. For production use, implement TLS, authentication, and robust node distribution.

Core Keywords

Hyperledger Besu, enterprise Ethereum, private blockchain, JSON-RPC, Truffle, DApp development, blockchain monitoring, smart contracts

👉 Start building secure, scalable blockchain solutions with cutting-edge tools now.