# genesis file

The genesis file is the file that allows you to create a new blockchain from block 0. It lays out the different parameter of your blockchain: the initial utxo, the start time, the slot duration time, etc...

Example of a BFT genesis file with an initial address UTxO and an account UTxO. More info regarding starting a BFT blockchain here and regarding addresses there. You could also find information regarding the jcli genesis tooling.

You can generate a documented pre-generated genesis file:

jcli genesis init


For example your genesis file may look like:

# The Blockchain Configuration defines the settings of the blockchain.
blockchain_configuration:

# The block0-date defines the date the blockchain starts
# expected value in seconds since UNIX_EPOCH
#
# By default the value will be the current date and time. Or you can
# add a specific time by entering the number of seconds since UNIX
# Epoch
block0_date: {default_block0_date}

# This is the type of discrimination of the blockchain
# of this blockchain is meant for production then
#
# otherwise leave as this
discrimination: {discrimination}

# The initial consensus version:
#
# * BFT consensus: bft
# * Genesis Praos consensus: genesis
block0_consensus: bft

# Number of slots in each epoch.
#
# default value is {default_slots_per_epoch}
slots_per_epoch: {default_slots_per_epoch}

# The slot duration, in seconds, is the time between the creation
# of 2 blocks
#
# default value is {default_slot_duration}
slot_duration: {default_slot_duration}

# set the block content max size
#
# This is the size, in bytes, of all the contents of the block (excluding the
#
# default value is {default_block_content_max_size}
block_content_max_size: {default_block_content_max_size}

# A list of Ed25519 PublicKey that represents the
# BFT leaders encoded as bech32. The order in the list matters.

# Epoch stability depth
#
# Optional: default value {default_epoch_stability_depth}
epoch_stability_depth: {default_epoch_stability_depth}

# Genesis praos active slot coefficient
# Determines minimum stake required to try becoming slot leader, must be in range (0,1]
#
# default value: {default_consensus_genesis_praos_active_slot_coeff}
consensus_genesis_praos_active_slot_coeff: {default_consensus_genesis_praos_active_slot_coeff}

# The fee calculations settings
#
# total fees: constant + (num_inputs + num_outputs) * coefficient [+ certificate]
linear_fees:
# this is the minimum value to pay for every transaction
constant: 2
# the additional fee to pay for every inputs and outputs
coefficient: 1
# the additional fee to pay if the transaction embeds a certificate
certificate: 4
# (optional) fees for different types of certificates, to override the one
# given in certificate just above
#
# here: all certificate fees are set to 4 except for pool registration
# and stake delegation which are respectively 5 and 2.
per_certificate_fees:
# (optional) if not specified, the pool registration certificate fee will be
# the one set by linear_fees.certificate
certificate_pool_registration: 5
# (optional) if not specified, the delegation certificate fee will be
# the one set by linear_fees.certificate
certificate_stake_delegation: 2
# (optional) if not specified, the owner delegation certificate fee will be
# the one set by linear_fees.certificate. Uncomment to set the owner stake
# delegation to 1 instead of default 4:
# certificate_owner_stake_delegation: 1

# The speed to update the KES Key in seconds
#
# default value: {default_kes_update_speed}
kes_update_speed: {default_kes_update_speed}

# Set where to send the fees generated by transactions activity.
#
# by default it is send to the "rewards" pot of the epoch which is then
# distributed to the different stake pools who created blocks that given
# epoch.
#
# It is possible to send all the generated fees to the "treasury".
#
# Optional, default is "rewards"
# fees_go_to: "rewards"

# initial value the treasury will start with, if not set the treasury
# starts at 0
treasury: 1000000000000

# set the treasury parameters, this is the tax type, just as in stake pool
# registration certificate parameters.
#
# When distributing the rewards, the treasury will be first serve as per
# the incentive specification document
#
# if not set, the treasury will not grow
treasury_parameters:
# the fix value the treasury will take from the total reward pot of the epoch
fixed: 1000
# the extra percentage the the treasury will take from the reward pot of the epoch
ratio: "1/10"
# It is possible to add a max bound to the total value the treasury takes
# at each reward distribution. For example, one could cap the treasury tax
# to 10000. Uncomment the following line to apply a max limit:
# max_limit: 10000

# Set the total reward supply available for monetary creation
#
# if not set there is no monetary creation
# once emptied, there is no more monetary creation
total_reward_supply: 100000000000000

