Skip to main content

Genesis Configuration

Genesis File​

The 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 by configuring key aspects of the network, including its initial validators, the DB administrator, initial height, and other consensus parameters.

All the nodes in the network must 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.

Example​

Below is an example genesis.json file featuring a basic configuration:

example genesis.json file
{
  "chain_id": "kwil-testnet",
  "initial_height": 0,
  "app_hash": null,
  "db_owner": "0xE0f13c95225F34f86E99f83984e286dcaF321E37",
  "alloc": [
    {
      "id": "0xDC18F4993e93b50486e3e54e27d91D57cEE1dA07",
      "key_type": "secp256k1",
      "amount": 1234567890000000000000
    }
  ],
  "validators": [
    {
      "pubkey": "0226b3ff29216dac187cea393f8af685ad419ac9644e55dce83d145c8b1af213bd",
      "type": "secp256k1",
      "power": 1
    },
    {
      "pubkey": "02c57268fc884fa88425c7e5c19d3af263d1c64dd8b8f3f8c0fb31bb622d1fdab8",
      "type": "secp256k1",
      "power": 1
    }
  ],
  "leader": {
    "type": "secp256k1",
    "key": "0226b3ff29216dac187cea393f8af685ad419ac9644e55dce83d145c8b1af213bd"
  },
  "max_block_size": 6291456,
  "join_expiry": "24h0m0s",
  "disabled_gas_costs": true,
  "max_votes_per_tx": 200
}

Parameters​

Chain ID​

chain_id: Uniquely identifies the blockchain network and should not exceed 50 characters.

Initial Height​

initial_height: The initial height the blockchain should begin at. It should be set to 0 for a new chain that is not migrated from a previous chain. This should be considered the genesis height. Thus, first block produced will be one greater than this value.

DB Owner​

db_owner: The owner owner (administrator) of the Kwil database schemas. This is given in the string format used by the Kwil engine's @caller variable, which is derived from the user's public key. Typically this will be the corresponding Ethereum address.

Initial Funding Allocations​

alloc: A list of Kwil accounts and their initial balances at the genesis. This field is optional and is used to pre-fund Kwil accounts with balance. The id field is the Kwil account ID string, which may be an ethereum address in the case of user funding or a public key in the case of validator funding. The key_type field specifies the type of the account's public key, which is "secp256k1" for Ethereum users. The amount field specifies the initial balance of the account.

Validators​

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

  • pubkey: The validator's public key bytes (hexadecimal).
  • type: The type of the validator's public key (e.g. secp256k1).
  • power: The validator's voting power. Power 0 indicates that the node is a non-validator.

Leader​

leader: The initial leader of the blockchain. The leader is a special validator that is responsible for proposing new blocks.

App Hash​

app_hash: The hash generated from the initial application state, which is only used in the case of a migration where the genesis_state setting in the config.toml specifies the path to the snapshot file of the previous chain.

Block Rules:​

max_block_size: The maximum block size, in bytes.

Validator Join Request Expiry:​

join_expiry: The duration after which the validator join request expires if not approved. The default expiry is 24hrs blocks, which is equivalent to 1 day if blocks are produced at the rate of 1 block/sec.

Disabled Gas Costs​

disable_gas_costs: Whether gas costs should be enabled for the transactions. With gas costs disabled, no fees are incurred for transactions.

Max Votes Per Tx​

max_votes_per_tx: The maximum number of validator resolution votes that can be included in a single transaction.

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.