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:
-
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.
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.
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:
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
:
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/
. ├── 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. |
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 Both objects can be customized before passing them to the 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. |