Client configuration

A complete reference of the client configurations is described on this page.

Configuration

By default, each blockchain client has a set of configurations that enable it to run properly.

For more information on how to create and use a custom configuration for the client, please check out the guide Blockchain client configuration. The configuration schema can be found at client config schema

The configuration of a blockchain client has the following options, as listed below:

By default, the complete configuration for a Lisk blockchain client looks like this:

Default config options
export const defaultConfig = {
	// Contains configuration for the blockchain client.
	"system": {
		"dataPath": "~/.lisk/beta-sdk-app",
		"keepEventsForHeights": 300,
		"logLevel": "info",
	},

	// The rpc protocol defines communication behavior.
	"rpc": {
		"modes": ["ipc"],
		"port": 7887,
		"host": "127.0.0.1",
	},

	//The network configuration holds the network information of the node.
	"network": {
		"version": "1.0",
		"seedPeers": [],
		"port": 7667,
	},

	// Contains configuration about a transaction pool.
	"transactionPool": {
		"maxTransactions": 4096,
		"maxTransactionsPerAccount": 64,
		"transactionExpiryTime": 3 * 60 * 60 * 1000,
		"minEntranceFeePriority": "0",
		"minReplacementFeeDifference": "10",
	},

	// The genesis configuration holds the blockchain protocol configurations.
	"genesis": {
		"block": {
			"fromFile": "./config/genesis_block.blob",
		},
		"blockTime": 10,
		"bftBatchSize": 103,
		"maxTransactionsSize": 15 * 1024, // Kilo Bytes
		"minFeePerByte": 1000,
		"chainID": "0x00000000",
	},

	// Contains the directory path to the "keys" file required by the generator.
	"generator": {
		"keys": {},
	},

	// (Optional) modules hold a group of module-specific configs which is passed to a particular module.
	"modules": {},

	// (Optional) plugins hold a group of plugin-specific configs which is passed to a particular plugin.
	"plugins": {},
};

export const DEFAULT_KEY_DERIVATION_PATH = "m/25519'/134'/0'/0'";
The DEFAULT_KEY_DERIVATION_PATH points to the path for deriving the private key of the n-th generator key pair. For more information, see Introduce tree based key derivation and account recovery.

The following sections describe various configuration categories and their available options.

network

The network category contains the following configuration options:

  • Properties

  • Sample

Property’s Name Datatype Optionality Description Sample

version

string

mandatory

The version of network protocol.

1.0

port

number

mandatory

The port defines an open port for P2P incoming connections.

7667

seedPeers

object[]

mandatory

SeedPeers defines an entry point of the network.

 
"seedPeers": [{
	"ip": "127.0.0.1",
	"port": 5000
}]

host

string

optional

Address of the server to connect to.

127.0.0.1

blacklistedIPs

string[]

optional

A list of IP addresses for which the node will reject the connection for both outbound and inbound connections.

192.168.178.23

fixedPeers

object[]

optional

A set of peers to which a node will always try to connect, for outbound connections.

 
"fixedPeers": [{
	"ip": "192.110.01.12",
	"port": 5000
}]

whitelistedPeers

object[]

optional

Set of peers that are always allowed to connect to the node through inbound connections.

 
"whitelistedPeers": [{
	"ip": "192.110.01.12",
	"port": 5000
}]

maxOutboundConnections

number

optional

The maximum number of outbound connections allowed.

20[1]

maxInboundConnections

number

optional

The maximum number of inbound connections allowed.

100[1]

wsMaxPayload

number

optional

The maximum size of the payload allowed per communication.

3048576[1]

advertiseAddress

boolean

optional

Defines whether to announce the IP/Port to other peers.

true[1]

 
const customConfig =
{
	// Other types of configurations.
	"network": {
		"version": "1.0",
		"seedPeers": [
			{
				"ip": "127.0.0.1",
				"port": 5000
			}
		],
		"port": 7667,
		"host": "127.0.0.1",
		"blacklistedIPs": [
			"172.112,31.0",
			"172.112,31.2"
		],
		"fixedPeers": [
			{
				"ip": "192.110.01.12",
				"port": 5000
			},
		]
		"whitelistedPeers": [
			{
				"ip": "192.110.01.12",
				"port": 5000
			},
		],
		"maxOutboundConnections": 20,
		"maxInboundConnections": 100,
		"wsMaxPayload": 3048576,
		"advertiseAddress": true,
		},
	// Other types of configurations.
}
The connectivity of the node might be negatively impacted if the fixedPeers configuration is used. Beware of declaring only trustworthy peers in whitelistedPeers as these could attack a node with a denial-of-service attack because the banning mechanism is deactivated.

