EIP-7949

Genesis File Format

Schema for `genesis.json` files

DraftInformational

创建时间: 2025-05-19

Justin Florentine (@jflo) <[email protected]>, Jochem Brouwer (@jochem-brouwer) <[email protected]>, Barnabas Busa (@barnabasbusa) <[email protected]>

社区讨论原文链接编辑

1 分钟了解

欢迎补充好内容

去提交

正文

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)
`<hardfork(Block\|Time)>`	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.	(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


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

Blob Parameter Only Hardforks

eth_config JSON-RPC method

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

扩展阅读

欢迎补充好内容

去提交

不想错过最新的 EIP 动态？

订阅 EIPs Fun 周刊以跟进相关更新，建⽴你与 EIP 之间的连接，更好地建设以太坊。

详情

Genesis File Format

相关视频

正文

Abstract

Motivation

Specification

Top-Level Fields

`config` Object

`blobSchedule` Object

`alloc` Object

JSON Schema

Rationale

Security Considerations

Copyright

不想错过最新的 EIP 动态？

资源

支持社区

Genesis File Format

相关视频

正文

Abstract

Motivation

Specification

Top-Level Fields

config Object

blobSchedule Object

alloc Object

JSON Schema

Rationale

Security Considerations

Copyright

不想错过最新的 EIP 动态？

资源

支持社区

`config` Object

`blobSchedule` Object

`alloc` Object