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:

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 CLI

Create a network programmatically. Pass a JSON config file matching the platform's network shape (see the --config examples):

chainlaunch networks besu create \
  --name prod-besu-network \
  --description "Production Besu network" \
  --config /path/to/besu-network.json

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 CLI

chainlaunch besu create \
  --name validator-1 \
  --network-id 123 \
  --p2p-port 30303 \
  --rpc-port 8545 \
  --key-id 1

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 CLI

chainlaunch besu create \
  --name bootnode-1 \
  --network-id 123 \
  --key-id 2

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 CLI

Start all nodes (no network start API today — start each node):

for n in validator-1 validator-2 bootnode-1; do
  chainlaunch nodes start "$n"
done

Start specific node:

chainlaunch nodes start validator-1     # by slug
chainlaunch nodes start 123             # by numeric ID

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 CLI:

chainlaunch nodes get validator-1

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
chainlaunch nodes logs validator-1 --tail 100

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