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
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.
lisk-interchain using this command:
npm install lisk-interchain --save
Then, you will need to install your sidechain module, in this case
npm install capitalisk --save
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
npm install capitalisk-http-api --save
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
Near the top of the file, add the following lines:
import attachInterchain from 'lisk-interchain';
import CapitaliskModule from 'capitalisk';
import CapitaliskHTTPAPI from 'capitalisk-http-api';
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.
src/index.ts and compile the code with your custom modules using the following command:
npm run build
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
You can create a new database using the following command (example):
sudo -u postgres -i createdb capitalisk_test --owner lisk
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
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.