Configuring a blockchain application

How to configure a blockchain application.


To use this guide, it is assumed that the following criteria have been met:

  1. Lisk Commander is installed, and a basic blockchain application is already initialized, as explained in the guide Creating a new blockchain application.

  2. A new module HelloModule is created, as explained in the guide Creating a module.

  3. A new asset HelloAsset is created, as explained in the guide Creating a module asset.

  4. A new plugin LatestHelloPlugin is created, as explained in the previous guide Creating a plugin.

Config file location

The configuration of a blockchain application is stored under the following path:

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

After editing the config file, it is required to restart the blockchain application, so that the changes can take effect.

The configuration file located in APP_NAME/config/default/config.json is only used during the initial bootstrapping of the blockchain application. Making updates in this config file will have no further effect on the blockchain application, so please ensure you are updating the correct config.json file.

Alternatively, to start the application with a different 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.

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 Interacting with the blockchain application via the dashboard plugin, 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

   // ...


Now restart the app to apply the new configuration.

List of all available config options

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

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": 78,
        "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 to trusted machines.

To achieve this, configure a firewall that only allows access from whitelisted IPs

Please see the RPC endpoints and Communication 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