How to configure a blockchain application

How to configure a blockchain application.

The Application instance expects two arguments:

  1. A configuration file

  2. A genesis block

import { Application, PartialApplicationConfig } from 'lisk-sdk';
import { registerModules } from './modules';
import { registerPlugins } from './plugins';

export const getApplication = (
	genesisBlock: Record<string, unknown>,
	config: PartialApplicationConfig,
): Application => {
	const app = Application.defaultApplication(genesisBlock, config);


	return app;

Setting a custom configuration

To start the application with a custom config.json, add the --config flag to the start command with a custom path to the configuration file, e.g. --config my_custom_config.json.

bin/run start --config my_custom_config.json --overwrite-config

How to create a custom config

The optimal method to create a custom configuration for your app is to copy an existing config.json and adjust it to suit your requirements.

For example, copy the default config.json of the blockchain application:

In the root directory of the blockchain application
cp config/default/config.json my_custom_config.json

Example: Configuration of the Hello World application

Until now, it was not necessary to use any custom configurations for the Hello World application. However, if we want to interact with the application as described in the next guide Using dashboard with the blockchain application, it is necessary to change the RPC (Remote-Procedure-Call), configuration of the application, so that the dashboard plugin can connect to it.

By default, the RPC API is disabled, and the communication protocol is set to ipc. It is now necessary to enable the RPC API and change the communication protocol to ws.

Adjust the RPC configuration as follows:


  // ...

    "rpc": {
        "enable": true,
        "mode": "ws",
        "port": 8080

   // ...


Restart the app to apply the new configuration.

Config file location

The current configuration of a blockchain application is stored under the following path after the application is started for the first time:

~/.lisk/APP_NAME/config/default/config.json (1)
1 Replace APP_NAME with the name of the blockchain application.

List of all available config options

To get a complete overview of all configuration options for the Lisk SDK, please refer to the Application Configuration.

It is not necessary to include all options that are included in the schema. The application will use the default configuration options in the case whereby a config option is not specified.

Important configuration options


Adjust basic properties for the blockchain application in genesisConfig. For example, the time that elapses until a new block is forged, the network epoch time, and the block rewards.

To see a full list of all constants and their predefined values, please see the file application_config_schema.js.
Example: Starting the app with a custom genesisConfig
    // ...

    "genesisConfig": {
        "bftThreshold": 23,
        "communityIdentifier": "hello",
        "blockTime": 5,
        "maxPayloadLength": 19000,
            "milestones": [
            "offset": 100,
            "distance": 100000
        "minFeePerByte": 500,
        "baseFees": [
                "moduleID": 2,
                "assetID": 0,
                "baseFee": "1000000"
        "activeDelegates": 31,
        "standbyDelegates": 5

    // ...

Custom properties in the genesisConfig

Since all genesis config options will be passed to modules, it is possible to add custom config options to the genesisConfig.

These options can then be used in a specific custom module, see the "Genesis config" section of the Modules introduction for more information.

Adding a custom config option to the genesis config
    // ...

    "genesisConfig": {
        "myCustomOption": "Some data",
        // ...

    // ...



The rpc key holds all configuration options related to the API access of the blockchain application.

Allowing arbitrary machines to access the rpc port (ws) is dangerous and strongly discouraged — access should be strictly limited only to trusted machines.

For reference see the guide Protecting a non-forging node

Please see the RPC endpoints of a Lisk node and RPC endpoints of a Lisk node pages for more information about the API access options.

Configuring the API access to the node
    "rpc": {
        "enable": true, //true or false
        "mode": "ws", //"ws" or "ipc"
        "port": 8080, //websocket port
        "host": "" (1)
1 Change the host to if you wish to connect to the node from a remote server.