Creating a new blockchain application

How to create a new blockchain application with the Lisk SDK.

To get started with the development of a blockchain application in the most simple and efficient manner, it is recommended to follow the guide Bootstrapping a new blockchain application with Lisk Commander.

If you prefer not to use Lisk Commander to get started with development, the Manual Setup (alternative without Lisk Commander) is explained below.

The Hello World application

In this guide and the following guides, it is explained step by step how to create a very simple blockchain which allows users to save hello messages in their accounts.

The following image provides an overview of the Hello application:

hello overview

To achieve this, complete the following steps:

  1. Bootstrapping a new blockchain application with Lisk Commander: The current guide is the first guide and explains how to bootstrap a default blockchain application.

  2. Creating a module: This guide explains how to create a new module and how to add it to the application. In the example, the HelloModule will contain all on-chain logic related to the hello message.

  3. Creating a module asset: This guide explains how to create a new asset and how to add it to a module. In the example, the HelloAsset saves hello messages of users into their accounts, if they send a corresponding transaction.

  4. Creating a plugin: This guide explains how to create a new plugin and how to add it to the application. In the example, the HelloPlugin will contain one action, which will return the latest hello message which was sent to the network, and its sender address.

Bootstrapping a new blockchain application with Lisk Commander

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

Sample code

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

Supported Operating Systems

The Lisk SDK will run on both the Ubuntu and MacOS operating systems shown below:

  • Ubuntu

  • MacOS

  • 18.04 (LTS)

  • 20.04 (LTS)

  • 10.13 (High Sierra)

  • 10.14 (Mojave)

  • 10.15 (Catalina)

  • 11.04 (Big Sur)

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

Dependencies

Dependencies Version

Git

v2 (latest)

Node.js

v12 (latest)

Lisk Commander

v5.1.2 (latest)

Node.js

If you are using NVM, install the correct version as shown below:

nvm install v12.22.3

Lisk Commander

It is recommended to install Lisk Commander globally with NPM 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
lisk-commander/5.1.2 darwin-x64 node-v12.22.3

Initializing a new blockchain application

In this example, we want to create a new blockchain application with the name hello_app.

Therefore, create a dedicated folder hello_app/, which will contain the files for the application.

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

mkdir hello_app
cd hello_app
lisk init

The user is asked for the application name, description, author, and license after running lisk init.

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

Using template "lisk-ts"
Initializing git repository
Updating .liskrc.json file
Creating project structure
? Application name hello_app
? Application description A simple blockchain application that saves hello messages in user accounts.
? Author mona
? License ISC
   create package.json
   create .liskrc.json
   create .eslintignore
   create .eslintrc.js
   create .lintstagedrc.json
   create .prettierignore
   create .prettierrc.json
   create README.md
   create jest.config.js
   create tsconfig.json
   create bin/run
   create bin/run.cmd
   create test/.eslintrc.js
   create test/_setup.js
   create test/tsconfig.json
   create src/app/app.ts
   create src/app/index.ts
   create src/app/modules.ts
   create src/app/plugins.ts
   create src/commands/console.ts
   create src/commands/hash-onion.ts
   create src/commands/start.ts
   create test/integration/.gitkeep
   create test/network/.gitkeep
   create test/utils/config.ts
   create src/app/modules/.gitkeep
   create src/app/plugins/.gitkeep
   create src/commands/account/create.ts
   create src/commands/account/get.ts
   create src/commands/account/show.ts
   create src/commands/account/validate.ts
   create src/commands/block/get.ts
   create src/commands/blockchain/export.ts
   create src/commands/blockchain/hash.ts
   create src/commands/blockchain/import.ts
   create src/commands/blockchain/reset.ts
   create src/commands/config/create.ts
   create src/commands/config/show.ts
   create src/commands/forger-info/export.ts
   create src/commands/forger-info/import.ts
   create src/commands/forging/config.ts
   create src/commands/forging/disable.ts
   create src/commands/forging/enable.ts
   create src/commands/forging/status.ts
   create src/commands/genesis-block/create.ts
   create src/commands/node/info.ts
   create src/commands/passphrase/decrypt.ts
   create src/commands/passphrase/encrypt.ts
   create src/commands/transaction/create.ts
   create src/commands/transaction/get.ts
   create src/commands/transaction/send.ts
   create src/commands/transaction/sign.ts
   create test/commands/account/create.spec.ts
   create test/unit/modules/.gitkeep
The application CLI offers various commands to conveniently manage your blockchain application.

As shown in the snippet above, a new folder src/commands/ will be created, which contains all files for the available command-line commands of the application.

Using the application CLI globally

To use the application commands globally, create an alias in the .bashrc file.

~/.bashrc/
alias hello_app="$HOME/hello_app/bin/run" (1)
1 Adjust to the path where your hello_app is located.

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

. ~/.bashrc

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

hello_app --help

