Introduction

Lisk Service is a web application that allows interaction with various blockchain networks based on Lisk and Bitcoin protocols.

The main focus of Lisk Service is to provide data to the UI clients such as Lisk Desktop and Lisk Mobile. Lisk Service makes it possible to access all blockchain live data in a similar way to the regular Lisk SDK API, and in addition provides users with much more details and endpoints, such as geolocation and various statistics about network usage.

The project implementation is based on Microservices. The technical stack is designed to deliver several microservices, and each of them provides one particular functionality. The data is served in JSON format and exposed by a public RESTful API.

Architecture

Architecture

Microservices

Table 1. The Lisk Service microservices
Microservice Description

Gateway

The Gateway component provides a RESTful HTTP API, which all users of Lisk Service can access and use. Its main purpose is to proxy API requests from users to other components provided by Lisk Service. It also maintains backwards compatibility when its public API is changed or replaced by a new version. This provides users with a central point of data access that never breaks existing application compatibility.

Lisk

The REST client component acts as a bridge between the Lisk SDK and the Lisk Service Gateway. Its main purpose is to provide enriched data from the Lisk SDK API. This component is designed to provide high availability, efficient and reliable access to the Lisk SDK API.

Template

The Template service is an abstract service whereby all of the services from Lisk Service are inherited from. It allows all services to share a similar interface and design pattern. The purpose here is to reduce code duplication and increase consistency between each service, hence simplifying code maintenance and testing.

Usage

Once Lisk Service is set up, configured and started, it is possible to retrieve data from the blockchain network.

Lisk Service provides the data through several alternative APIs:

The HTTP API

The HTTP API offers a RESTful API with various additional endpoints as compared to the HTTP API of a normal Lisk node.

This API can be utilized to build powerful wallets and user interfaces for blockchain applications which are built with the Lisk SDK.

Public Lisk Service APIs

There is a public HTTP API for every public Lisk blockchain network, which can be used to query the desired information from the network.

Example: Request data with curl

Example request: Obtain a list of all 101 currently forging delegates
curl -X GET "http://localhost:9901/api/v2/delegates/active?limit=101&offset=0" -H  "accept: application/json"
Example response
{
  "data": [
    {
      "address": "4935562234363081651L",
      "approval": "35.77",
      "missedBlocks": 157,
      "producedBlocks": 55222,
      "productivity": "99.72",
      "publicKey": "6122ac1fd71b437014ddbc4ec01e07879f5af1853536efaa0233bc12907c684b",
      "secondPublicKey": "6122ac1fd71b437014ddbc4ec01e07879f5af1853536efaa0233bc12907c684b",
      "rank": 93,
      "rewards": "109000000000",
      "username": "genesis_84",
      "vote": "4630668157412954"
    }
  ],
  "meta": {
    "count": 100,
    "offset": 25,
    "total": 43749
  },
  "links": {}
}

The JSON-RPC API

The WebSocket JSON 2.0 RPC API provides blockchain data in standardized JSON format over a WebSocket connection. The API uses the socket.io library and it is compatible with JSON-RPC 2.0 standard.

Check out the WebSocket JSON 2.0 RPC API reference for an overview of all available RPC requests.

Example: Emit to remote-procedure calls with socket.io

Use the socket.io-client to connect to the RPC API.

npm i socket.io-client@2
Specify version 2 of the socket.io client, as the current version 3 is not compatible with Lisk Service.
// 1. Require the dependencies
const io = require('socket.io-client'); // The socket.io client
const jsome = require('jsome'); // Prettifies the JSON output

jsome.params.colored = true;

// 2. Connect to Lisk Service via WebSockets
const socket = io('ws://localhost:9901/rpc-v2', {
  forceNew: true,
  transports: ['websocket']
});

// 3. Emit the remote procedure call
socket.emit('request', {
  jsonrpc: '2.0',
  method: 'get.delegates.next_forgers',
  params: {limit: "20", offset: "50"} },
  answer => {
    jsome(answer);
    process.exit(0);
});

The Subscribe API

The Subscribe API, or sometimes called the Publish/Subscribe or Event-Driven API. It uses a two-way streaming connection, which means that not only the client can request the server for a data update, but also the server can notify the client about new data instantly as it arrives.

Check out the Subscribe API reference for an overview of all available RPC requests.

Example: Subscribe to events with socket.io

Use the socket.io-client to connect to the RPC API.

npm i socket.io-client@2
Specify version 2 of the socket.io client, as the current version 3 is not compatible with Lisk Service.
const io = require('socket.io-client');
const jsome = require('jsome');

jsome.params.colored = true;

const socket = io('ws://localhost:9901/blockchain', {
	forceNew: true,
	transports: ['websocket'],
});

const subscribe = event => {
	socket.on(event, answer => {
		console.log(`====== ${event} ======`);
		// console.log(answer);
		jsome(answer);
	});
};

subscribe('update.block');
subscribe('update.round');
subscribe('update.forgers');
subscribe('update.transactions.confirmed');
subscribe('update.fee_estimates');

// To log all events
[
	'connect', 'reconnect',
	'connect_error', 'connect_timeout', 'error', 'disconnect',
	'reconnect', 'reconnect_attempt',
	'reconnecting', 'reconnect_error', 'reconnect_failed',
].forEach(item => {
	socket.on(item, res => {
		console.log(`Event: ${item}, res: ${res || '-'}`);
	});
});

// To log incoming data
['status'].forEach(eventName => {
	socket.on(eventName, newData => {
		console.log(
			`Received data from ws://localhost:9901/blockchain/${eventName}: ${newData}`,
		);
	});
});