Create a Besu Network

This guide walks you through creating a new Hyperledger Besu blockchain network using ChainLaunch.

Prerequisites

• ChainLaunch server running and accessible
• User account with NETWORK_CREATE permission
• Basic understanding of blockchain networks and Besu

Network Parameters

Before creating a network, decide on these parameters:

Parameter	Description	Example
Network Name	Unique identifier for your network	prod-besu-network
Consensus Mechanism	PoW, PoA, Clique, or IBFT 2.0	IBFT_2
Chain ID	Unique identifier for the chain (prevent replay attacks)	2024
Network ID	P2P network identifier	2024
Block Time	Target block production time in seconds	12
Validator Count	Initial number of validators	3-5
Initial Accounts	Pre-funded accounts for testing	See below

Step 1: Create Network via UI

Navigate to Networks

1. Click Networks in the main menu
2. Click Create Network button
3. Select Besu from the network type options

Enter Basic Information

1. Network Name

   • Enter a descriptive name: prod-network or dev-testnet
   • Must be unique across your system
   • Only alphanumeric characters and hyphens

2. Description (optional)

   • Document the network's purpose
   • Example: Production network for our DeFi platform

Configure Genesis Parameters

1. Consensus Mechanism

   • Select from: Proof of Work, Proof of Authority, Clique, IBFT 2.0
   • Recommended: IBFT 2.0 for production networks

2. Chain ID

   • Enter a unique number (typically 1000-9999 for private networks)
   • Example: 2024
   • Used to identify the chain

3. Network ID

   • Enter peer discovery ID (can be same as Chain ID)
   • Example: 2024
   • Used for P2P networking

4. Block Time

   • Enter target block production in seconds
   • IBFT: 12-15 seconds recommended
   • PoA: 5-15 seconds
   • Default: 12

Configure Consensus Parameters

For IBFT 2.0:

• Block Period: Seconds between blocks (default: 5)
• Request Timeout: Timeout for block proposals (default: 10s)
• Epoch Length: Blocks per epoch (default: 30000)
• Round Change Timeout: Timeout for round changes (default: 3s)

For Proof of Authority:

• Signer Count: Number of initial signers (validators)
• Signer Period: Seconds between signers producing blocks
• Allow In-Mining Block: Allow mining while signing (yes/no)

Create Initial Accounts

ChainLaunch can pre-fund test accounts with ETH:

1. Click Add Account
2. Enter public address (or generate new key)
3. Enter initial balance in ETH
4. Repeat for each account

Example Initial Accounts:

0x123456... : 1000 ETH (Deployer)
0x789012... : 500 ETH (Test user 1)
0x345678... : 500 ETH (Test user 2)

Set Validators

1. Click Add Validator
2. Enter validator address
3. Repeat for desired number of validators
4. Recommended: 3-5 validators for consensus

Configure Advanced Options

1. Fork ID (advanced)

   • Leave default unless upgrading network version

2. Difficulty (for PoW only)

   • Set mining difficulty target

3. Gas Limit

   • Maximum gas allowed per block
   • Default: 30000000 (30M)

4. Extradata

   • Additional data to include in genesis block
   • Usually empty or reserved for DAO voting

Review and Create

1. Review all parameters
2. Check validator addresses are correct
3. Click Create Network
4. Wait for genesis block generation

Step 2: Create Network via API

Create a network programmatically:

curl -X POST http://localhost:8100/api/v1/networks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "prod-besu-network",
    "type": "besu",
    "description": "Production Besu network",
    "genesis": {
      "chain_id": 2024,
      "network_id": 2024,
      "consensus": "IBFT_2",
      "block_time": 12,
      "difficulty": "0x1",
      "gas_limit": "0x1c9c380",
      "validators": [
        "0xAA36A7D6FB3E7F6FF89A4ECEF5E27D28B37B74E3",
        "0xBB36A7D6FB3E7F6FF89A4ECEF5E27D28B37B74E4",
        "0xCC36A7D6FB3E7F6FF89A4ECEF5E27D28B37B74E5"
      ],
      "accounts": {
        "0xDD36A7D6FB3E7F6FF89A4ECEF5E27D28B37B74E6": {
          "balance": "1000000000000000000000"
        }
      }
    }
  }'

Response:

