Lisk Service is a web application middleware that allows interaction with various blockchain networks based on the Lisk protocol.
The main focus of Lisk Service is to provide data to the UI clients such as Lisk Desktop and Lisk Mobile. It allows accessing the live blockchain data similarly to the regular Lisk SDK API, albeit with more comprehensive features. Furthermore, Lisk Service also provides users with much more detailed information and endpoints, such as geolocation, network usage statistics, and more.
The project is a Microservices-based implementation. The technical stack design helps deliver several micro-services, whereby each one is responsible for a particular functionality. The data is served in JSON format and exposed by a public RESTful or a WebSocket-based RPC API.
Lisk Service comprises of multiple microservices that can operate independently of each other. The Gateway is required to expose the APIs provided by the specific services.
Every microservice is independently managed and placed in a separate directory under the services directory. They contain their own package.json and Dockerfile that are beneficial when running the applications.
| Service | Description |
|---|---|
| Gateway | The Gateway exposes the API for Lisk Service users to access and use over HTTP and WS protocols. Its main purpose is to proxy API requests from users to the concerned Lisk Service microservices. It provides the users with a central point of data access that ensures existing application compatibility. |
| Connector | The Blockchain Connector connects with the node running a Lisk protocol-compliant blockchain application. It is primarily responsible for data transformation and caching, thus reducing the number of calls made to the node. |
| Coordinator | The Blockchain Coordinator service is primarily responsible for ensuring the completeness of the index. It performs periodic checks for any gaps in the index and schedules tasks to update it, along with the latest block updates. |
| Indexer | The Blockchain Indexer service, in the indexing mode, is primarily responsible to update the index, based on the scheduled jobs by the Blockchain Coordinator. In the data service mode, it serves user request queries made via the RESTful API or WebSocket-based RPC calls. It can run both the indexer and data service modes simultaneously, which is enabled by default. |
| App Registry | The Blockchain Application Registry service is primarily responsible for regularly synchronizing and providing off-chain metadata information for known blockchain applications in the Lisk ecosystem. The metadata is maintained in the Lisk Application Registry repository. |
| Fee Estimator | The Fee Estimator service implements the dynamic fee system algorithm to offer users transaction fee recommendations based on the network traffic. |
| Transaction Statistics | The Transaction Statistics service, as the name suggests, is primarily responsible to compute various transaction statistics to offer users various real-time network insights. |
| Market | The Market service allows price data retrieval. It supports multiple sources to keep the current Lisk token price up-to-date and available to the clients in real time. |
| Export | The Export service enables users to download the transaction history as a CSV file for any given account on the blockchain. |
| Template | The Template service is an abstract microservice from which all Lisk Service services are inherited. It allows all services to share a similar interface and design pattern. Its purpose is to reduce code duplication and increase consistency between each service, hence, simplifying code maintenance and testing. |
Remarks
- Lisk Service by default attempts to connect to a local node via WebSocket on port
7887or IPC on~/.lisk/lisk-coreby default. - The default installation method is based on Docker.
- Some token conversion rates in the Market service require their API keys.
- For the events information to be always available in the API, please set
system.keepEventsForHeights: -1in the Lisk application node config. - It is highly recommended to NOT enable any plugins on the Lisk application node when running Lisk Service against it. Enabling them can cause performance issues in Lisk Service.
Inter-microservice communications are enabled with a message broker, typically an instance of Redis or NATS.
The Gateway service provides the following APIs, which all users of Lisk Service can access and use.
| API | Description |
|---|---|
| HTTP API | HTTP API is the public RESTful API that provides blockchain data in standardized JSON format. |
| WebSocket JSON-RPC API | The WebSocket-based JSON-RPC API provides blockchain data in standardized JSON format. The API uses the Socket.IO library and is compatible with JSON-RPC 2.0 standards. |
| Subscribe API | The Subscribe API is an event-driven API. It uses a two-way streaming connection, which can notify the client about new data instantly as it arrives. It is responsible for updating users regarding changes in the blockchain network and markets. |
The default port for REST API requests and Socket.IO-based communication is 9901. The API is accessible through the URL http://127.0.0.1:9901 when running locally. The REST API is accessible via HTTP clients such as Postman, cURL and HTTPie.
WebSocket-based APIs can be used through the Socket.IO library available for many modern programming languages and frameworks.
To continue the installation ensure that you have the following dependencies installed:
Follow the instructions listed below, to acquire detailed information regarding the installation of required dependencies for various operating systems.
Retrieve the latest release from the official repository.
Unpack the source code archive by executing the following commands listed below:
tar -xf lisk-service-x.y.z.tar.gz
cd lisk-serviceAlthough the above commands retrieve the entire source code, this instruction does not cover building a custom version of Lisk Service. For more information refer to this document: Building Lisk Service from source
If you wish to build the local version of Lisk Service execute the following command below:
make build-imagesThis step is only necessary if you wish to build a custom or pre-release version of Lisk Service that does not have a pre-built Docker image published on the Docker Hub. The installation script chooses the last available stable version on Docker Hub, unless there is no local image. If you are unsure about any local builds, use the
make cleancommand to remove all locally built docker images.
The following system requirements are recommended to start Lisk Service:
- Machines with a minimum of 16 GB RAM for the Mainnet.
- Machines with a minimum of 16 GB RAM for the Testnet.
- Machines with a minimum of 40 GB HDD.
The default configuration is sufficient to run Lisk Service against the local node.
Before running the application copy the default docker-compose environment file:
cp docker/example.env .envIn the next step, set the required environment variables.
$EDITOR .envThe example below assumes that the Lisk Core (or any Lisk protocol-compliant blockchain application) node is running on the host machine, and not inside of a Docker container.
## Required
# The local Lisk Core node WebSocket API port
export LISK_APP_WS="ws://host.docker.internal:7887"When running a node inside of a Docker container, the variable needs to refer to the container: LISK_APP_WS="ws://<your_docker_container>:7887".
Configuration options are described in this document.
Optional: Check your configuration with the command
make print-config
To run the application execute the following command:
make upTo stop the application execute the following command:
make downOptional: It is possible to use regular docker-compose commands such as
docker-compose up -d. Please check theMakefilefor more examples.
Assuming lisk-service is running on the 127.0.0.1:9901, and you are in the root of this repo, you can run the following:
cd tests
LISK_SERVICE_URL=http://127.0.0.1:9901 yarn run benchmarkThe possibility to customize and build Lisk Service from a local source is described in the following document Building Lisk Service from source. It may also be useful for PM2-based installations.
https://github.com/LiskHQ/lisk-service/graphs/contributors
Copyright 2016-2024 Lisk Foundation
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.