Genesis file items
The Besu genesis file contains network configuration items and genesis block parameters.
Genesis item names are case-insensitive, except account addresses in alloc.
The examples on this page use the casing used in Besu's built-in genesis files.
Configuration items
Network configuration items are specified in the genesis file in the config object.
| Item | Description |
|---|---|
| Milestone blocks | Protocol milestone activation points for the network. |
chainId | Chain ID for the network. |
ethash | Specifies that the network uses Ethash and contains fixeddifficulty. |
ibft2 | Specifies that the network uses IBFT 2.0 and contains IBFT 2.0 configuration items. |
qbft | Specifies that the network uses QBFT and contains QBFT configuration items. |
transitions | Specifies the block at which to change IBFT 2.0 or QBFT validators. |
contractSizeLimit | Maximum contract size in bytes. Specify in free gas networks. The default is 24576 and the maximum size is 2147483647. |
evmStackSize | Maximum stack size. Specify to increase the maximum stack size in private networks with complex smart contracts. The default is 1024. |
ecCurve | Specifies the elliptic curve to use. The default is secp256k1. |
discovery | Specifies discovery configuration items. The discovery object can be left empty. |
zeroBaseFee | Specifies a base fee of 0 for free gas networks. |
fixedBaseFee | Specifies a constant base fee for blocks, overriding the dynamic base fee calculation of Ethereum Improvement Proposal 1559 (EIP-1559). |
depositContractAddress | Address for the Ethereum staking contract. |
withdrawalRequestContractAddress | Address for the withdrawal request contract. |
consolidationRequestContractAddress | Address for the consolidation request contract. |
blobSchedule | Specifies blob schedule configuration items. |
Genesis block parameters
Genesis block parameters are specified as top-level fields in the genesis file, outside of config.
| Item | Description |
|---|---|
alloc | Defines accounts with balances or contracts. |
baseFeePerGas | Genesis block base fee per gas, in Wei. Specify as a decimal or hexadecimal string. If omitted and londonBlock is 0, Besu uses 1000000000. |
blobGasUsed | Blob gas used in the genesis block. Besu applies this value when Cancun is active at genesis. The default is 0x0. |
coinbase | Beneficiary address in the genesis block. If omitted, Besu uses the zero address. |
difficulty | Difficulty value in the genesis block. The required value depends on the consensus protocol. |
excessBlobGas | Excess blob gas in the genesis block. Besu applies this value when Cancun is active at genesis. The default is 0x0. |
extraData | Extra data in the genesis block. For IBFT 2.0 and QBFT, this contains the validator list and consensus metadata. |
gasLimit | Block gas limit. Total gas limit for all transactions in a block. |
mixHash | Mix hash value in the genesis block. The required value depends on the consensus protocol. |
nonce | Used in block computation. Can be any value in the genesis block. The default is 0x0. |
parentBeaconBlockRoot | Parent beacon block root in the genesis block. Besu applies this value when Cancun is active at genesis. The default is the zero hash. |
parentHash | Parent hash in the genesis block. |
slotNumber | Slot number in the genesis block. Besu applies this value when Amsterdam is active at genesis. The default is 0x0. |
timestamp | Creation date and time of the genesis block. Must be before the next block, so we recommend specifying 0x0. |
If a Supplied genesis block does not match stored chain data error occurs, use the genesis file matching the genesis block of the data directory, or use the --data-path option to specify a different data directory.
Milestone configuration items
Milestone items activate protocol changes for the network.
Use terminalTotalDifficulty for the Paris transition (The Merge).
Use block-number milestone items for pre-merge forks and timestamp milestone
items for post-merge forks (Shanghai and later).
See the Ethereum execution specs protocol history for Mainnet activation blocks and timestamps.
{
"config": {
"homesteadBlock": 1150000,
"daoForkBlock": 1920000,
"eip150Block": 2463000,
"eip158Block": 2675000,
"byzantiumBlock": 4370000,
"constantinopleBlock": 7280000,
"constantinopleFixBlock": 7280000,
"istanbulBlock": 9069000,
"muirGlacierBlock": 9200000,
"berlinBlock": 12244000,
"londonBlock": 12965000,
"arrowGlacierBlock": 13773000,
"grayGlacierBlock": 15050000,
"terminalTotalDifficulty": 58750000000000000000000,
"shanghaiTime": 1681338455,
"cancunTime": 1710338135,
"pragueTime": 1746612311,
"osakaTime": 1764798551,
"bpo1Time": 1765290071,
"bpo2Time": 1767747671
}
}
Ensure you include a milestone far enough in advance in the genesis file. Not doing so can lead to unexpected and inconsistent behavior without specific errors.
In private networks, the milestone block defines the protocol version for the network.
{
"config": {
...
"berlinBlock": 0,
...
},
}
In private networks, we recommend specifying the latest milestone block. It's implied this includes the preceding milestones. This ensures you use the most up-to-date protocol and have access to the most recent opcodes.
Blob schedule configuration items
Use the blobSchedule object to configure blob gas parameters for Cancun,
Prague, and Blob Parameter Only (BPO) forks.
| Item | Description |
|---|---|
target | Target number of blobs per block for the fork. |
max | Maximum number of blobs per block for the fork. |
baseFeeUpdateFraction | Denominator used to update the blob base fee for the fork. |
{
"config": {
"blobSchedule": {
"cancun": {
"target": 3,
"max": 6,
"baseFeeUpdateFraction": 3338477
},
"prague": {
"target": 6,
"max": 9,
"baseFeeUpdateFraction": 5007716
}
}
}
}
Discovery configuration items
Use the discovery configuration items to specify the bootnodes and discovery-dns-url in the genesis file, in place of using CLI options or listing them in the configuration file.
The genesis file can take discovery v4 bootnodes (specified as enode URLs using the bootnodes option) and discovery v5 bootnodes (specified as ENR URLs using the v5Bootnodes option).
To use discovery v5 bootnodes, set the early access option --Xv5-discovery-enabled to true.
If any option is specified using the command line or configuration file, it takes precedence over the genesis file.
{
"config": {
"discovery": {
"bootnodes": [
"enode://c35c3...d615f@1.2.3.4:30303",
"enode://f42c13...fc456@1.2.3.5:30303"
],
"v5Bootnodes": [
"enr:-Mq4QL...DdWRwgiMo",
"enr:-Ku4QLV...IN1ZHCCIyk"
],
"dns": "enrtree://AM5FCQLWIZX2QFPNJAP7VUERCCRNGRHWZG3YYHIUV7BVDQ5FDPRT2@nodes.example.org"
}
}
}
Fixed difficulty
PoW consensus is deprecated in Besu version 24.11.0 and later. Please read this blog post for more context on the rationale behind this decision as well as alternative options.
Use fixeddifficulty to specify a fixed difficulty in private networks using Ethash. This keeps the network's difficulty constant and overrides the difficulty parameter from the genesis file.
{
"config": {
"ethash": {
"fixeddifficulty": 1000
}
}
}
Using fixeddifficulty is not recommended for use with Ethash outside of test environments. For production networks using Ethash, we recommend setting a low difficulty value in the genesis file instead. Ethash will adjust the difficulty of the network based on hashrate to produce blocks at the targeted frequency.