Configuring a blockchain application

This guide explains step-by-step, how to configure a blockchain application built with the Lisk SDK.

Prerequisites

To follow this guide, the following criteria is assumed:

When the application instance is created, the Application expects a configuration JSON object as the second argument, (the first one is the genesis block).

During development of a blockchain application it is recommended to import and use the configDevnet object from the Lisk SDK. Together with genesisBlockDevnet, which defines the genesis block, it sets up a local development environment with 101 forging genesis delegates.

index.js of the Hello World app
const { Application, configDevnet, genesisBlockDevnet, utils } = require('lisk-sdk'); (1)

// Create a custom config based on the configDevnet
const appConfig = utils.objects.mergeDeep({}, configDevnet, { (2)
    label: 'hello-app',
    genesisConfig: { communityIdentifier: 'hello' },
    rpc: {
        enable: true,
        mode: 'ws',
        port: 8888,
    },
    network: {
        port: 8887,
    },
    logger: {
        consoleLogLevel: 'info',
    },
});

// Create the application instance
const app = Application.defaultApplication(genesisBlockDevnet, appConfig); (3)
1 Imports Application, configDevnet, genesisBlockDevnet and utils from the lisk-sdk package.
2 Optionally it is possible to override certain options in configDevnet before creating the application instance.
3 Creates the application instance and passes the genesisBlockDevnet as genesis block and configDevnet as config.

The genesis block

When the application instance is created, the Application expects a genesis block as the first argument.

The devnet genesis block

The Lisk SDK exposes an object genesisBlockDevnet that holds all of the required configurations to spin up a local development network.

This genesis block can be used together with the configDevnet to quickstart your application with a preconfigured devnet.

Go to Github, to see the full file genesis_block_devnet.json

Configuration options

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

List of all available config options

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

Important configuration options

label

Change the name of the blockchain application by updating the label option.

Starting the app with a custom label
const { Application, configDevnet, genesisBlockDevnet, utils } = require('lisk-sdk'); (1)

// Create a custom config based on the configDevnet
const appConfig = utils.objects.mergeDeep({}, configDevnet, { (2)
    label: 'hello-app'
});

// Create the application instance
const app = Application.defaultApplication(genesisBlockDevnet, appConfig); (3)

genesisConfig

Specific constants for the blockchain application are set inside configDevnet.genesisConfig. These constants allow the basic properties of the blockchain to be easily adjusted. 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.
Starting the app with a custom genesisConfig
const { Application, configDevnet, genesisBlockDevnet, utils } = require('lisk-sdk');

// Create a custom config based on the configDevnet
const appConfig = utils.objects.mergeDeep({}, configDevnet, {
    genesisConfig: {
      bftThreshold: 78,
      communityIdentifier: 'hello',
      blockTime: 5,
      maxPayloadLength: 19000,
      rewards:{
        milestones: ['1000000000','700000000','500000000','200000000','100000000'],
        offset: 100,
        distance: 100000
      },
      minFeePerByte: 500,
      baseFees: [{
        moduleID: 2,
        assetID: 0,
        baseFee: 1000000,
      }]
    },
    activeDelegates: 31
    standbyDelegates: 5
});

// Create the application instance
const app = Application.defaultApplication(genesisBlockDevnet, appConfig);
Custom properties in the genesisConfig

Since all genesis config options will be passed, it is possible to add custom config options to the genesisConfig. These options can then be used in a specific custom module.

Adding a custom config option to the genesis config
const { Application, configDevnet, genesisBlockDevnet, utils } = require('lisk-sdk');

// Create a custom config based on the configDevnet
const appConfig = utils.objects.mergeDeep({}, configDevnet, {
    genesisConfig: {
      myCustomOption: 'Some data'
    },
});

// Create the application instance
const app = Application.defaultApplication(genesisBlockDevnet, appConfig);

rpc

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 Architecture pages for more information about the API access options.

Starting the app with a custom API access
const { Application, configDevnet, genesisBlockDevnet, utils } = require('lisk-sdk');

// Create a custom config based on the configDevnet
const appConfig = utils.objects.mergeDeep({}, configDevnet, {
    rpc: {
        enable: true, //true or false
        mode: 'ws', //'ws' or 'ipc'
        port: 8888, //websocket port
    },
});

// Create the application instance
const app = Application.defaultApplication(genesisBlockDevnet, appConfig);