Aggregate blockchain data with Lisk Service

Lisk Service is a web application middleware that allows interaction with various blockchain networks based on the Lisk protocol.

Data delivery to UI clients like Lisk Desktop, Lisk Mobile, or a custom frontend like Hello Frontend is the primary goal of Lisk Service. Lisk Service offers users a lot more information and endpoints as compared to node APIs, including geolocation and different statistics about network utilization. In addition, Lisk Service makes it possible to access all the live blockchain data such as the Lisk SDK API.

In this guide, you’ll learn to connect Lisk Service to a blockchain node. Lisk Service is installed in addition to a Lisk application such as Lisk Core or a blockchain client of a sidechain, to provide enriched network data for third-party services.

Pre-requisite

  1. It is required to set up a blockchain node.

    • Make sure that you have set up a blockchain node e.g. Lisk Core node. Please refer to the dedicated setup guides, such as the NPM setup.

    • Alternatively, you can setup up a sidechain node to connect with Lisk Service.

    • Please make sure to set system.keepEventsForHeights: -1 in the node config[1] before synchronizing the node with the network.

  2. It is required to set up Lisk Service.

1. Enable API on the blockchain node

We recommend using PM2 for running a node with the desired configurations.

  • --api-ws enables the WebSocket API of the node, if not already enabled within the config.json file.

  • --api-ws-host=0.0.0.0 allows remote servers to connect to the blockchain node via WS API. If this option is not set, it defaults to 127.0.0.1.

  • --api-ws-port=7887 is the port for the WebSocket API.

  • --api-http allows remote servers to connect with the blockchain node via HTTP.

  • --network or -n flag determines the blockchain network a node connects to. To connect to a specific network, mention either one of mainnet, default, testnet, or devnet with the network flag.

  • Lisk Core node

  • Sidechain node

lisk-core start --network mainnet --api-ws --api-ws-host=0.0.0.0 --api-ws-port=7887 --api-http

While using pm2.conf.json for running a node, the starting script can look like the following:

pm2.conf.json
{
  "apps": [
    {
      "name": "hello_client",
      "script": "./bin/run start --api-ws -n default --api-ws-host=0.0.0.0 --api-ws-port=7887 --api-http"
    }
  ]
}
The script assumes that the blockchain client has been built with npm run build and the pm2.conf.json assumes that it lies within the blockchain client’s root directory.

To start the node with your desired configurations mentioned above, execute the following command:

pm2 start pm2.conf.json

Once the node starts, follow the steps mentioned in the Connecting Lisk Service to a blockchain node section to connect Lisk Service with a node.

2. Running Lisk Service

Run the docker container for lisk-service, redis, and mysql or mariadb. It is recommended to use mariadb instead of mysql when running on Darwin.

  1. Run Lisk Service container:

    ./lisk-service/
    make up

  2. Run Redis container:

    ./lisk-service/jenkins/redis
    make up

  3. Run MariaDB container:

    ./lisk-service/jenkins/mariadb
    make up
If you installed Lisk Service via source then, follow the steps mentioned in the Source setup guide to run Lisk Service.

3. Checking established connection

After both the blockchain client and the Lisk Service are running and connected, you should see a similar entry in the logs of the blockchain node.

2023-06-27T11:03:39.085Z INFO XYZ.local engine 35439 New web socket client connected

Another hint that Lisk Service is now connected to your node is the occurrence of the following entry in the logs from the blockchain-connector service.

2023-06-26T16:09:28.435 INFO [app] Found a node, starting service LISK-SERVICE-BLOCKCHAIN-CONNECTOR...

You can also invoke an endpoint of the blockchain node via Lisk service API like the following, to verify that the connection was established successfully.

curl --location 'http://localhost:9901/api/v3/invoke' --header 'Content-Type: application/json' --data '{"endpoint": "chain_getLastBlock","params": {}}' | json_pp

You can now customize your UI to take advantage of all the enriched APIs of Lisk Service.

For more information about Lisk Service APIs, see the following pages:

1. Events are necessary to determine the transaction execution status and the actual block generation rewards. Without this information, Lisk Service wouldn’t be able to index all the transactions. Thus, the indexing will be incomplete. Setting "system.keepEventsForHeights: -1" will ensure that the events are not deleted and are maintained on the node for all the block heights. By default, the node only maintains the events for the last 300 blocks.