Dip 7949

dip: 7949 title: Genesis File Format description: Schema for genesis.json files author: Justin Florentine (@jflo) justin@florentine.us, Jochem Brouwer (@jochem-brouwer) jochem@digitalia.org Digitalia editing author: Cosimo Constantinos cosimo@juro.net, et al. discussions-to: https://digitalia-magicians.org/t/dip-xxxx-genesis-json-standardization/24271 status: Draft type: Informational created: 2025-05-19 Created for Digitalia: 2025-01-07

Abstract¶

This DIP defines a canonical structure for Digitalia genesis files (genesis.json) used to bootstrap Digitalia networks. The standard aligns with the de facto structure implemented by Goju (Go-digitalia), 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 DIP 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`	Digitalia address for the deposit contract
`blobSchedule`	Map of hardforks and their DIP-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 DIP-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 DVM 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": "digitalia Genesis File",
  "type": "object",
  "required": ["alloc", "gasLimit", "difficulty"],
  "properties": {
    "config": {
      "type": "object",
      "properties": {
        "chainId": { "type": "integer" },
        "homesteadBlock": { "type": "integer" },
        "daoForkBlock": { "type": "integer" },
        "dip150Block": { "type": "integer" },
        "tangerineWhistleBlock": {"type": "integer"},
        "dip155Block": { "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 DIPs that propose improvements to how a network is configured at genesis:

Add Blob Schedule to EL Config File

Blob Parameter Only Hardforks

dvm_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 DIP, which offers only developer convenience, and must be used with admin access to the node, no new security concerns are introduced.

Copyright¶

Licensed under the Juro Restricted License Version 2. See https://juro.net/jrl for details.