How to create a new genesis block

How to generate a genesis block for a blockchain application.

Prerequisites

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

The recommended and most convenient method to generate a new genesis block is Using the CLI to generate a new genesis block.

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

If a module includes an account schema, it is necessary to update the genesis block after registering the module with the application, to update the accounts in the genesis block with the new properties.

If a new module that includes an account schema is then registered with the application, it will fail and an error similar to this example shown below will be displayed:

$ ./bin/run start
Starting Lisk hello_app at /Users/mona/.lisk/hello_app.
12:31:44 INFO lisk-framework: Starting the app - hello_app (module=lisk:app)
12:31:44 INFO lisk-framework: If you experience any type of error, please open an issue on Lisk GitHub: https://github.com/LiskHQ/lisk-sdk/issues (module=lisk:app)
12:31:44 INFO lisk-framework: Contribution guidelines can be found at Lisk-sdk: https://github.com/LiskHQ/lisk-sdk/blob/development/docs/CONTRIBUTING.md (module=lisk:app)
12:31:44 INFO lisk-framework: Booting the application with Lisk Framework(0.1.0) (module=lisk:app)
12:31:44 INFO lisk-framework: Initializing controller (module=lisk:app)
12:31:44 INFO lisk-framework: Loading controller (module=lisk:app)
12:31:44 INFO lisk-framework: Event * was subscribed but not registered to the bus yet. (module=lisk:app)
    TypeError: Cannot read property 'helloMessage' of undefined
12:31:45 INFO lisk-framework: Application shutdown started (module=lisk:app)
{
 "errorCode": 2,
 "message": "process.exit"
}

To fix this error, it is required to update the genesis block of the application to include the newly created account schema.

Using the CLI to generate a new genesis block

The genesis block can be updated with the application CLI:

./bin/run genesis-block:create --output config/default
For more information about the genesis-block:create command, check the CLI command reference.

Once the above command is executed, wait until the new genesis block is generated.

Creating genesis block [===========         ] 55% 44.6s

When asked to overwrite the existing genesis block, reply with yes.

? A genesis_block file already exists at the given location. Do you want to overwrite it? Yes

After the genesis block creation is complete, the following 4 files should be generated under config/default/:

  • genesis-block.json: The new genesis block.

  • forging_info.json: The prepared information about the genesis delegates for the config.

  • password.json: The default password to decrypt the passphrases of the genesis delegates.

  • accounts.json: The passphrases of each genesis delegate as plain text. Store this file somewhere secure and safe.

The config.json is required to be updated as well, with the forging information of the new genesis delegates:

Assuming no custom config is used, the following commands can be used to update the configuration (please update <YOUR_APP> to the corresponding application name).

tmp=$(mktemp)
jq '.forging.delegates = input' config/default/config.json config/default/forging_info.json > "$tmp" && mv "$tmp" config/default/config.json
jq '.forging += input' config/default/config.json config/default/password.json > "$tmp" && mv "$tmp" config/default/config.json

Remove the old application data:

rm -r ~/.lisk/<YOUR_APP>

Now start the node again:

