This guide will show you how to set up the first node of your new custom blockchain and then show you how to get additional nodes to join it. If you run into any issues, feel free to reach out to people from the Capitalisk or Leasehold communities for assistance.
A Capitalisk node runs on an decentralized engine called LDEM - It allows a single node to efficiently participate in multiple blockchains. With LDEM, it's possible to launch a new/custom blockchain using an existing Lisk custom module as the source (no coding necessary).
For example, the Capitalisk blockchain itself is based on a white-label module called ldpos-chain.
The Leasehold blockchain, on the other hand, is based on a different white-label module called leasehold-chain - The
leasehold-chain module is a fork of
lisk-chain so it is compatible with all the clients, wallets and tools from Lisk SDK v3.
leasehold-chain are designed to work with capitalisk-dex - This means that any custom blockchain which is based on either of these two modules can be easily listed for trading on https://ldex.trading/ and also on any other compatible
This guide focuses on how to launch a new custom blockchain based on the
ldpos-chain module since that's the module which the Capitalisk blockchain is based on.
This guide assumes that the new custom blockchain symbol will be
foo - You should substitute
foo with your own blockchain symbol everywhere (including file names) as you go through this guide. The blockchain symbol (also called network symbol) is a unique symbol or acronym used to represent a blockchain (E.g. for listing on exchanges).
1.1 Machine/instance requirements
- A machine/instance with a publicly exposed IP address (E.g. from a cloud service provider).
- 100GB of hard drive space is recommended (this should be enough for several years of data).
- Port 8001 needs to be open for inbound TCP traffic.
- All ports should be open for outbound TCP traffic.
1.2 A compatible LDEM node
To create a custom blockchain, you first need to have an LDEM node - Any node which is based on the LDEM engine is fine; this includes a Leasehold node or a Capitalisk node. But for the purpose of this guide, it is recommended to use a Capitalisk node - So you should follow the guide Set up a new Capitalisk node to setup a node. Make sure that you also have the
pm2 command installed globally on your node (
sudo npm install -g pm2).
1.3 LDPoS Commander CLI
You need to install the
ldpos-commander Node.js module using the following command:
npm install -g ldpos-commander
OR (if the above fails):
sudo npm install -g ldpos-commander
Check that the installation was successful using the command:
If the command outputs a version number, it means that the installation was successful.
2. Create a new genesis file
Each blockchain needs to start from a genesis state. Blockchains based on
ldpos-chain load their initial state from a genesis JSON file - It contains a list of accounts and balances which are present from the beginning of the blockchain as well as initial votes which determine who the initial forging delegates are.
For your custom blockchain, you will need to create your own
foo-genesis.json file - You can add as many genesis accounts to it as you want with whatever balance amounts and votes you want. You can create this file on your own computer (while preparing it); later, you will need to drop a copy of it inside a specific directory on your node.
foo-genesis.json file should follow the same structure as the
foo-genesis.json file of the Capitalisk blockchain: https://gist.github.com/jondubois/6061f01168f793308621b77b16ee64c1
- Copy the
foo-genesis.jsonfile from the link above to your own computer.
- Change the
networkSymbolto the symbol for your new blockchain (as you want it to appear on the DEX).
- Delete all the entries inside the
accountsarray; you will need to generate and add your own entries.
The simplest way to generate accounts is using
ldpos-commander using this command:
ldpos account generate
It will prompt you for the network symbol of your custom blockchain.
The output object should look like this:
"passphrase": "correct subway helmet chalk degree object cargo inquiry window goddess monster remain",
You should run this command multiple times (e.g. 10 times); each time, it will create a new account; you should save all the details for each account in a safe place; it's important not to lose the passphrases of the genesis accounts as you will need them to run and secure the network in the beginning.
Once you have generated all your genesis accounts, you should add their addresses and public keys to the
foo-genesis.json file inside the
Each account entry should look like this:
For each entry, you should substitute the
sigPublicKey with the relevant values for each account you generated. Make sure that each account entry is separated by a comma (must be valid JSON).
You can change the
balance of each account to suit your requirements;
1 token is
100000000 units so you need to ignore the last 8 zeroes in order to read the value in tokens - The example account above has a balance of
10 million tokens.
It's strongly recommended that you add a sufficient number of accounts to your
foo-genesis.json file to act as genesis delegates so that they take up
~66% of all available forging slots - In the beginning, it's important that the majority of available delegate slots are controlled by a trusted party (e.g. yourself) so that you don't lose control over the network before it's in a desirable state.
Once you've defined all the genesis accounts and their starting balances, you will need to specify the genesis votes in order to choose the block forgers.
The simplest approach is to make one of the genesis accounts hold most (or all) of the total token supply (specified in the
balance property) and make that account vote for itself as well as the other genesis accounts. To add votes, you just need to add a list of delegate addresses to the
votes array of the relevant genesis voter account (e.g. the one with the most tokens).
"votes": ["foo95bb3611a9796d2c4a1a352632331df4330987b8", "foob32a9b7182ead076b6dafc7b59f903edf9ba1b19", "fooa2495cacc5b2b3d08a548e05f061827021581af3"]
It's recommended that the genesis voter account vote for all the delegate accounts which you created in order to take up the majority of available forging slots (make sure you control
~66% of available forging slots). The voting could alternatively be done later (post-launch), but this is not recommended for most scenarios.
foo-genesis.json file is ready, you should drop it inside a directory on your remote Capitalisk node.
It's recommended that you drop it at the following relative path:
capitalisk-core is the directory where your node's source code is located.
3. Create a new database
If using SQLite, the database file will be created automatically so you can skip this step. Each node is free to choose their own database engine.
If using Postgres, you will need to create a new database to store the blockchain data.
Create a new Postgres database. If your blockchain is called
foo you may want to call it
foo_main (for mainnet).
The following commands may be different depending on your Postgres setup (change
foo_main with an appropriate database name):
postgres createdb foo_main
If using the default
postgres user, the command would be:
sudo -u postgres createdb foo_main
4. Add a new custom module config object
You will need to open your node's
config.json file (inside your main
Inside this file, you should find a field called
modules which is an array of module objects; these objects reference the module instances which will run on your node.
You will need to add the following object inside the array alongside existing entries:
Make sure that each module object inside the
modules array is separated by a comma (the
config.json file needs to be valid JSON).
In the above object, you will need to substitute
foo with the symbol of your custom chain throughout:
- The module name (
- The value of
- The value of
If you're using SQLite instead of Postgres, the object under
dal should look like this instead:
foo with your custom chain symbol in
5. Start your node
You can start the node using PM2:
pm2 start index.js --name "ldem-node" -o "/dev/null" -e "/dev/null"
If you get any errors, make sure that you don't have an existing node already running. If you do, you can shut it down using
pm2 delete ldem-node.
You should check the logs using the following command:
pm2 logs ldem-node
If you see a lot of error messages, it could be an indication that something went wrong.
Pay attention to the metadata inside the square brackets; it should tell you if the message is of type
ERROR; you can ignore most message types except for
ERROR. The logs should also tell you which module the message comes from - You should mostly concern yourself with messages from the
6. Get other nodes to join your new blockchain
You will need to provide participants with the following things:
- A copy of your prepared
foo-genesis.jsonfile from step
- An exact copy of your module config object from step
- A link to this guide: Join a custom blockchain.
You may want to provide additional assistance to new participants depending on their technical abilities; it can be helpful to compare logs with other participants to ensure that their nodes are running correctly.
If you run into any issues that you can't figure out, you can reach out to node operators from the Leasehold or Capitalisk community since we all use the same underlying technology.