Aggregate blockchain data with Klayr Service

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

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

In this guide, you’ll learn to connect Klayr Service to a blockchain node. Klayr Service is installed in addition to a Klayr application such as Klayr 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. Klayr 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 Klayr 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 Klayr 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.

  • Klayr Core node

  • Sidechain node

klayr-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 Klayr Service to a blockchain node section to connect Klayr Service with a node.

2. Running Klayr Service

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

  1. Run Klayr Service container:

    ./klayr-service/
    make up

  2. Run Redis container:

    ./klayr-service/jenkins/redis
    make up

  3. Run MariaDB container:

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

3. Checking established connection

After both the blockchain client and the Klayr 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 Klayr 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 KLAYR-SERVICE-BLOCKCHAIN-CONNECTOR...

You can also invoke an endpoint of the blockchain node via Klayr 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 Klayr Service.

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

To learn more about extending Klayr Service, see Extending the Indexer microservice.

1. Events are necessary to determine the transaction execution status and the actual block generation rewards. Without this information, Klayr 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.