Creating a new blockchain client

Bootstrapping a new blockchain client with Lisk Commander

Lisk Commander offers various commands related to Initializing a new blockchain client which can be used to conveniently get started.

Sample code

View the complete sample code of this guide on GitHub in the Lisk SDK examples repository.

Supported Operating Systems

The Lisk SDK runs on both Ubuntu and macOS operating systems and supports the following versions, as described below:

  • Ubuntu

  • macOS

  • 18.04 (LTS)

  • 20.04 (LTS)

  • 22.04 (LTS)

  • 10.13 (High Sierra)

  • 10.14 (Mojave)

  • 10.15 (Catalina)

  • 11.04 (Big Sur)

  • 12.6.1 (Monterey)

  • 13.0 (Ventura)

Please note that the SDK does not come with any official support for Windows.

Dependencies

Dependencies Version

Git

v2 (latest)

Node.js

v18 (latest LTS)

Lisk Commander

v6.0.0 (latest)

Homebrew (macOS)

v3.6.7 (latest)

automake

1.16.5 (latest)

autoconf

2.71 (latest)

curl (Ubuntu)

7.68.0 (latest)

build-essential (Ubuntu)

12.8 (latest)

python2

2.7 (latest)

Node.js

If you are using NVM (Node.js Version Manager), install the correct version as shown below:

nvm install 18

Lisk Commander

It is recommended to install Lisk Commander globally with NPM (Node Package Manager), to facilitate the convenient usage of the Lisk Commander CLI.

npm install --global lisk-commander

To check the successful installation of Lisk Commander, run the following command:

lisk --version
Output
lisk-commander/6.0.0 darwin-arm64 node-v18.16.0

Toolchain dependencies

Once Lisk Commander is installed, install the following compiler dependencies as well.

  • Ubuntu

  • macOS

sudo apt update
sudo apt install -y libtool automake autoconf curl build-essential python2-minimal

Ensure that Homebrew is installed.

brew install autoconf automake libtool python2

Initializing a new blockchain client

In this example, we want to create a new client hello_client.

Create a dedicated folder hello/:

mkdir hello
cd hello

Once you’re in the dedicated hello folder, create another folder named hello_client which will contain the logic for the blockchain client.

A corresponding UI example for the blockchain client is added to the hello folder later in the Integrating with UI guide.

/hello/
mkdir hello_client
cd hello_client

Inside the hello_client, execute the init command of Lisk Commander as shown below:

/hello/hello_client/
lisk init
The init command can be executed anywhere on the disk to bootstrap a sidechain client, however, to accommodate both frontend and the sidechain client, we have to create the aforementioned folders.

As a result of executing the init command, you will be asked for the Name, ChainID, Description, Author, and License of the blockchain client.

Using template "lisk-ts"
Initializing git repository
Updating .liskrc.json file
Creating project structure
? Application name hello_client
? Chain ID in hex representation. ChainID must be 4 bytes (8 characters) 12345678
? Application description A simple blockchain application that saves hello messages in user accounts.
? Author XYZ
? License ISC

Next, all the required files are created by Lisk Commander.

Using the client CLI globally

To use the client CLI commands globally, create an alias in the .bashrc or .zshrc file depending on the operating system that you are using.

  • bashrc

  • zshrc

~/.bashrc/
alias hello_client="$HOME/hello_client/bin/run"

Add the path to where your hello_client is located.

After updating the .bashrc file, make it directly available in the terminal by executing the following:

. ~/.bashrc
~/.zshrc/
alias hello_client="$HOME/hello_client/bin/run"

Add the path to where your hello_client is located.

After updating the .zshrc file, make it directly available in the terminal by executing the following:

. ~/.zshrc

Now it is possible to conveniently run these client CLI commands from anywhere by referring to the alias.

hello_client --help

The above command will display the general CLI command reference:

Available commands
Lisk-SDK Client

VERSION
  hello_client/0.1.0 darwin-arm64 node-v18.16.0

USAGE
  $ hello_client [COMMAND]

TOPICS
  block          Commands relating to hello_client blocks.
  blockchain     Commands relating to hello_client blockchain data.
  config         Commands relating to hello_client node configuration.
  endpoint       Commands relating to hello_client endpoint.
  generator      Commands relating to hello_client block generator.
  genesis-block  Creates a genesis block file.
  keys           Commands relating to hello_client key generation.
  node           Commands relating to hello_client node.
  passphrase     Commands relating to hello_client passphrases.
  transaction    Commands relating to hello_client transactions.

COMMANDS
  autocomplete  Displays autocomplete installation instructions
  console       Lisk interactive REPL session to run commands.
  hash-onion    Creates hash onions to be used by the forger.
  help          Displays help for hello_client.
  start         Starts Blockchain Node.
  version

File & folder structure

The blockchain client will have the following file structure after the first initialization:

