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.

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

v16.15.0

Lisk Commander

v5.1.10 (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 v16.15.0

Lisk Commander

It is recommended to install Lisk Commander globally with the NPM (Node Packet Manager), in order 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.10 darwin-x64 node-v16.15.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

Ensure that Homebrew is installed.

brew install libtool cmake autoconf automake pyenv
pyenv install 2.7.18
pyenv global 2.7.18
# Add `eval "$(pyenv init --path)"` to ~/.zshrc etc

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 Navigate 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-v16.15.0

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 (Read-eval-print loop), 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/ (3)
│   │   ├── app.ts (4)
│   │   ├── index.ts
│   │   ├── modules/ (5)
│   │   ├── modules.ts (6)
│   │   ├── plugins/ (7)
│   │   └── plugins.ts (8)
│   └── commands/ (9)
└── test/ (10)
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 app/: Contains the files of the blockchain application.
4 app.ts: Creates the Application instance.
5 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.
6 modules.ts Registers the modules with the application.
7 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.
8 plugins.ts Registers the plugins with the application.
9 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.
10 test/: Contains the test files for unit, functional, and integration tests.

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

The application is created in the file app.ts:

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

export const getApplication = (
	genesisBlock: Record<string, unknown>,
	config: PartialApplicationConfig,
): Application => {
	const app = Application.defaultApplication(genesisBlock, config); (1)

	registerModules(app); (2)
	registerPlugins(app); (3)

	return app;
};
1 Creates a blockchain application with the default modules.
2 Will register additional modules to the application. Currently, no additional modules are available for the application. To add new modules update the modules.ts file.
3 Will register additional plugins to the application. Currently, no plugins are available for the application. To add new plugins update the plugins.ts file.

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

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.

This should start the blockchain application, 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 application is functioning correctly, stop the node again with kbd:[Ctrl] + kbd:[C].

After the application was started for the first time, the corresponding application data can be found under the path ~/.lisk/hello_app/

~/.lisk/hello_app/
.
├── config
│   └── default
│       ├── config.json (1)
│       └── genesis_block.json (2)
├── data  (3)
│   ├── blockchain.db
│   ├── forger.db
│   ├── genesis_block_compiled
│   └── node.db
├── logs  (4)
├── plugins (5)
└── tmp (6)
1 config.json is the configuration file of the blockchain application.
2 genesis_block.json is the genesis block of the blockchain application.
3 data contains all on-chain data of the blockchain, stored in key-value stores.
4 logs contains the file logs of the application and its' plugins.
5 plugins contains all off-chain data of the application, stored in key-value-stores.
6 tmp contains temporary application data.

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 in the application.

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

Manual Setup (alternative without Lisk Commander)

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

Dependencies

  • Node.js v16.15.0

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

nvm install v16.15.0

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. The genesisBlockDevnet includes a set of preconfigured genesis delegates, that will immediately start forging on a single node to stabilize the network. The 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 How to configure 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.