Lisk SDK Overview

Logo

Mostly Harmless

Please read this carefully. The current version of the SDK is the alpha release of the Lisk SDK. We have released the Lisk SDK in its current form in order for us to improve the development experience through community feedback and contributions.

We strongly discourage anyone from using the alpha release of the Lisk SDK for any production-based blockchain applications, i.e. a blockchain operating on a real mainnet.

Over the course of the SDK’s alpha phase there will be significant changes in the Lisk protocol and implementation, which will eventually bring the accessibility and reliability to a level which is feasible for production-based blockchain applications.

At this time we only recommend the Lisk SDK for proof-of-concept blockchain applications, i.e. a blockchain operating on a fake testnet.

Be aware that the dummy delegate accounts are insecure, as their secret passphrases are public. In addition, the convenient creation of a new genesis block is not supported by alpha release of the Lisk SDK.

The only application built using the Lisk SDK currently feasible for production usage is Lisk Core, the client of the Lisk network itself.

Please be advised that we cannot guarantee blockchains created with the alpha release of the Lisk SDK will remain compatible with our planned (beta/rc) releases.

We hope you enjoy building your proof-of-concept blockchain applications using the Lisk SDK and look forward to receiving your feedback and contributions during the alpha phase.

What is the Lisk SDK?

The Lisk SDK aims to provide an easy and reliable software development kit for building blockchain applications compatible with the Lisk Protocol.

The architecture of the Lisk SDK has been designed so that it can be extended to meet the requirements of a wide variety of blockchain use cases.

The codebase is written entirely in JavaScript, which means for a majority of developers, no significant change of tools is required to get started.

The Lisk SDK makes every effort to allow developers to focus simply and purely on writing the code that matters to their own blockchain application, and nothing more.

SDK components

Directory Description

Framework

Lisk Framework is an application framework responsible for establishing and maintaining the interactions between the modules of a Lisk blockchain application.

Elements

Lisk Elements is a collection of libraries, each of them implementing some form of blockchain application functionality such as cryptography, transactions, p2p, etc. Each library is designed to be compatible with the Lisk Protocol.

Commander

Lisk Commander is a command line tool which allows you to manage a Lisk node instance and interact with a Lisk compatible network.

Architecture Overview

The Lisk SDK operates on the NodeJS runtime and consists primarily of an application framework (Lisk Framework), a collection of libraries providing blockchain application functionalities (Lisk Elements), and a powerful Command Line Interface (Lisk Commander) which allows developers to manage a Lisk node instance and interact with a Lisk compatible network.

The diagram below provides a high-level overview of the architecture:

Diagram

Usage

Dependencies

Before running Lisk SDK, the following dependencies need to be installed in order to run applications created with the Lisk SDK:

Dependencies Version

NodeJS

10.17.0

PostgreSQL

10+

Redis (optional)

5+

Python

2

You can find further details on installing these dependencies in our pre-installation setup guide.

Mind, that you need to create a database before. The default database name is lisk_dev, so for the development purposes, a command createdb lisk_dev will set you up. The default database user and password are lisk and password, they can be both changed in the configuration of Lisk SDK.

Installation

The installation of Lisk Alpha SDK is straightforward and limited to getting a single NPM package, lisk-sdk, to your Node.js project:

npm install lisk-sdk

Lisk SDK is all-in-one package that provides you with tools to create, run and maintain blockchain applications in JavaScript.

In case you only need some specific functionality, it is possible to install only the relevant package, e.g.:

npm install lisk-commmander (1)
npm install lisk-elements (2)
npm install @liskhq/lisk-transactions (3)
npm install @liskhq/lisk-cryptography (4)
1 Install Lisk Commander
2 Install Lisk Elements with all packages included
3 Install Lisk Elements Transactions Package
4 Install Lisk Elements Cryptography Package

How to build a blockchain application in 3 steps

3 steps to build a blockchain application

We constantly work on new proof of concept applications that show the features, capabilities and current limitations of the Lisk SDK.

For concrete examples how to build blockchain applications, check out the Tutorials page! Here, we provide detailed step-by-step guides for building the example applications yourself.

Lisk SDK Setup

To start, create the project structure of your blockchain application. Then install the Lisk SDK dependencies and the Lisk SDK afterwards.

npm init (1)
npm install lisk-sdk (2)
1 Initialize the project by creating a package.json file
2 Install the lisk-sdk package as dependency of your project. Make sure you installed the dependencies of lisk-sdk beforehand.

To create a blockchain application, you need to provide an entry point of your application (like index.js) and set-up your network by using the modules of Lisk SDK.

It is quite simple to have a working blockchain application, mirroring the configuration of the existing Lisk network. This can be done by copying the following three lines of code to your index.js:

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

