EIP-7949: Genesis File Format
Schema for `genesis.json` files
| Authors | Justin Florentine (@jflo) <justin@florentine.us>, Jochem Brouwer (@jochem-brouwer) <jochem@ethereum.org> |
|---|---|
| Created | 2025-05-19 |
| Discussion Link | https://ethereum-magicians.org/t/eip-xxxx-genesis-json-standardization/24271 |
Table of Contents
Abstract
This EIP defines a canonical structure for Ethereum genesis files (genesis.json) used to bootstrap Ethereum networks. The standard aligns with the de facto structure implemented by Geth (Go-Ethereum), and already adopted by other clients. It introduces a JSON Schema to ensure consistency and tool compatibility across clients.
Motivation
The lack of an official standard for the genesis.json file has led to incompatibilities, bugs and confusion, as well as added workload for those running multiple clients together in test networks. This EIP aims to reduce ambiguity by defining a consistent structure and enabling tooling through schema-based validation.
Specification
The canonical genesis file MUST be a JSON object with the following top-level fields:
Top-Level Fields
| Field | Description |
|---|---|
config |
Chain configuration object. |
alloc |
Map of addresses to pre-allocated balances and/or code/storage. |
nonce |
Decimal or Hex nonce. |
timestamp |
Decimal or Hex UNIX timestamp. |
extraData |
Arbitrary extra data. |
gasLimit |
Decimal or Hex block gas limit. |
difficulty |
Decimal or Hex block difficulty. |
mixhash |
Hex mix hash. |
coinbase |
Hex address. |
config Object
The config object contains hardfork activation block numbers and fork configurations. Known keys include:
| Field | Description |
|---|---|
chainId |
unique identifier for the blockchain. |
<hardfork(Block\|Time)> |
block height or timestamp to activate the named hardfork. |
terminalTotalDifficulty |
difficulty after which to switch from PoW to PoS. |
depositContractAddress |
Ethereum address for the deposit contract |
blobSchedule |
Map of hardforks and their EIP-4844 DAS configuration parameters. |
blobSchedule Object
| Field | Description |
|---|---|
target |
desired number of blobs to include per block |
max |
maximum number of blobs to include per block |
baseFeeUpdateFraction |
input to pricing formula per EIP-4844 |
alloc Object
The alloc field defines the initial state at genesis. It maps addresses (as lowercase hex strings) to the following object:
| Field | Description |
|---|---|
balance |
decimal balance in wei. |
code |
Hex-encoded EVM bytecode. |
nonce |
Decimal or Hex value. |
storage |
Key-value hex map representing initial storage. |
JSON Schema
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$defs": {
"hexOrDecimal48": {
"type": "string",
"pattern": "^((0x[0-9a-f]{1,12})|[0-9]{1,15})$"
},
"hexOrDecimal": {
"type": "string",
"pattern": "^((0x[0-9a-f]+)|[0-9]+)$"
},
"address": {
"type": "string",
"pattern": "^0x[0-9a-fA-F]{40}$"
},
"hash": {
"type": "string",
"pattern": "^0x[0-9a-f]{64}$"
}
},
"title": "Ethereum Genesis File",
"type": "object",
"required": ["alloc", "gasLimit", "difficulty"],
"properties": {
"config": {
"type": "object",
"properties": {
"chainId": { "type": "integer" },
"homesteadBlock": { "type": "integer" },
"daoForkBlock": { "type": "integer" },
"eip150Block": { "type": "integer" },
"tangerineWhistleBlock": {"type": "integer"},
"eip155Block": { "type": "integer" },
"spuriousDragonBlock": {"type": "integer"},
"byzantiumBlock": { "type": "integer" },
"constantinopleBlock": { "type": "integer" },
"petersburgBlock": { "type": "integer" },
"istanbulBlock": { "type": "integer" },
"muirGlacierBlock": {"type": "integer"},
"berlinBlock": { "type": "integer" },
"londonBlock": { "type": "integer" },
"arrowGlacierBlock": { "type": "integer" },
"grayGlacierBlock": { "type": "integer" },
"terminalTotalDifficulty": { "type": "integer" },
"mergeNetsplitBlock": { "type": "integer"},
"shanghaiTime": { "type": "integer"},
"cancunTime": { "type": "integer"},
"pragueTime": { "type": "integer"},
"osakaTime": { "type": "integer"},
"depositContractAddress": { "$ref": "#/$defs/address"},
"blobSchedule": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"target": { "type": "integer" },
"max": { "type" : "integer" },
"baseFeeUpdateFraction": { "type" : "integer" }
}
}
}
},
"additionalProperties": true
},
"nonce": { "$ref": "#/$defs/hexOrDecimal48" },
"timestamp": { "$ref": "#/$defs/hexOrDecimal48" },
"extraData": {
"anyOf": [
{"type": "string", "const": "" },
{"type": "string", "pattern": "^0x([0-9a-fA-F]{2})*$" }
]
},
"gasLimit": { "$ref": "#/$defs/hexOrDecimal48" },
"difficulty": { "$ref": "#/$defs/hexOrDecimal48" },
"mixhash": { "$ref": "#/$defs/hash" },
"coinbase": { "$ref": "#/$defs/address" },
"alloc": {
"type": "object",
"patternProperties": {
"^(0x)?[0-9a-fA-F]{40}$": {
"type": "object",
"properties": {
"balance": { "$ref": "#/$defs/hexOrDecimal" },
"nonce": { "$ref": "#/$defs/hexOrDecimal48" },
"code": { "type": "string", "pattern": "^0x([0-9a-f])*$" },
"storage": {
"type": "object",
"patternProperties": {
"^0x[0-9a-f]{64}$": {
"$ref": "#/$defs/hash"
}
}
}
}
},
"additionalProperties": false
},
"additionalProperties":false
}
},
"additionalProperties": true
}
Rationale
There are a growing number of EIPs that propose improvements to how a network is configured at genesis:
Add Blob Schedule to EL Config File
However, the root configuration element these amend remains unspecified. Adopting a minimal schema to define that will make subsequent changes more accurate and concise.
Security Considerations
Since this is an optional and informational EIP, which offers only developer convenience, and must be used with admin access to the node, no new security concerns are introduced.
Copyright
Copyright and related rights waived via CC0.
Citation
Please cite this document as:
Justin Florentine (@jflo) <justin@florentine.us>, Jochem Brouwer (@jochem-brouwer) <jochem@ethereum.org>, "EIP-7949: Genesis File Format [DRAFT]," Ethereum Improvement Proposals, no. 7949, May 2025. [Online serial]. Available: https://eips.ethereum.org/EIPS/eip-7949.