EIP-7949 Standard genesis file format (Genesis File Format)

No call decision · Networking & nodes · EIP status Draft · created 2025-05-19

Defines the standard structure of genesis.json, the configuration file used to first launch an Ethereum network. It formalizes the de facto standard structure used by Geth and provides a JSON Schema for validation.

Why it is needed

Ethereum networks start by reading a genesis.json file containing the contents of the first block (the genesis block) and the chain configuration. Until now, there has been no official standard for this file. Each client (node software) has roughly followed Geth's format, but with small differences in detail, causing compatibility problems, bugs, and confusion in multi-client test networks, and increasing operators' workload. The purpose of this EIP is to codify field names and formats so all clients use the same structure, and to attach a machine-checkable JSON Schema to reduce ambiguity. It is also a proposal to establish the underlying document on which future chain configuration EIPs can build, given that new EIPs related to chain configuration continue to appear.

What changes

Today

After EIP-7949

Who is affected

In depth

Top-level field structure

The genesis file is a JSON object with top-level fields config (the chain configuration object), alloc (a map of initial state by address), nonce, timestamp, extraData, gasLimit, difficulty, mixhash, and coinbase. Numeric fields are written as hex strings. For example, gasLimit might be 0x1c9c380, difficulty might be 0x1, and coinbase might be in the form 0x0000000000000000000000000000000000000000. The JSON Schema requires three fields: alloc, gasLimit, and difficulty, and allows undefined additional top-level properties (additionalProperties: true).

The config object: chain identification and hard fork schedule

The config object contains the chain identifier and hard fork activation times. chainId is written as a decimal integer (mainnet is 1). Hard fork activations use keys of the form <hardfork(Block|Time)> with a block height or timestamp written as a decimal integer, for example shanghaiTime: 1681338455. The schema enumerates block-based fork keys from homesteadBlock through londonBlock, arrowGlacierBlock, and grayGlacierBlock, and time-based fork keys such as shanghaiTime, cancunTime, pragueTime, and osakaTime. terminalTotalDifficulty, the threshold for the transition from proof of work to proof of stake, is written as a hex string, and depositContractAddress, the deposit contract address, is written as an address-formatted hex string.

The blobSchedule object: per-fork blob parameters

blobSchedule within config is a map with hard fork names as keys and EIP-4844 blob configuration parameters as values. Each entry has three decimal integer fields: target, the target number of blobs per block (e.g. 3); max, the maximum number of blobs per block (e.g. 6); and baseFeeUpdateFraction, an input value used in the EIP-4844 pricing formula (e.g. 3338477). This structure follows the configuration approach of EIP-7840, which decided to place the blob schedule in the execution client configuration file.

The alloc object: genesis initial state

alloc defines the initial state at genesis. It uses hex address strings as keys, and the value object can include balance (the balance in wei, as a hex string, e.g. 0xde0b6b3a7640000 equals 1 ETH), code (EVM bytecode as a hex string), nonce (the account nonce as a hex string), and storage (a map of storage slots with 32-byte hex string keys and values). This allows balances to be assigned to specific accounts from the network's launch, or contract code and storage to be pre-deployed.

JSON Schema and format rules

The source provides the full JSON Schema based on draft-07. Common formats are defined under $defs. hexUint follows the pattern ^0x[0-9a-fA-F]+$, address is a 40-digit hex pattern, and hash is a lowercase 64-digit hex pattern. The address keys in alloc are checked against the pattern ^0x[0-9a-fA-F]{40}$, and code only allows lowercase hex matching ^0x([0-9a-f])*$. extraData must be either an empty string or an even-length hex string (^0x([0-9a-fA-F]{2})*$). config allows additional properties beyond the enumerated keys (additionalProperties: true), but the alloc value object does not.

Why standardize now

The number of EIPs that modify or extend genesis configuration is growing. The source cites EIP-7840, which adds the blob schedule to the execution client configuration; EIP-7892, which defines hard forks that only change blob parameters; and EIP-7910, the eth_config JSON-RPC method for querying node configuration, as examples. The argument of this EIP is that since the root configuration elements these modify have never been specified, defining a minimal schema first allows subsequent changes to be described more precisely and concisely.

Security implications and current status

This EIP is of type Informational, an optional document that provides development convenience. The source states that since the genesis file is used only under node administrator privileges, there are no new security concerns. It is not a protocol change requiring a network hard fork, but a documentation standard for clients and tools to follow. The current status is Draft, so the field composition and schema details may still change.

Original EIP · ← EIPs