The above command will display the general CLI command reference:

Available commands
My blockchain application

VERSION
  hello_app/0.1.0 darwin-x64 node-v12.22.3

USAGE
  $ hello_app [COMMAND]

TOPICS
  account        Commands relating to hello_app accounts.
  block          Commands relating to hello_app blocks.
  blockchain     Commands relating to hello_app blockchain data.
  config         Commands relating to hello_app node configuration.
  forger-info    Commands relating to hello_app forger-info data.
  forging        Commands relating to hello_app forging.
  genesis-block  Creates genesis block file.
  node           Commands relating to hello_app node.
  passphrase     Commands relating to hello_app passphrases.
  transaction    Commands relating to hello_app transactions.

COMMANDS
  autocomplete  Display autocomplete installation instructions.
  console       Lisk interactive REPL session to run commands.
  hash-onion    Create hash onions to be used by the forger.
  help          Display help for hello_app.
  start         Start Blockchain Node.

Starting the application

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

.
├── bin/ (1)
│   ├── run
│   └── run.cmd
├── config/ (2)
│   └── default/
│       ├── config.json
│       └── genesis_block.json
├── jest.config.js
├── package-lock.json
├── package.json
├── src/
│   ├── app/
│   │   ├── app.ts
│   │   ├── index.ts
│   │   ├── modules/ (3)
│   │   ├── modules.ts
│   │   ├── plugins/ (4)
│   │   └── plugins.ts
│   └── commands/ (5)
└── test/ (6)
1 bin/: Contains the script to run the CLI of the application.
2 config/: Contains the configuration and the genesis block used by the application.
3 modules/: Contains internal modules of the application. This folder is empty after the first initialization with lisk init. The command lisk generate:module creates new modules in this folder.
4 plugins/: Contains internal plugins of the application. This folder is empty after the first initialization with lisk init. The command lisk generate:plugin creates new modules in this folder.
5 commands/: Contains the logic for the CLI commands of the application. The files for the different commands can be adjusted and extended as desired, for example, to include new flags and commands.
6 test/: Contains the test files for unit, functional and integration tests.

Use the following command to start the blockchain application.

hello_app start

The start command offers various options, allowing further configuration of the application. For example, it is possible to define ports or to enable plugins that will be used by the application. For a complete list of all available start options, visit the application CLI reference.

How to reset the database of an application

Once the application is started for the first time, it will save the application-specific data under the path ~/.lisk/hello_app/.

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

rm -r ~/.lisk/hello_app/data/

Next steps

By installing Lisk Commander and running lisk init, a working blockchain application now exists with the default configurations for running in a local devnet.

To extend the application further, you need to register additional modules and/or plugins at the application.

For the next step, proceed with the guide Creating a module.

Manual Setup (alternative without Lisk Commander)

How to create a new blockchain application manually without using the Lisk Commander.

Dependencies

  • Node.js v12 (latest)

If you are using NVM, install the correct version as shown below:

nvm install v12.22.3

Project setup

Create a new folder for the blockchain application and navigate into it.

mkdir my_blockchain_app
cd my_blockchain_app

Create a package.json file.

npm init --yes

Install the lisk-sdk package.

npm i lisk-sdk

Creating a blockchain application

Create a new file index.js. We want to use this file to store the code that will start the blockchain application by using the Lisk SDK.

In index.js, import the Application, genesisBlockDevnet and configDevnet from the the lisk-sdk package.

const { Application, genesisBlockDevnet, configDevnet } = require('lisk-sdk');

Now use the objects to create a blockchain application:

const app = Application.defaultApplication(genesisBlockDevnet, configDevnet);

This will create a new blockchain application that uses genesisBlockDevnet as the genesis block for the blockchain, and `configDevnet`to configure the application with common default options to run a node in a development network.

The lisk-sdk package contains the sample objects genesisBlockDevnet and configDevnet which enable the user to quickly spin up a development blockchain network. genesisBlockDevnet includes a set of preconfigured genesis delegates, that will immediately start forging on a single node to stabilize the network. configDevnet includes the configuration for the Devnet.

Both objects can be customized before passing them to the Application instance, if desired.

More information can be found in the guide Configuring a blockchain application.

Use app.run() to start the application:

app
	.run()
	.then(() => app.logger.info('App started...'))
	.catch(error => {
		console.error('Faced error in application', error);
		process.exit(1);
	});

After adding all of the above contents, save the file. Now it is possible to start a blockchain application with a default configuration, that will connect to a local devnet.

Starting the application

Start the application as shown below:

node index.js

To verify the application start, check the log messages in the terminal. If the start was successful, the application will enable forging for all genesis delegates and will start to add new blocks to the blockchain every 10 seconds.

After completing these steps, the default blockchain application of the Lisk SDK will now be running.

It is now possible to customize your application by registering new modules and plugins, and also adjusting the genesis block and config to suit your specific use case.