How to create a new genesis block

Table of Contents

Why create a new genesis block?
Using the CLI to generate a new genesis block

How to generate a genesis block for a blockchain client.

Prerequisites

To use this guide, ensure the following criteria below have been fulfilled:

A basic blockchain client is already initiated, as explained in the guide Creating a new blockchain client.

Each client needs a genesis block, which is the very first block of the blockchain.

During the init process of a blockchain client, the Klayr SDK bootstraps the first genesis block, and the relevant assets required for each blockchain in the config/default directory of each client.

Default genesis block and configuration files

├── bin/
├── config/
│    └── default/
│         ├── config.json (1)
│         ├── dev-validators.json (2)
│         ├── genesis_assets.json (3)
│         ├── genesis_block.blob (4)
│         └── passphrase.json (5)
├── src/
└── test/

1	The default configuration of the blockchain client exists in the `config.json` file.
2	`dev-validators.json`: Contains the plain & encrypted keys, addresses, and other properties of 102 validators.
3	`genesis_assets.json`: Contains details about the initial state of a blockchain such as account details for `token` and `pos` modules. It also contains the list of validators, etc.
4	`genesis_block.blob`: A blob file of the genesis block.
5	`passphrase.json`: Contains the passphrase used in various blockchain client operations.

Why create a new genesis block?

For every new blockchain, a unique genesis block is required. As mentioned earlier, a default genesis block becomes available right after the client’s init process. However, while running a public network, the developers have to create a new genesis block to change the initial state. The initial genesis block is expected to be used only for development purposes.

To achieve this you can regenerate a genesis block for various use cases, such as assigning different tokens to specific addresses of your choice. Furthermore, it is also possible to recreate the genesis block based on the module’s requirements, for example, setting up the initial constraints required for a staking module, etc.

If a module wants to process a genesis block asset, the module needs to implement the initGenesisState or finalizeGenesisState hook available in each Module Class.

Using the CLI to generate a new genesis block

The genesis block can be re-generated with the client CLI. By executing the following command in the root directory of the blockchain client, you can create a new genesis block.

./bin/run genesis-block:create --output config/default --assets-file ./config/default/genesis_assets.json

The --output flag accepts the directory where you wish to create the genesis_block.blob file.

The --assets-file flag accepts the path where the genesis_assets.json file exists. The asset’s file can be tweaked as per the requirements and then based on the updated asset’s file, a genesis block can be generated.

As a result of the genesis-block:create command, the new genesis block files will be created in the directory mentioned with the --output flag.

2022-12-02T12:59:33.104Z INFO XYZ application 30245 Registered and initialized auth module
2022-12-02T12:59:33.105Z INFO XYZ application 30245 Registered auth module has command registerMultisignature
2022-12-02T12:59:33.106Z INFO XYZ application 30245 Registered and initialized validators module
2022-12-02T12:59:33.107Z INFO XYZ application 30245 Registered and initialized token module
2022-12-02T12:59:33.107Z INFO XYZ application 30245 Registered token module has command transfer
2022-12-02T12:59:33.107Z INFO XYZ application 30245 Registered token module has command crossChaintransfer
2022-12-02T12:59:33.108Z INFO XYZ application 30245 Registered and initialized fee module
2022-12-02T12:59:33.110Z INFO XYZ application 30245 Registered and initialized reward module
2022-12-02T12:59:33.111Z INFO XYZ application 30245 Registered and initialized random module
2022-12-02T12:59:33.114Z INFO XYZ application 30245 Registered and initialized pos module
2022-12-02T12:59:33.114Z INFO XYZ application 30245 Registered pos module has command registerValidator
2022-12-02T12:59:33.114Z INFO XYZ application 30245 Registered pos module has command reportMisbehavior
2022-12-02T12:59:33.114Z INFO XYZ application 30245 Registered pos module has command unlock
2022-12-02T12:59:33.114Z INFO XYZ application 30245 Registered pos module has command updateGeneratorKey
2022-12-02T12:59:33.114Z INFO XYZ application 30245 Registered pos module has command stake
2022-12-02T12:59:33.114Z INFO XYZ application 30245 Registered and initialized interoperability module
2022-12-02T12:59:33.114Z INFO XYZ application 30245 Registered interoperability module has command mainchainRegistration
Genesis block files saved at: /Users/XYZ/klayr/hello_client/config/default

For more information about the genesis-block:create command, check the CLI command reference.

After the genesis block creation is complete, the passphrase.json and genesis_block.blob re-generate under the config/default/ directory.