./bin/run start
Ensure the file accounts.json is securely stored somewhere safe, as it contains the passphrases of all the genesis delegates.
Example config with forging enabled for the genesis delegates
{
  // ...
  "forging": {
    "force": true,
    "waitThreshold": 2,
    "delegates": [
        {
            "encryptedPassphrase": "iterations=1000000&cipherText=e340e06389f55bacb4043a60b9135aa905c3fd543fcab7e9f309577abf5631bec801626c67e87b47b6e9b674a65a1d15ec5176ace21fb5c0f0f1c1f1950b38abe5b06c8fc54fd511c0109f83dc&iv=37abcda2bf1a254563f49e36&salt=1a3b09594d04096d250e74850d3c7508&tag=a836539af32622c10536dacecd12320d&version=1",
            "hashOnion": {
                "count": 100000,
                "distance": 1000,
                "hashes": [
                    "34ecc432170c0812e7ca69d73485ca57",
                    "1bf9423f594619f7d14e6f742c0631a1",
                    "4732e2bc540f8ab1e51e8a5d7b5b8f7e",
                    // ...
                    "fa51b75c7920894019b43378af621e2d",
                    "bd4ea06be86fb6d850023be7ad1d9558",
                    "da23c5a34d19bbd57ebb159da170dfb5"
                ]
            },
            "address": "8baec1286a12488825f3b6a8c84a7a72bf6591d9"
        },
        // ....
        {
            "encryptedPassphrase": "iterations=1000000&cipherText=5c53db41ec94b46049ca5a5b8312e6b38c7bbad775153a8091bafade3f78ac855b55d5d33318e13f22ec961510061c8a07726aeb4d2d2b30fbcc6ddfabc82dd6f233891a06ae54b2&iv=8c0419422b6e81c32c10ac6a&salt=1f2308d0d12480d0c788a4c60a8f272d&tag=23cf9840cb985550a96b463f878de99d&version=1",
            "hashOnion": {
                "count": 100000,
                "distance": 1000,
                "hashes": [
                    "34ecc432170c0812e7ca69d73485ca57",
                    "1bf9423f594619f7d14e6f742c0631a1",
                    "4732e2bc540f8ab1e51e8a5d7b5b8f7e",
                    // ...
                    "bd4ea06be86fb6d850023be7ad1d9558",
                    "da23c5a34d19bbd57ebb159da170dfb5"
                ]
            },
            "address": "68d6b039567ebbfc714176d87cdd6906cf526cc7"
        }
    ],
    "defaultPassword": "state dawn marriage honey cinnamon sadness crumble someone file caution sell oxygen"
    },
	// ...
}

Manual genesis block creation (alternative with Lisk Genesis)

The genesis library can be used to generate a valid genesis block based on the above parameters. It can be imported directly from the lisk-sdk package, or alternatively it can be installed as a separate package @liskhq/lisk-genesis.

npm install lisk-sdk
# or
npm install @liskhq/lisk-genesis

Including the account asset schemas

It is necessary for the genesis block to include the account schemas of all modules that are registered with the application. This also includes all account schemas of the SDK default modules which are registered with the application by default.

To achieve this, first import all relevant modules to get their account schemas:

const { TokenModule, DPoSModule, KeysModule, SequenceModule, genesis, passphrase, cryptography, configDevnet } = require('lisk-sdk');
const { MyModule } = require('./my-module');

// Create the accountAssetSchemas
const token = new TokenModule(configDevnet.genesisConfig).accountSchema;
const dpos = new DPoSModule(configDevnet.genesisConfig).accountSchema;
const keys = new KeysModule(configDevnet.genesisConfig).accountSchema;
const sequence = new SequenceModule(configDevnet.genesisConfig).accountSchema;
const myModule = new MyModule().accountSchema;

// Add fieldNumber starting from 2. Field number 1 is assigned to address of the account
token.fieldNumber = 2;
dpos.fieldNumber = 3;
keys.fieldNumber = 4;
sequence.fieldNumber = 5;
myModule.fieldNumber = 6;

const accountAssetSchemas = {
  token,
  dpos,
  keys,
  sequence,
  myModule
};
The key of each account schema should equal the name property of the respective module.

The default modules are always required to be included in the application for it to function correctly.

If they are not included in the application, other modules need to be included which replace their functionalities.

Generating a list of genesis delegates

The genesis block includes a list of genesis delegates under the initDelegates key.

These delegates will forge during the bootstrap period of the blockchain, which lasts for 3 forging rounds (3 * 103 blocks = 309 blocks) by default.

The default length of the bootstrap period can be altered with the initRounds property.

Generating a fresh list of genesis delegates

If you don’t have a list of already existing account details, it is necessary to newly generate the accounts.

The three minimum properties for a delegate are listed below:

  • address(Buffer): Address of the delegate account.

  • token.balance(BigInt): Balance of the delegate.

  • dpos.delegate.username(string): Unique username of the delegate.

