ChainLaunch

Genesis Configuration

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

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": {
  "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