Skip to main content

Genesis Configuration

A genesis file defines the initial state and parameters needed to bootstrap a new blockchain network. It serves as the starting point for the entire blockchain system by defining key aspects of the network, including its initial validators, initial height, consensus rules, and more. All the nodes in the network need to have the same genesis file to start with the same initial conditions. Any discrepancies or errors in the genesis file could prohibit the node from joining the network or producing blocks.

Minimal Configuration​

Below is a sample genesis.json file featuring a basic configuration:

sample genesis.json file
{
  "genesis_time": "2024-09-10T22:20:11.75149Z",
  "chain_id": "kwil-chain-YLyVNOKZ",
  "initial_height": 1,
  "consensus_params": {
    "block": {
      "max_bytes": 6291456,
      "max_gas": -1,
      "abci_max_bytes": false
    },
    "evidence": {
      "max_age_num_blocks": 100000,
      "max_age_duration": 172800000000000,
      "max_bytes": 1048576
    },
    "validator": {
      "pub_key_types": [
        "ed25519"
      ],
      "join_expiry": 14400
    },
    "votes": {
      "vote_expiry": 14400,
      "max_votes_per_tx": 100
    }
  },
  "validators": [
    {
      "pub_key": "45a41991ce11839115e5a47d70c6589de28eea8780295a251ea16b62ec1accdd",
      "power": 1,
      "name": "validator-0"
    }
  ]
}

Genesis File Contents​

Genesis Time​

genesis_time: This field specifies the official time (ISO 8601 format) at which the blockchain is initialized.

Chain ID​

chain_id: This field uniquely identifies the blockchain network and should not exceed 50 characters.

Initial Height​

initial_height: This field sets the initial height the blockchain should begin at. By default, it should be set to 1.

Genesis Validators​

validators: This field sets the list of the initial set of validators. Each validator has a cryptographic key-pair and an associated voting power.

  • pub_key: This field specifies the validator's public key bytes (hex).
  • power: The validator's voting power. Power 0 indicates that the node is a non-validator.
  • name: The validator's name.

Genesis App Hash​

app_hash: The app hash is a hash generated from the initial application state.

Genesis Allocs​

alloc: This field specifies the Kwil accounts and their initial balances at the genesis. The alloc field is optional and is used to pre-fund Kwil accounts with balance. This is a JSON dictionary object where the keys are account identifiers of type hexadecimal bytes and the values are the account balances. By default, Kwil supports both 0x prefixed ethereum addresses and ed25519 public keys as account identifiers.

Advanced Configurations​

Consensus Params​

The genesis file can also be used to establish a predefined set of consensus rules such as:

Block Rules:​

  • block:
    • max_bytes: This field specifies the maximum block size, in bytes.
    • max_height: This field specifies the maximum gas per block.

Validator Type:​

  • validator:

    • pub_key_types: This field sets the public key types validators can use. Currently, only the ed25519 key type is supported.

    • join_expiry: This field sets the number of blocks after which the validator join request expires if not approved. The default expiry is 86400 blocks, which is equivalent to 1 day if blocks are produced at the rate of 1 block/sec.

ABCI App Version:​

  • version:
    • app_version: This field sets the ABCI application version.

Migrations:​

  • migration:
    • start_height: The start height of the migration on the old network. Specifies the height from which the state changes are to be replicated onto the new network.
    • end_height: The end height of the migration on the old network. Specifies the height until which the state changes are to be replicated onto the new network.

General​

  • without_gas_costs: This field sets whether gas costs should be enabled for the transactions. By default, gas costs are disabled, resulting in no fees incurred for each transaction.

Complete Genesis Configuration​

Below is an example of a genesis file with complete configuration:

sample genesis.json file
{
  "genesis_time": "2024-09-10T22:37:12.960766Z",
  "chain_id": "kwil-chain-wcHt2Qul",
  "initial_height": 1,
  "app_hash": null,
  "activations": null,
  "consensus_params": {
    "block": {
      "max_bytes": 6291456,
      "max_gas": -1,
      "abci_max_bytes": false
    },
    "evidence": {
      "max_age_num_blocks": 100000,
      "max_age_duration": 172800000000000,
      "max_bytes": 1048576
    },
    "version": {
      "app": 0
    },
    "validator": {
      "pub_key_types": [
        "ed25519"
      ],
      "join_expiry": 14400
    },
    "votes": {
      "vote_expiry": 14400,
      "max_votes_per_tx": 100
    },
    "abci": {
      "vote_extensions_enable_height": 0
    },
    "migration": {
      "start_height": 0,
      "end_height": 0
    },
    "without_gas_costs": true
  },
  "validators": [
    {
      "pub_key": "6ec435ec737629ffade7d0f4679f4e89f285529487a72beb1945326c3b59be4a",
      "power": 1,
      "name": "validator-0"
    }
  ]
}