// Generating the genesis delegates

const newCredentials = () => {
    const pass = passphrase.Mnemonic.generateMnemonic();
    const keys = cryptography.getPrivateAndPublicKeyFromPassphrase(pass);
    const credentials = {
        address: cryptography.getBase32AddressFromPassphrase(pass),
        binaryAddress: cryptography.getAddressFromPassphrase(pass).toString("hex"),
        passphrase: pass,
        publicKey: keys.publicKey.toString("hex"),
        privateKey: keys.privateKey.toString("hex")
    };
    return credentials;
};

const credentials = [];


const newDelegate = (name) => {
  const cred = newCredentials();
  credentials.push(cred);
    const delegate = {
        address: Buffer.from(cred.binaryAddress, 'hex'),
        token: { balance: BigInt(100000000) },
        dpos: { delegate: { username: name } }
    };
    return delegate;
};

const generateDelegates = (amount) => {
  const delegates = [];
  const name = 'genesisDelegate';
  for (let i = 1; i <= amount; i++) {
    let nameNumber = name + i;
    delegates.push(newDelegate(nameNumber))
  }
  return delegates;
};

const delegates = generateDelegates(5);

Generating the list of genesis accounts

All accounts that already exist at the beginning of the network are listed under the property accounts of the genesis block.

The accounts property is a list of accounts that always needs to include the accounts for the genesis delegates, that were created in the previous step.

Besides this, any other accounts can be added here, and account properties such as balance can be configured as desired.

// Creating the genesis account list

const newAccount = () => {
  const cred = newCredentials();
  credentials.push(cred);
  const account = {
    address: Buffer.from(cred.binaryAddress, 'hex'),
    token: { balance: BigInt(25000000000) }
  };
  return account;
};

const generateAccounts = (amount) => {
  const accounts = [];
  for (let i = 1; i <= amount; i++) {
    accounts.push(newAccount())
  }
  return accounts;
};

const genesisAccounts = generateAccounts(3);

const accounts = [...delegates, ...genesisAccounts];

Creating the genesis block

As the final step, use the function createGenesisBlock() of the genesis library to generate the genesis block.

The parameters for the genesis block are all packed into one object.

  • initDelegates(Array): List of initial delegate addresses used during the bootstrap period to forge blocks. Addresses are expected to be in Buffer format.

  • accounts(Array): List of initial accounts in the network. The minimum required is address, however other properties such as balance can be included. Addresses are expected to be in Buffer format.

  • accountAssetSchemas(Object): The genesis block needs to contain all account asset schemas for all modules which are registered with the respective blockchain application. The different account asset schemas are all grouped together in one large object and added as accountAssetSchemas to the genesis block params. accountAssetSchemas is one of the most important parameters for generating a valid genesis block, so make sure it includes all required account asset schemas.

This object is provided as a parameter for the createGenesisBlock() function, which will then be used to generate the dedicated genesis block.

const genesisBlockParams = {
	initDelegates: delegates.map(a => a.address),
	accounts,
	accountAssetSchemas,
};

const genesisBlock = genesis.createGenesisBlock(genesisBlockParams);

console.log(genesisBlock);

Complete example

Full example: How to generate a genesis block
const { TokenModule, DPoSModule, KeysModule, SequenceModule, genesis, passphrase, cryptography, configDevnet } = require('lisk-sdk');
const { MyModule } = require('./my-module');

// Create the accountAssetSchemas
const token = new TokenModule(configDevnet.genesisConfig).accountSchema;
const dpos = new DPoSModule(configDevnet.genesisConfig).accountSchema;
const keys = new KeysModule(configDevnet.genesisConfig).accountSchema;
const sequence = new SequenceModule(configDevnet.genesisConfig).accountSchema;
const myModule = new MyModule().accountSchema;

// Add fieldNumber starting from 2. Field number 1 is assigned to address of the account
token.fieldNumber = 2;
dpos.fieldNumber = 3;
keys.fieldNumber = 4;
sequence.fieldNumber = 5;
myModule.fieldNumber = 6;