genesis

The genesis configuration holds the settings for the blockchain protocol.

  • Properties

  • Sample

Property’s Name Datatype Optionality Description Sample

block

object

optional

This is the first block of a chain.

 
"block": {
	"fromFile": "./config/genesis_block.blob'",
	"blob": "<<Hex of encoded genesis block>>",
},

chainID

string

mandatory

Represents a 4-byte hex string that identifies each chain in the Lisk ecosystem. The length of the hex string should be 8 characters.

0x00000000

maxTransactionsSize

number

mandatory

The maximum transaction size (kilobytes) allowed in a block.

15 * 1024

minFeePerByte

number

mandatory

The minimum fee per byte for a transaction.

1000

blockTime

number

mandatory

The frequency of blocks to be created.

10

bftBatchSize

number

mandatory

The length of a round for block generation.

103

 
const customConfig =
{
	// Other types of configurations.
	"genesis": {
		"block": {
			"fromFile": "./config/genesis_block.blob",
			"blob": "<<Hex of encoded genesis block>>",
		},
		"chainID": "0x00000000",
		"maxTransactionsSize": 15 * 1024, // Kilo Bytes
		"minFeePerByte": 1000,
		"blockTime": 10,
		"bftBatchSize": 103,
	},
	// Other types of configurations.
}

transactionPool

This type of configuration holds the settings for the transaction pool.

  • Properties

  • Sample

Property’s Name Datatype Optionality Description Sample

maxTransactions

number

optional

The maximum number of transactions in the pool.

4096

maxTransactionsPerAccount

number

optional

The maximum number of transactions in the pool per sender account.

64

transactionExpiryTime

number

optional

Defines the timeout (milliseconds) of the transaction in the pool.

3 * 60 * 60 * 1000

minEntranceFeePriority

string

optional

The minimum fee required for a transaction to be added to the transaction pool.

0

minReplacementFeeDifference

string

optional

The difference of minimum fee required to replace a transaction with the same nonce

10

 
const customConfig =
{
	// Other types of configurations.
	"transactionPool": {
		"maxTransactions": 4096,
		"maxTransactionsPerAccount": 64,
		"transactionExpiryTime": 3 * 60 * 60 * 1000,
		"minEntranceFeePriority": "0",
		"minReplacementFeeDifference": "10",
	},
	// Other types of configurations.
}

system

The system configuration holds settings for the node.

  • Properties

  • Sample

Property’s Name Datatype Optionality Description Sample

version

string

mandatory

The version of the system.

1.0

dataPath

string

mandatory

DataPath defines the folder path for the client application data.

~/.lisk/beta-sdk-app

keepEventsForHeights

number

mandatory

Defines the number of blocks for which the events should be maintained by the system. Usually, the events are based on the latest, given number of blocks.

300[1]

logLevel

string

mandatory

Level of the log to be maintained.

info

 
const customConfig =
{
	// Other types of configurations.
	"system": {
		"version": "1.0"
		"dataPath": "~/.lisk/beta-sdk-app",
		"keepEventsForHeights": 300,
		"logLevel": "info",
	},
	// Other types of configurations.
}

rpc

Apps on Lisk can communicate with a node via the rpc communication protocol.

  • Properties

  • Sample

Property’s Name Datatype Optionality Description Sample

modes

enum

mandatory

Modes of communication between lisk node and external services.

IPC, WS, HTTP

port

number

mandatory

Port to be used for a 'WS' connection.

7887

host

string

mandatory

Address of the server to connect.

127.0.0.1

 
const customConfig =
{
	// Other types of configurations.
	"rpc": {
		"modes": ["IPC"],
		"port": 7887,
		"host": "127.0.0.1",
	},
	// Other types of configurations.
}

generator

The generator configuration is used to read keys from a file, which are then stored in the database.

  • Properties

  • Sample

Property’s Name Datatype Optionality Description Sample

