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 to not 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.

Dependencies

  • Node.js v12 (latest)

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

nvm install v12.22.1

Installing 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 --production lisk-commander

Initializing a new blockchain application

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

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

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

mkdir new_app
cd new_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 new_app
? Application description My blockchain application
? 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.

To run the application CLI, execute the following command in the root folder of the application:

/new_app/
./bin/run

Running the CLI command without any arguments will display the general command reference:

Available commands
My blockchain application

VERSION
  new_app/0.1.0 darwin-x64 node-v12.20.1

USAGE
  $ new_app [COMMAND]

TOPICS
  account        Commands relating to new_app accounts.
  block          Commands relating to new_app blocks.
  blockchain     Commands relating to new_app blockchain data.
  config         Commands relating to new_app node configuration.
  forger-info    Commands relating to new_app forger-info data.
  forging        Commands relating to new_app forging.
  genesis-block  Creates genesis block file.
  node           Commands relating to new_app node.
  passphrase     Commands relating to new_app passphrases.
  transaction    Commands relating to new_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 new_app.
  start         Start Blockchain Node.

For convenient usage of the application commands, assign an alias to the CLI command:

Example
alias new_app="$(cwd)/bin/run"
new_app

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)
└── tsconfig.json
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.

Use the following command to start the blockchain application.

./bin/run 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.

See the full list of available options in the reference below.

$ ./bin/run start --help
Start Blockchain Node.

USAGE
  $ new_app start

OPTIONS
  -c, --config=config                                    File path to a custom config. Environment variable "LISK_CONFIG_FILE" can
                                                         also be used.

  -d, --data-path=data-path                              Directory path to specify where node data is stored. Environment variable
                                                         "LISK_DATA_PATH" can also be used.

  -l, --log=trace|debug|info|warn|error|fatal            File log level. Environment variable "LISK_FILE_LOG_LEVEL" can also be
                                                         used.

  -n, --network=network                                  [default: default] Default network config to use. Environment variable
                                                         "LISK_NETWORK" can also be used.

  -p, --port=port                                        Open port for the peer to peer incoming connections. Environment variable
                                                         "LISK_PORT" can also be used.

  --api-ipc                                              Enable IPC communication. This will load plugins as a child process and
                                                         communicate over IPC. Environment variable "LISK_API_IPC" can also be
                                                         used.

  --api-ws                                               Enable websocket communication for api-client. Environment variable
                                                         "LISK_API_WS" can also be used.

  --api-ws-port=api-ws-port                              Port to be used for api-client websocket. Environment variable
                                                         "LISK_API_WS_PORT" can also be used.

  --console-log=trace|debug|info|warn|error|fatal        Console log level. Environment variable "LISK_CONSOLE_LOG_LEVEL" can also
                                                         be used.

  --dashboard-plugin-port=dashboard-plugin-port          Port to be used for Dashboard Plugin. Environment variable
                                                         "LISK_DASHBOARD_PLUGIN_PORT" can also be used.

  --enable-dashboard-plugin                              Enable Dashboard Plugin. Environment variable
                                                         "LISK_ENABLE_DASHBOARD_PLUGIN" can also be used.

  --enable-faucet-plugin                                 Enable Faucet Plugin. Environment variable "LISK_ENABLE_FAUCET_PLUGIN" can
                                                         also be used.

  --enable-forger-plugin                                 Enable Forger Plugin. Environment variable "LISK_ENABLE_FORGER_PLUGIN" can
                                                         also be used.

  --enable-http-api-plugin                               Enable HTTP API Plugin. Environment variable "LISK_ENABLE_HTTP_API_PLUGIN"
                                                         can also be used.

  --enable-monitor-plugin                                Enable Monitor Plugin. Environment variable "LISK_ENABLE_MONITOR_PLUGIN"
                                                         can also be used.

  --enable-report-misbehavior-plugin                     Enable ReportMisbehavior Plugin. Environment variable
                                                         "LISK_ENABLE_REPORT_MISBEHAVIOR_PLUGIN" can also be used.

  --faucet-plugin-port=faucet-plugin-port                Port to be used for Faucet Plugin. Environment variable
                                                         "LISK_FAUCET_PLUGIN_PORT" can also be used.

  --http-api-plugin-port=http-api-plugin-port            Port to be used for HTTP API Plugin. Environment variable
                                                         "LISK_HTTP_API_PLUGIN_PORT" can also be used.

  --http-api-plugin-whitelist=http-api-plugin-whitelist  List of IPs in comma separated value to allow the connection. Environment
                                                         variable "LISK_HTTP_API_PLUGIN_WHITELIST" can also be used.

  --monitor-plugin-port=monitor-plugin-port              Port to be used for Monitor Plugin. Environment variable
                                                         "LISK_MONITOR_PLUGIN_PORT" can also be used.

  --monitor-plugin-whitelist=monitor-plugin-whitelist    List of IPs in comma separated value to allow the connection. Environment
                                                         variable "LISK_MONITOR_PLUGIN_WHITELIST" can also be used.

  --overwrite-config                                     Overwrite network configs if they already exist.

  --seed-peers=seed-peers                                Seed peers to initially connect to, in the format of comma separated "ip:port".
                                                         IP can be DNS name or IPV4 format. Environment variable "LISK_SEED_PEERS"
                                                         can also be used.

EXAMPLES
  start
  start --network devnet --data-path /path/to/data-dir --log debug
  start --network devnet --api-ws
  start --network devnet --api-ws --api-ws-port 8888
  start --network devnet --port 9000
  start --network devnet --port 9002 --seed-peers 127.0.0.1:9001,127.0.0.1:9000
  start --network testnet --overwrite-config
  start --network testnet --config ~/my_custom_config.json

Next steps

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

To extend the application further, you need to register additional modules and/or plugins with your application. Either import external modules and plugins, or create completely new modules and plugins with the Lisk SDK.

More information can be found on the following pages:

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.1

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.