{
  "id": "network-123",
  "name": "prod-besu-network",
  "type": "besu",
  "status": "created",
  "genesis_block_hash": "0x...",
  "chain_id": 2024,
  "created_at": "2024-01-15T10:30:00Z"
}

Step 3: Deploy Validator Nodes

After creating the network, deploy validator nodes:

Via UI

1. Go to Networks → prod-besu-network
2. Click Add Node
3. Select Validator Node
4. Enter node name (e.g., validator-1)
5. Configure resources:
   • CPU: 2-4 cores recommended
   • Memory: 4-8 GB recommended
6. Click Create
7. Repeat for each validator (3-5 recommended)

Via API

curl -X POST http://localhost:8100/api/v1/networks/network-123/nodes \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "validator-1",
    "type": "validator",
    "network_id": "network-123",
    "port": 30303,
    "rpc_port": 8545,
    "ws_port": 8546,
    "resources": {
      "cpu": "2",
      "memory": "4Gi"
    }
  }'

Step 4: Deploy Bootnode (Optional)

For networks with multiple validator groups, deploy a bootnode:

Via UI

1. Go to Networks → prod-besu-network
2. Click Add Node
3. Select Bootnode
4. Enter node name (e.g., bootnode-1)
5. Click Create

Via API

curl -X POST http://localhost:8100/api/v1/networks/network-123/nodes \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "bootnode-1",
    "type": "bootnode",
    "network_id": "network-123"
  }'

Step 5: Start the Network

Via UI

1. Go to Networks → prod-besu-network
2. Click Start Network
3. Select all nodes to start
4. Click Confirm
5. Wait for nodes to initialize (2-5 minutes)

Via API

Start all nodes:

curl -X POST http://localhost:8100/api/v1/networks/network-123/start \
  -H "Authorization: Bearer YOUR_API_KEY"

Start specific node:

curl -X POST http://localhost:8100/api/v1/nodes/node-123/start \
  -H "Authorization: Bearer YOUR_API_KEY"

Step 6: Verify Network Health

Check Node Status

Via UI:

1. Go to Networks → prod-besu-network
2. View node status (should show "Running")
3. Check block height increasing

Via API:

curl -X GET http://localhost:8100/api/v1/nodes/node-123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "id": "node-123",
  "name": "validator-1",
  "status": "running",
  "block_height": 42,
  "peer_count": 2,
  "uptime_seconds": 300
}

Query Network via JSON-RPC

Get latest block number:

curl -X POST http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "eth_blockNumber",
    "params": [],
    "id": 1
  }'

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0x2a"
}

Get validator list:

curl -X POST http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "ibft_getValidatorsByBlockNumber",
    "params": ["latest"],
    "id": 1
  }'

Consensus-Specific Configuration

IBFT 2.0 (Recommended for Production)

{
  "ibft": {
    "blockperiod": 5,
    "epochlength": 30000,
    "requesttimeoutms": 10000,
    "roundchangetimeoutms": 3000,
    "messageQueueLimit": 1000,
    "duplicateMessageLimit": 100,
    "futureRoundsLimit": 1000,
    "transmitOnEmptyPayload": true
  }
}

Proof of Authority (Quick Testing)

{
  "clique": {
    "period": 15,
    "epoch": 30000
  }
}

Proof of Work (Ethereum Compatible)

{
  "ethash": {
    "fixeddifficulty": 1000,
    "minBlockTime": 1
  }
}

Common Issues & Solutions

Validators Won't Start Consensus

Problem: Nodes running but no blocks being created

• Verify all validator addresses are in genesis file
• Check validator count is at least 2
• Ensure all validators are in "Running" state
• Check node logs for errors

Solution:

# View node logs
curl -X GET http://localhost:8100/api/v1/nodes/node-123/logs?tail=100 \
  -H "Authorization: Bearer YOUR_API_KEY"

Peer Connection Issues

Problem: Nodes isolated, not discovering each other

• Check bootnode is running
• Verify network connectivity between nodes
• Check enode URLs match
• Review firewall settings

Solution:

# Check peer count via RPC
curl -X POST http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "net_peerCount",
    "params": [],
    "id": 1
  }'

High Block Time

Problem: Blocks produced slower than expected

• Check CPU/memory utilization
• Verify network latency between validators
• Reduce block period in genesis
• Check for slow disk I/O

Next Steps

1. Monitor Network - Setup Prometheus

See Also

• Besu Networks Overview
• Network Management
• Besu Official Genesis Config