# set the reward supply consumption. These parameters will define how the
# total_reward_supply is consumed for the stake pool reward
#
# There's fundamentally many potential choices for how rewards are contributed back, and here's two potential valid examples:
#
# Linear formula: constant - ratio * (#epoch after epoch_start / epoch_rate)
# Halving formula: constant * ratio ^ (#epoch after epoch_start / epoch_rate)
#
reward_parameters:
halving: # or use "linear" for the linear formula
# In the linear formula, it represents the starting point of the contribution
# at #epoch=0, whereas in halving formula is used as starting constant for
# the calculation.
constant: 100

# In the halving formula, an effective value between 0.0 to 1.0 indicates a
# reducing contribution, whereas above 1.0 it indicate an acceleration of contribution.
#
# However in linear formula the meaning is just a scaling factor for the epoch zone
# (current_epoch - start_epoch / epoch_rate). Further requirement is that this ratio
# is expressed in fractional form (e.g. 1/2), which allow calculation in integer form.
ratio: "13/19"

# indicates when this contribution start. note that if the epoch is not
# the same or after the epoch_start, the overall contribution is zero.
epoch_start: 1

# the rate at which the contribution is tweaked related to epoch.
epoch_rate: 3

# set some reward constraints and limits
#
# this value is optional, the default is no constraints at all. The settings
# are commented below:
#
#reward_constraints:
#  # limit the epoch total reward drawing limit to a portion of the total
#  # active stake of the system.
#  #
#  # for example, if set to 10%, the reward drawn will be bounded by the
#  # 10% of the total active stake.
#  #
#  # this value is optional, the default is no reward drawing limit
#  reward_drawing_limit_max: "10/100"
#
#  # settings to incentivize the numbers of stake pool to be registered
#  # on the blockchain.
#  #
#  # These settings does not prevent more stake pool to be added. For example
#  # if there is already 1000 stake pools, someone can still register a new
#  # stake pool and affect the rewards of everyone else too.
#  #
#  # if the threshold is reached, the pool doesn't really have incentive to
#  # create more blocks than 1 / set-value-of-pools % of stake.
#  #
#  # this value is optional, the default is no pool participation capping
#  pool_participation_capping:
#    min: 300
#    max: 1000

# list of the committee members, they will be used to guarantee the initial
# valid operation of the vote as well as privacy.
committees:
- "7ef044ba437057d6d944ace679b7f811335639a689064cd969dffc8b55a7cc19"

# Initial state of the ledger. Each item is applied in order of this list
initial:
# Initial deposits present in the blockchain
- fund:
value: 10000

# Initial certificates
#- cert: ..

# Initial deposits present in the blockchain
#- legacy_fund:
#      value: 123


There are multiple parts in the genesis file:

• blockchain_configuration: this is a list of configuration parameters of the blockchain, some of which can be changed later via the update protocol;
• initial: list of steps to create initial state of ledger

## blockchain_configuration options

optionformatdescription
block0_datenumberthe official start time of the blockchain, in seconds since UNIX EPOCH
discriminationstringproduction or test
block0_consensusstringbft
slot_durationnumberthe number of seconds between the creation of 2 blocks
epoch_stability_depthnumberallowed size of a fork (in number of block)
consensus_leader_idsarraythe list of the BFT leader at the beginning of the blockchain
block_content_max_sizenumberthe maximum size of the block content (excluding the block header), in bytes.
linear_feesobjectlinear fee settings, set the fee for transaction and certificate publishing
consensus_genesis_praos_active_slot_coeffnumbergenesis praos active slot coefficient. Determines minimum stake required to try becoming slot leader, must be in range (0,1]
kes_update_speednumberthe speed to update the KES Key in seconds
slots_per_epochnumbernumber of slots in each epoch

## initial options

Each entry can be one of 3 variants:

variantformatdescription
fundsequenceinitial deposits present in the blockchain (up to 255 outputs per entry)
certstringinitial certificate
legacy_fundsequencesame as fund, but with legacy Cardano address format

Example:

initial:
- fund:
value: 10000
value: 20000
value: 30000
- cert: <certificate>
- legacy_fund:
value: 123
- fund:
value: 1001


### fund and legacy_fund format

variantformatdescription
addressstringcan be a single address or an account address
valuenumberassigned value

legacy_fund differs only in address format, which is legacy Cardano