--- eip: 7949 title: Genesis File Format description: Schema for `genesis.json` files author: Justin Florentine (@jflo) , Jochem Brouwer (@jochem-brouwer) , Barnabas Busa (@barnabasbusa) discussions-to: https://ethereum-magicians.org/t/eip-xxxx-genesis-json-standardization/24271 status: Draft type: Informational created: 2025-05-19 --- ## 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 | Type | Description | Example | |-----------------|---------|------------------------------------------------------------------|---------| | `config` | Object | Chain configuration object. | (see below) | | `alloc` | Object | Map of addresses to pre-allocated balances and/or code/storage. | (see below) | | `nonce` | String | Block nonce as a hex string. | `0x0` | | `timestamp` | String | UNIX timestamp as a hex string. | `0x6720f180` | | `extraData` | String | Arbitrary extra data as hex string. | `0x00` | | `gasLimit` | String | Block gas limit as a hex string. | `0x1c9c380` | | `difficulty` | String | Block difficulty as a hex string. | `0x1` | | `mixhash` | String | Mix hash as a hex string. | `0x0000000000000000000000000000000000000000000000000000000000000000` | | `coinbase` | String | Coinbase address as a hex string. | `0x0000000000000000000000000000000000000000` | ### `config` Object The `config` object contains hardfork activation block numbers and fork configurations. Known keys include: | Field | Type | Description | Example | |---------------------------|---------|----------------------------------------------------------------------------------|---------| | `chainId` | Integer | Unique identifier for the blockchain as a decimal integer. | `1` (mainnet) | | `` | Integer | Block height or timestamp to activate the named hardfork as a decimal integer. | `shanghaiTime: 1681338455` | | `terminalTotalDifficulty` | String | Total difficulty after which to switch from PoW to PoS as a hex string. | `0xc70d815d562d3cfa955` | | `depositContractAddress` | String | Ethereum address for the deposit contract as a hex string. | `0x00000000219ab540356cBB839Cbe05303d7705Fa` | | `blobSchedule` | Object | Map of hardforks and their EIP-4844 DAS [configuration parameters](eip-7840.md). | (see below) | ### `blobSchedule` Object | Field | Type | Description | Example | |-------------------------|---------|------------------------------------------------------------------|---------| | `target` | Integer | Desired number of blobs to include per block as a decimal integer. | `3` | | `max` | Integer | Maximum number of blobs to include per block as a decimal integer. | `6` | | `baseFeeUpdateFraction` | Integer | Input to pricing formula per EIP-4844 as a decimal integer. | `3338477` | ### `alloc` Object The `alloc` field defines the initial state at genesis. It maps addresses (as hex strings) to the following object: | Field | Type | Description | Example | |----------------|---------|---------------------------------------------------------------------|---------| | `balance` | String | Account balance in wei as a hex string. | `0xde0b6b3a7640000` (1 ETH) | | `code` | String | EVM bytecode as a hex string. | `0x6060604052600436106100af576000357c0100000000000000000000000000000000000000000000000000000000` | | `nonce` | String | Account nonce as a hex string. | `0x0` | | `storage` | Object | Key-value map where keys and values are 32-byte hex strings representing storage slots. | `"0x0000000000000000000000000000000000000000000000000000000000000001": "0x00000000000000000000000000000000000000000000000000000000000000ff"` | ### JSON Schema ```json { "$schema": "http://json-schema.org/draft-07/schema#", "$defs": { "hexUint": { "type": "string", "pattern": "^0x[0-9a-fA-F]+$" }, "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": { "$ref": "#/$defs/hexUint" }, "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/hexUint" }, "timestamp": { "$ref": "#/$defs/hexUint" }, "extraData": { "anyOf": [ {"type": "string", "const": "" }, {"type": "string", "pattern": "^0x([0-9a-fA-F]{2})*$" } ] }, "gasLimit": { "$ref": "#/$defs/hexUint" }, "difficulty": { "$ref": "#/$defs/hexUint" }, "mixhash": { "$ref": "#/$defs/hash" }, "coinbase": { "$ref": "#/$defs/address" }, "alloc": { "type": "object", "patternProperties": { "^0x[0-9a-fA-F]{40}$": { "type": "object", "properties": { "balance": { "$ref": "#/$defs/hexUint" }, "nonce": { "$ref": "#/$defs/hexUint" }, "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](eip-7840) [Blob Parameter Only Hardforks](eip-7892) [eth_config JSON-RPC method](eip-7910) However, the root configuration element amended by these 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](../LICENSE.md).