Genesis File Format

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

Blob Paramter Only Hardforks

eth_config JSON-RPC method

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.