const app = new Application(genesisBlockDevnet, configDevnet); (2)

app.run() (3)
   .then(() => app.logger.info('App started...')) (4)
   .catch(error => { (5)
        console.error('Faced error in application', error);
        process.exit(0);
});
1 Require the lisk-sdk package.
2 Create a new application with default genesis block for a local devnet.
3 Start the application.
4 Code that is executed after the successful start of the application.
5 Code that is executed if the application start fails.

Now, save and close index.js and try to start your newly created blockchain application by running:

node index.js | npx bunyan -o short
node index.js will start the node, and | npx bunyan -o short will pretty-print the logs in the console.

This should start the application with the predefined defaultconfigurations, which will connect your app to a local devnet. From this point, you can start to configure and customize the application further.

For more detailed explanations, check out the example applications, which describe the process of creating a blockchain applications step-by-step.

Configure your blockchain parameters

You can also define your blockchain application parameters such as BLOCK_TIME, EPOCH_TIME, MAX_TRANSACTIONS_PER_BLOCK and more with an optional configurations object.

const app = new Application(genesisBlockDevnet, {
    app: {
        label: 'my-blockchain-application',
        minVersion: '0.0.2',
        version: '2.3.4',
        protocolVersion: '4.1',
        genesisConfig: {
            EPOCH_TIME: new Date(Date.UTC(2016, 4, 24, 17, 0, 0, 0)).toISOString(),
            BLOCK_TIME: 10,
            MAX_TRANSACTIONS_PER_BLOCK: 25,
        },
        ...
});

Register a custom transaction

You can define your own transaction types with Lisk-SDK. This is where the custom logic for your blockchain application lives.

Add your custom transaction type to your blockchain application by registering it to the application instance:

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

const MyTransaction = require('./my_transaction'); (1)

const app = new Application(genesisBlockDevnet, configDevnet);

app.registerTransaction(MyTransaction); (2)

app
    .run()
    .then(() => app.logger.info('App started...'))
    .catch(error => {
        console.error('Faced error in application', error);
        process.exit(0);
    });
1 Require the custom transaction.
2 Register the custom transaction with the application.
For information on creating your own custom transaction, see the customize page or follow the tutorials.

How to interact with the network

While your network is up and running, interact with it and the node through the API and use Lisk Commander or Lisk Elements to create sendable transaction objects.

To monitor and explore the network, you may want to set up a monitoring solution like https://github.com/LiskHQ/lisk-explorer[Lisk Explorer].

Depending on the level of customization, Lisk Explorer and Lisk Commander may also require customization to prevent other services from failing.

Another simple way to interact with the network is by connecting it to Lisk Hub. Lisk Hub provides a simple and beautiful user interface to create and manage accounts on the network, and also to interact with the network by sending different types of transactions.

Once your blockchain is finished, and it is possible to send the transactions (and custom transactions), you can create a frontend to allow users to interact and use your blockchain application. To connect your frontend to your network, we recommend to make use of Lisk Elements’ packages like lisk-api-client.

Check out the example applications at the tutorials, to see concrete examples how to make first interactions with a blockchain application.

See more options on the Interact with the network page.

Exploring the API

The available API endpoints for node applications built with the Lisk SDK are currently identical to the Lisk Core API.

The module http_api of the Lisk Framework describes all API endpoints using swagger.

The API definition file is exported by a node under the path localhost:3000/api/spec (exchange localhost with the IP of the node you want to explore). See as example the definition file of a public Lisk Core Testnet node: https://testnet.lisk.io/api/spec

This API definiton can be pasted into the swagger-ui frontend to render a beautiful and interactive API specification of that particular node.

If the API of the node is public, it is also possible to send requests and get live responses from the node using Swagger UI.

To quickly render the API specification of a node, go to the Swagger UI Demo Site, paste the URL of the API definition file and hit Explore.

Get Involved

How Where

Introduce yourself to our community

Lisk Discord

Report a bug

Open a new issue on GitHub

Report a security issue

View Bug Bounty Program

Discuss technical research

Research Forum

Build with Lisk

Create a fork on GitHub

Resources

We’ve put together a list of helpful links that will guide you to the appropriate forum to get your questions answered quickly.

By using the Alpha release of the Lisk SDK, you acknowledge and agree that you have an adequate understanding of the risks associated with the use of the Alpha release of the Lisk SDK and that it is provided on an "as is" and "as available" basis, without any representations or warranties of any kind. To the fullest extent permitted by law, in no event shall the Lisk Foundation or other parties involved in the development of the Alpha release of the Lisk SDK have any liability whatsoever to any person for any direct or indirect loss, liability, cost, claim, expense or damage of any kind, whether in contract or in tort, including negligence, or otherwise, arising out of or related to the use of all or part of the Alpha release of the Lisk SDK.