Skip to main content

Fields in genesis

C4E Team8/1/25About 3 min

Fields in genesis

A genesis.json file is the foundational block of a blockchain, defining its initial state. This includes everything from the network's unique identifier and initial accounts to the rules that govern consensus and module parameters.

Below is an overview of the key fields within a typical Cosmos SDK-based genesis.json file.

Top-Level Fields

These fields define the blockchain's core identity and starting point.

{
    "genesis_time": "2025-08-04T07:44:52.123456789Z",
    "chain_id": "your-chain-id",
    "initial_height": "1",
    "app_hash": "0x1234567890abcdef",
    "consensus_params": { ... },
    "app_state": { ... },
}
  • genesis_time: The timestamp marking the start of the blockchain.
  • chain_id: A unique identifier for the blockchain.
  • initial_height: The height of the first block in the blockchain, typically set to 1.
  • app_hash: A hash representing the initial state of the application.

Consensus Parameters (consensus_params)

These parameters define the rules enforced by the underlying consensus engine (e.g., Tendermint).

  • block
    • max_bytes: Maximum size of a block in bytes.
    • max_gas: The gas limit per block, default is -1 (no limit).
    • time_iota_ms: Minimum time increment between blocks in milliseconds.
  • evidence
    • max_age_num_blocks: Deprecated; use max_age_duration instead.
    • max_age_duration: Maximum age of evidence before it is rejected.
    • max_num: Maximum number of evidence items that can be stored.
  • validator
    • pub_key_types: Supported public key types for validators (e.g., ["ed25519"]).

Application State (app_state)

The app_state object contains the initial state for each of the application's modules.

genutil

Handles genesis transaction creation and validation.

  • gentxs: An array of signed genesis transactions that create the initial validator set.

auth

Manages accounts and transaction signatures.

  • params:
    • max_memo_characters: Maximum number of characters allowed in a transaction memo.
    • tx_sig_limit: Maximum number of signatures allowed in a transaction.
    • tx_size_cost_per_byte: Gas cost per byte of a transaction.
    • sig_verify_cost_ed25519: Gas cost for verifying Ed25519 signatures.
    • sig_verify_cost_secp256k1: Gas cost for verifying Secp256k1 signatures.
  • accounts: An array of initial accounts, each with:
    • @type: The type of account (e.g., "/cosmos.auth.v1beta1.BaseAccount" or "cosmos.vesting.v1beta1.ContinuousVestingAccount").
    • address: The account's address.
    • pub_key: The public key associated with the account.
    • account_number: A unique number for the account in the state.
    • sequence: The account's initial sequence number (usually "0"), used to prevent replay attacks.
    • base_vesting_account: For vesting accounts, this object contains vesting-specific details.
      • original_vesting: An array of coins that are subject to a vesting schedlue.
      • delegated_free: Delegate tokens that have completed their vesting preriod and can be transferred.
      • delegated_vesting: Delegate tokens that are still under vesting.
      • end_time: The UNIX timestamp when the vesting period concludes.

bank

Manages token transfers and supplies.

  • params:
    • send_enabled: An array specifying which denominations have sending enabled.
    • default_send_enabled: A boolean that controls the default transfer capability for all tokens.
  • balances: An array of all account balances at genesis.
  • supply: An array showing the total supply of each token denomination.

distribution

Manages the distribution of block rewards and transaction fees.

  • params:
    • community_tax: The percentage of rewards and fees allocated to the community poo.
    • base_proposer_reward: A base reward bonus for the block proposer.
    • bonus_proposer_reward: An additional bonus for proposers who include precommits from other validators.
    • withdraw_addr_enabled: A boolean that determines if delegators can set a separate withdrawal address for their rewards.
  • fee_pool:
    • community_pool: Contains any funds allocated to the community pool at genesis.
  • Other fields like delegator_starting_infos, outstanding_rewards, etc., are typically empty at genesis but are used to track rewards and commissions over time.

staking

Manages the Proof-of-Stake logic, including validators and delegations.

  • params:
    • unbonding_time: The duration a delegator must wait for their tokens to unbound (e.g., "1814400s" for 21 days).
    • max_validators: The maximum number of active validators in the set.
    • max_entries: The maximum number of unbonding or redelegation entries.
    • historical_entries: The number of historical staking entries to keep.
    • bond_denom: The token denomination required for staking.
  • delegations, unbonding_delegations, redelegations: Typically empty at genesis unless migrating state.
  • last_total_power: The total voting power at genesis, usually initialized to "0".
  • validators: An array of initial validators, populated from gentxs.

slashing

Handles punishments for validator misbehavior (downtime or double-signing).

  • params:
    • signed_blocks_window: The window of blocks used to track validator liveness.
    • min_signed_per_window: The minimum percentage of blocks a validator must sign in the window to avoid jailing.
    • downtime_jail_duration: The duration a validator is jailed for being offline.
    • slash_fraction_double_sign: The percentage of a validator's stake that is slashed for double-signing.
    • slash_fraction_downtime: The percentage of a validator's stake that is slashed for downtime.
  • signing_infos: Information about a validator signing history, populated from the initial validator set.

mint

Manages the creation of new tokens (inflation).

  • minter:
    • inflation: The initial yearly inflation rate.
    • annual_provisions: The expected tokens to be minted annually (circulated from inflation).
  • params:
    • mint_denom: The denomination of the token to be minted.
    • inflation_rate_change: The maximum annual change allowed for the inflation rate.
    • inflation_max: The maximum permissible inflation rate.
    • inflation_min: The minimum permissible inflation rate.
    • goal_bonded: The target ratio of bonded tokens to total supply.
    • blocks_per_year: The expected number of blocks per year, used to calculate inflation.

gov

Manages the on-chain governance process.

  • starting_proposal_id: The ID for the first governance proposal, usually "1".
  • deposit_params:
    • min_deposit: The minimum number of tokens required to submit a proposal.
    • max_deposit_period: The maximum time allowed for a proposal to reach the minimum deposit.
  • voting_params:
    • voting_period: The duration that a proposal is open for voting.
  • tally_params:
    • quorum: The minimum percentage of staked tokens that must vote for a proposal to be valid.
    • threshold: The minimum percentage of "Yes" votes (excluding "Abstain") required for a proposal to pass.
    • veto_threshold: The percentage of "NoWithVeto" votes that will cause a proposal to fail, regardless of other votes.

ibc

Manages the Inter-Blockchain Communication protocol. Its state is typically initialized as empty at genesis.

Copyright © 2025 C4E Team