.
├── bin/ (1)
│   ├── run
│   └── run.cmd
├── config/ (2)
│   └── default/
│   │   ├── config.json
│   │   ├── dev-validators.json
│   │   ├── genesis_assets.json
│   │   ├── genesis_block.blob
│   │   └── passphrase.json
├── src/
│   ├── app/ (3)
│   │   ├── app.ts (4)
│   │   ├── index.ts
│   │   ├── modules/ (5)
│   │   ├── modules.ts (6)
│   │   ├── plugins/ (7)
│   │   └── plugins.ts (8)
│   └── commands/ (9)
├── test/ (10)
├── jest.config.js
├── package-lock.json
├── package.json
├── readme.md
└── tsconfig.json
1 bin/: Contains the script to run the CLI of the client.
2 config/: Contains the configuration, dev-validators, genesis assets, genesis block, and passphrase files that are used by the application.
3 app/: Contains the files of the blockchain client.
4 app.ts: Creates the Application instance of the client.
5 modules/: Contains modules of the client. This folder is empty after the first initialization with the lisk init. The command lisk generate:module creates a new module in this folder.
6 modules.ts Registers the modules with the client.
7 plugins/: Contains plugins of the client. This folder is empty after the first initialization with lisk init. The command lisk generate:plugin creates a new plugin in this folder.
8 plugins.ts Registers the plugins with the client.
9 commands/: Contains the logic for the CLI commands of the client. The files for the different commands can be adjusted and extended as desired, for example, to include new flags and commands.
10 test/: Contains the test files for the unit, functional, and integration tests.

These files create a ready-to-start blockchain client configured for a local devnet, which uses only the default modules of the Lisk SDK.

Default modules
Lisk provides a range of default modules out of the box. These modules are created automatically, whenever a blockchain client is bootstrapped via Lisk Commander. The default modules provide basic blockchain functionality required by a blockchain client to work. For more information, see the Modules overview page.

Starting the client

The client is created in the file app.ts:

src/app/app.ts
import { Application, PartialApplicationConfig } from 'lisk-sdk';
import { registerModules } from './modules';
import { registerPlugins } from './plugins';

export const getApplication = (config: PartialApplicationConfig): Application => {
	const { app } = Application.defaultApplication(config); //Creates a sidechain client with the default modules.

  // Will register additional modules to the client.
  // Currently, no additional modules are available for the client.
  // To add new modules update the `modules.ts` file.
	registerModules(app);

  // Will register additional plugins to the client.
  // Currently, no plugins are available for the client.
  // To add new plugins update the `plugins.ts` file.
	registerPlugins(app);

	return app;
};

In most cases, the default modules don’t need to be changed, as they provide the basic functionality that most blockchain clients need. But in case you want to replace the default modules with other modules, you can also run the application without the default modules by replacing

const { app } = Application.defaultApplication(config);

with

const app = new Application(config);

Please be aware that if you create the client with const app = new Application(config);, then you need to register all modules manually in the app.ts file.

This way it is also possible to include some, but not all the default modules in the client application.

To verify the successful bootstrap of the blockchain client, start it with the following command:

hello_client start
In case you change the contents of the app.ts file, or any other source file of the client then, run the following command before starting the client: 
npm run build

The start command offers various options, allowing further configuration of the client. For example, it is possible to define ports or to enable plugins for the client. For a complete list of all available start options, visit the relevant client CLI reference.

Executing the start command should kick off the blockchain client, which is currently running with a local single-node development network.

Observe the displayed log messages in the console. If no errors are thrown, the application will start to add new logs every 10 seconds after the initial startup.

Once it is verified that the client is functioning correctly, stop the client again with Ctrl + C.

The corresponding application data can be found under the path ~/.lisk/hello_client/, once the client starts successfully for the first time.

~/.lisk/hello_client/
.
├── config
│   └── default
│   │   ├── config.json (1)
│   │   ├── dev-validators.json (2)
│   │   ├── genesis_assets.json (3)
│   │   ├── genesis_block.blob (4)
│   │   └── passphrase.json (5)
├── data  (6)
│   ├── blockchain.db
│   ├── generator.db
│   ├── module.db
│   ├── node.db
│   └── state.db
├── logs  (7)
├── plugins (8)
└── tmp (9)
1 config.json is the configuration file of the blockchain client.
2 dev-validators.json contains the details of all the Devnet validators that generate a block.
3 genesis_assets.json contains all the initial accounts and asset details. It is used to create the genesis block for the blockchain.
4 genesis_block.blob is the genesis block of the blockchain client.
5 passpharase.json contains the passphrase of the Devnet validators.
6 data contains the on-chain and off-chain data of the blockchain, data is stored in key-value stores.
7 logs contains the file logs of the client and its plugins.
8 plugins contains all the off-chain data relating to the plugins of the application, data is stored in key-value stores.
9 tmp contains temporary data.

How to reset the database of a blockchain client

Once the client starts for the first time, it saves the client-specific data under the path ~/.lisk/hello_client/.

To reset the database of the client, simply delete the folder with the client data:

rm -r ~/.lisk/hello_client/data/
Once removed, the hello_client/data folder is recreated automatically after the sidechain client starts again.

Next steps

By installing Lisk Commander and running lisk init, a functional blockchain client now exists with the default configurations for running in a local Devnet.

To extend the blockchain client further, it is required to register additional modules and/or plugins to the client.