keys

object

optional

Contains a path to the "keys" file for the generator.

 
"generator": {
	"keys": {},
},
 
const customConfig =
{
	// Other types of configurations.
	"generator": {
		"keys": {
			"fromFile": "<<path/filename>>",
		},
	},
	// Other types of configurations.
}

keys schema

The file passed to the generator configuration contains the schema for the keys to be used by the generator.

For more information, see plainKeysObjectSchema, encryptedObjectSchema and a sample keys_fixture.json.

  • Properties

  • Sample keys file

Property’s Name Datatype Optionality Description Sample

address

string

mandatory

Lisk 32 address[2] for the generator.

lsk24cd35u4jdq8szo3pnsqe5dsxwrnazyqqqg5eu

plain

object

mandatory

Contains the object for plain keys.

 
"plain": {
	"generatorKey": "",
	"generatorPrivateKey" : "",
	"blsKey": "",
	"blsPrivateKey": ""
},

encrypted

object

mandatory

Contains the object for encrypted keys.

 
"encrypted": {
	"version": ,
	"ciphertext": ,
	"kdf": ,
	"kdfparams" : {},
	"cipher": '',
	"cipherparams": {}
},
 
{
	"keys": [
		{
		"address": "lske5sqed53fdcs4m9et28f2k7u9fk6hno9bauday",
		"keyPath": "m/44'/134'/0'",
		"publicKey": "a3f96c50d0446220ef2f98240898515cbba8155730679ca35326d98dcfb680f0",
		"privateKey": "d0b159fe5a7cc3d5f4b39a97621b514bc55b0a0f1aca8adeed2dd1899d93f103a3f96c50d0446220ef2f98240898515cbba8155730679ca35326d98dcfb680f0",
		"plain": {
			"generatorKeyPath": "m/25519'/134'/0'/0'",
			"generatorKey": "b9e54121e5346cc04cc84bcf286d5e40d586ba5d39571daf57bd31bac3861a4a",
			"generatorPrivateKey": "b3c4de7f7932275b7a465045e918337ffd7b7b229cef8eba28f706de8759da95b9e54121e5346cc04cc84bcf286d5e40d586ba5d39571daf57bd31bac3861a4a",
			"blsKeyPath": "m/12381/134/0/0",
			"blsKey": "92f020ce5e37befb86493a82686b0eedddb264350b0873cf1eeaa1fefe39d938f05f272452c1ef5e6ceb4d9b23687e31",
			"blsProofOfPosession": "b92b11d66348e197c62d14af1453620d550c21d59ce572d95a03f0eaa0d0d195efbb2f2fd1577dc1a04ecdb453065d9d168ce7648bc5328e5ea47bb07d3ce6fd75f35ee51064a9903da8b90f7dc8ab4f2549b834cb5911b883097133f66b9ab9",
			"blsPrivateKey": "463dd3413051366ee658c2524dd0bec85f8459bf6d70439685746406604f950d"
		},
		"encrypted": {
			"ciphertext": "d340438fde7b744d7482f01531415ffc0bda70dac36257571bb0dab703771e83152428b4a4dddc77dff1a983f07b0f3cba688fab2e46abe970ae4131c616e6cbf613952786f5749e94531641f07fcdef38a001a44f56f5de69e0976964ea13cbaff0682b5e0eaf9ff01a00f5b2215a3a1d9e3f0d5b78c876b157213367f7f90a468937c0baf9904189c21870c396b43b53422422bd61a3e1c8cb3126e1a5d60545aa06ee789c89dfb9155b560c327a88af5f9b04b4c6d4e9",
			"mac": "d476a90c1fb057a1e4ece0d725f40f67ae36efcc166aede5380115d2a7532833",
			"kdf": "argon2id",
			"kdfparams": {
			"parallelism": 4,
			"iterations": 1,
			"memorySize": 2024,
			"salt": "ecc014a7619b7f179b3fa32d2fed5d6c"
			},
			"cipher": "aes-256-gcm",
			"cipherparams": {
			"iv": "328cf25fdda6988ed9f1101e",
			"tag": "1862fde73a2a7b71979773bf620872ef"
			},
			"version": "1"
		}
		}
	]
}
1. This is the default value.
2. For more information, see the New LISK ID System.