How to run a custom Lisk sidechain node

This guide will show you:

  • How to install the necessary modules on a Lisk node
  • How to register the necessary modules on a Lisk node
  • How to setup a Postgres database for your sidechain
  • How to configure your sidechain

This guide will focus on how to run a node as part of the Capitalisk sidechain on testnet with a DEX. To make your own custom sidechain, you can fork https://github.com/jondubois/capitalisk

Before you start, you need to setup a Lisk node which can run from source. See the Lisk guide: https://lisk.io/documentation/lisk-core/setup/source.html — lisk-core version 2.1.x is recommended. This guide was tested with lisk-core v2.1.3.

Once you have a lisk-core node running from source without errors, you are ready to install a custom sidechain on that node.

Part 1: How to install the necessary modules on a Lisk node

Make sure that you have your terminal open with lisk-core as your working directory.

You will need to install 3 modules.

Firstly, you need a plugin called lisk-interchain. This module will:

  • Allow your sidechain nodes to find each other and form subnets within the Lisk network.
  • Provide advanced routing features to allow your sidechain nodes to communicate with each other efficiently.

Install lisk-interchain using this command:

Then, you will need to install your sidechain module, in this case capitalisk:

These 2 modules are enough to run a sidechain node, but you may also want to expose your sidechain via an HTTP API (similar to the Lisk HTTP API) so then you should install the capitalisk-http-api module:

Part 2: How to register the necessary modules on a Lisk node

Now that you’ve installed the three modules, you should register them on your Lisk node.

To do this, open the file src/index.ts.

Near the top of the file, add the following lines:

Now scroll down to the part of the code where the app launches using app.run() — Just before that line, add the following lines:

Note that the location of the lines is important. See https://gist.github.com/jondubois/a6b21c1b3f77101de0809f0b9e0c6298#file-lisk-core_src_index-ts-L8-L10 and https://gist.github.com/jondubois/a6b21c1b3f77101de0809f0b9e0c6298#file-lisk-core_src_index-ts-L51-L56 for reference.

Now save src/index.ts and compile the code with your custom modules using the following command:

Part 3: How to setup a Postgres database for your sidechain

You need to create a new Postgres database where all your sidechain’s data will be stored. Your sidechain will use the same underlying database engine as the main Lisk chain but under a separate database name. Call it capitalisk_test.

You can create a new database using the following command (example):

The exact steps may vary depending on your system but it is similar to how you would setup the database for Lisk testnet except that you need to use capitalisk_test instead of lisk_test as the database name.

Part 4: How to configure your sidechain

To run the node on testnet, you need to edit the testnet config file.

Open the file config/testnet/config.json and add the following config properties/objects inside the main modules object above other entries:

That’s it. You can now launch your sidechain node. If successful, your node should populate your new capitalisk_test database with data and start synching with the rest of the network.

Note that if you get an error like FATAL: sorry, too many clients already, this should easily be fixed by increasing the max number of connections in your Postgres database config file. See: https://stackoverflow.com/questions/30778015/how-to-increase-the-max-connections-in-postgres

Note that the config object for the capitalisk module is essentially the same as the chain module in Lisk 2.x. You can also specify delegate details in the same way. You can enable forging using the HTTP API in the same way; the main difference is that your sidechain HTTP API will be exposed on port 7010 instead of port 7000.

To find out how to connect your sidechain to Lisk via a DEX, see https://medium.com/@jonathangrosdubois/how-to-setup-a-dex-to-allow-users-to-trade-a-custom-sidechain-token-for-lsk-68e22f0eea26

Additional config for small subnet

The capitalisk testnet may not have many nodes in the subnet, if this is the case, it can take a while for your node to find the others and start synching the capitalisk chain and it can become detached easily due to network shuffling. If this is the case, you may want to add one or both of these IPs as fixedPeers in your config/testnet/config.json file:

  • 3.93.232.78
  • 34.227.22.98

For example, like this (for testnet, set wsPort as 7001):

This will not be necessary once the network reaches a certain size (e.g. 10 to 20 nodes).

You don’t have to use the IPs above, it can be the IP of any node which you know is part of the capitalisk subnet.