const accountAssetSchemas = {
  token,
  dpos,
  keys,
  sequence,
  myModule
};

// Generating the genesis delegates

const newCredentials = () => {
  const pass = passphrase.Mnemonic.generateMnemonic();
  const keys = cryptography.getPrivateAndPublicKeyFromPassphrase(pass);
  const credentials = {
    address: cryptography.getBase32AddressFromPassphrase(pass),
    binaryAddress: cryptography.getAddressFromPassphrase(pass).toString("hex"),
    passphrase: pass,
    publicKey: keys.publicKey.toString("hex"),
    privateKey: keys.privateKey.toString("hex")
  };
  return credentials;
};

const credentials = [];


const newDelegate = (name) => {
  const cred = newCredentials();
  credentials.push(cred);
  const delegate = {
    address: Buffer.from(cred.binaryAddress, 'hex'),
    token: { balance: BigInt(100000000) },
    dpos: { delegate: { username: name } }
  };
  return delegate;
};

const generateDelegates = (amount) => {
  const delegates = [];
  const name = 'genesisDelegate';
  for (let i = 1; i <= amount; i++) {
    let nameNumber = name + i;
    delegates.push(newDelegate(nameNumber))
  }
  return delegates;
};

const delegates = generateDelegates(5);

// Creating the genesis account list

const newAccount = () => {
  const cred = newCredentials();
  credentials.push(cred);
  const account = {
    address: Buffer.from(cred.binaryAddress, 'hex'),
    token: { balance: BigInt(25000000000) }
  };
  return account;
};

const generateAccounts = (amount) => {
  const accounts = [];
  for (let i = 1; i <= amount; i++) {
    accounts.push(newAccount())
  }
  return accounts;
};

const genesisAccounts = generateAccounts(3);

const accounts = [...delegates, ...genesisAccounts];

// Creating the genesis block

const genesisBlockParams = {
  initDelegates: delegates.map(a => a.address),
  accounts,
  accountAssetSchemas,
};

const genesisBlock = genesis.createGenesisBlock(genesisBlockParams);

console.log(genesisBlock);

The generated genesis block

The above script will create the following output:

Genesis block
{
  header: {
    generatorPublicKey: <Buffer >,
    height: 0,
    previousBlockID: <Buffer >,
    reward: 0n,
    signature: <Buffer >,
    timestamp: 1620398241,
    transactionRoot: <Buffer e3 b0 c4 42 98 fc 1c 14 9a fb f4 c8 99 6f b9 24 27 ae 41 e4 64 9b 93 4c a4 95 99 1b 78 52 b8 55>,
    version: 0,
    asset: { initRounds: 3, initDelegates: [Array], accounts: [Array] },
    id: <Buffer a8 eb 2c da 7b 2a 8f 0e 84 24 1e 78 af 78 4e c9 0b ce d0 39 d0 b4 98 87 95 a8 5d 63 83 be c5 a0>
  },
  payload: []
}

Optional parameters for the genesis block

Besides the three required properties initDelegates, accounts, and accountAssetSchemas, it is possible to set the following optional properties for the genesis block:

  • initRounds(number): Number of rounds for bootstrap period, default is 3.

  • height(number): Height of the genesis block.

  • timestamp(number): Timestamp of the genesis block.

  • previousBlockID(Buffer): Previous block ID. Can be used for example in case of regenesis.

Example: Generating a genesis block with all optional properties included
const genesisBlockParams = {
	initDelegates: delegates.map(a => a.address),
	accounts,
	accountAssetSchemas,
	initRounds: 200,
	height: 123,
	timestamp: 1520668243,
	previousBlockID: Buffer.from(
		'454690a1c37838326007519a7ce1c8a6a495df50898f1ebd69d22fbcedf9689a',
		'hex',
	)
};

const genesisBlock = genesis.createGenesisBlock(genesisBlockParams);

console.log(genesisBlock);