Genesis Configuration

The genesis file defines the initial state and rules for a Besu network. This reference covers all configurable parameters.

Genesis Structure

A Besu genesis file has this structure:

{
  "config": {
    "chainId": 1337,
    "berlinBlock": 0,
    "qbft": {
      "blockperiodseconds": 5,
      "epochlength": 30000,
      "requesttimeoutseconds": 10
    }
  },
  "nonce": "0x0",
  "timestamp": "0x0",
  "gasLimit": "0x1c9c380",
  "difficulty": "0x1",
  "mixHash": "0x63746963616c2062797a616e74696e65206661756c7420746f6c6572616e6365",
  "extradata": "0x...",
  "alloc": {
    "0xaddress1": { "balance": "1000000000000000000000" }
  }
}

Config Parameters

Chain ID

Unique identifier for the chain. Prevents replay attacks between networks.

"chainId": 1337

• Use values > 1000 for private networks
• Must match the chain ID used when signing transactions
• Cannot be changed after genesis

Consensus

QBFT (Recommended)

"qbft": {
  "blockperiodseconds": 5,
  "epochlength": 30000,
  "requesttimeoutseconds": 10
}

Parameter	Description	Default	Production
blockperiodseconds	Target time between blocks	5	2-5
epochlength	Blocks per epoch (validator set checkpoint)	30000	30000
requesttimeoutseconds	Timeout for consensus round	10	10

IBFT 2.0

"ibft2": {
  "blockperiodseconds": 5,
  "epochlength": 30000,
  "requesttimeoutseconds": 10,
  "messageQueueLimit": 1000,
  "duplicateMessageLimit": 100,
  "futureMessagesLimit": 1000,
  "futureMessagesMaxDistance": 10
}

Clique

"clique": {
  "blockperiodseconds": 15,
  "epochlength": 30000
}

EVM Fork Configuration

Enable Ethereum hard fork features by setting the block number where each fork activates:

"config": {
  "chainId": 1337,
  "homesteadBlock": 0,
  "eip150Block": 0,
  "eip155Block": 0,
  "eip158Block": 0,
  "byzantiumBlock": 0,
  "constantinopleBlock": 0,
  "petersburgBlock": 0,
  "istanbulBlock": 0,
  "berlinBlock": 0,
  "londonBlock": 0,
  "shanghaiTime": 0
}

Set all to 0 to enable all features from the genesis block (recommended for new private networks).

Gas Limit

Maximum gas per block. Controls how many transactions fit in a block.

"gasLimit": "0x1c9c380"

Value (hex)	Value (decimal)	Typical use
0x1c9c380	30,000,000	Default, good for most networks
0x3B9ACA00	1,000,000,000	High throughput networks
0x47B760	4,700,000	Ethereum mainnet-equivalent

Extradata

For QBFT/IBFT, extradata encodes the initial validator set. ChainLaunch generates this automatically when you create a network.

Format: 0x + 32 bytes vanity + RLP-encoded validator list + seal data

You generally don't need to set this manually — ChainLaunch computes it from the validator addresses you provide.

Alloc (Pre-funded Accounts)

Pre-fund accounts with ETH at genesis:

"alloc": {
  "0xfe3b557e8fb62b89f4916b721be55ceb828dbd73": {
    "balance": "0xad78ebc5ac6200000"
  },
  "0x627306090abaB3A6e1400e9345bC60c78a8BEf57": {
    "balance": "1000000000000000000000",
    "comment": "1000 ETH for deployer"
  }
}

Balances are in wei (1 ETH = 10^18 wei). You can use hex or decimal notation.

Amount	Wei	Hex
1 ETH	1000000000000000000	0xde0b6b3a7640000
100 ETH	100000000000000000000	0x56bc75e2d63100000
1000 ETH	1000000000000000000000	0x3635c9adc5dea00000

ChainLaunch Genesis Defaults

When you create a Besu network in ChainLaunch, these defaults are applied:

Parameter	Default
Consensus	QBFT
Chain ID	1337
Block period	5 seconds
Epoch length	30000
Gas limit	30,000,000
EVM forks	All enabled from block 0
Initial balance	1000 ETH per validator

You can override any of these during network creation.

Next Steps

• Create a Besu Network to use these parameters
• Manage Validators to modify the validator set after genesis
• Besu Overview for consensus mechanism comparison