Connecting via endpoints

On this page, we discuss how endpoints of a Lisk blockchain node and Lisk products i.e., Lisk Service can be invoked. By default, Lisk exposes a range of endpoints to enable communication with a blockchain node. On top of that, the Lisk service also provides its own set of endpoints that offer even more extensive blockchain data.

Furthermore, Modules and Plugins of a blockchain client can also expose endpoints. By default, Lisk exposes various module-based endpoints as well, an example of which is the Auth module endpoints. It is also possible to develop endpoints for custom modules and plugins. For more information, see implementing endpoints for a module and creating an endpoint for a plugin guides, respectively.

In addition, further information can be found regarding module endpoints in the specific module endpoint reference pages, for example, the Auth module endpoint.

Preliminaries

  • In order to make the endpoints accessible, the configuration setting: rpc.allowedMethods should specify ["*"] to allow all methods.

  • Alternatively, it can specify the module name, for example, ["consensus","token","pos"], or the exact method names such as ["chain_getLastBlock", "system_getNodeInfo"] to expose them in the API.

  • For further details please see the Configuring Lisk Node section in the Lisk Core README file.

  • To interact with the node APIs through IPC, WS, or HTTP, it is necessary to enable the corresponding APIs. This can be done by configuring them in the node settings, using command line flags, or setting up the relevant environment variables when launching the Lisk application.

Connecting to a node

Invoking via API client

The API client simplifies sending API requests to a blockchain node.

External services communicate to a blockchain node via RPCs.

The RPC-based endpoint invocations to the nodes are possible over IPC, WS, or HTTP.

An API client can be imported into any JS client application as shown in the following snippets.

To conveniently communicate with a blockchain node, use the apiClient included in the @liskhq/lisk-client and the lisk-sdk packages.

  • WS API client example

  • IPC API client example

  • HTTP cURL

const { apiClient } = require('@liskhq/lisk-client');
let clientCache;
const nodeAPIURL = 'ws://localhost:7887/rpc-ws';

const getClient = async () => {
    if (!clientCache) {
        clientCache = await apiClient.createWSClient(nodeAPIURL);
    }
    return clientCache;
};


const blockId = "0f4ea1c3cfb61b99d387b26aaadf57936a528e5c713c6e55aa06f4d621b7e6f0";

getClient().then((client) => {
    client.invoke("chain_getBlockByID", {
        id: blockId
    }).then(res => {
        console.log("Result: ", res);
    });
});
const { apiClient } = require('@liskhq/lisk-client');
let clientCache;

const getClient = async () => {
    if (!clientCache) {
        // The data path to the blockchain client should be passed here
        // In our case, we are passing data path for the "hello_client"
        clientCache = await apiClient.createIPCClient('~/.lisk/hello_client');
    }
    return clientCache;
};

const blockId = "0f4ea1c3cfb61b99d387b26aaadf57936a528e5c713c6e55aa06f4d621b7e6f0";

getClient().then((client) => {
    client.invoke("chain_getBlockByID", {
        id: blockId
    }).then(res => {
        console.log("Result: ", res);
    });
});

Apart from the WS and IPC method, Lisk endpoints also support HTTP requests and response mechanisms. With a JSON RPC 2.0 based format, any endpoint can be invoked using a cURL request. For example, as shown below:

curl --location --request POST 'http://localhost:7887/rpc' \
--header 'Content-Type: application/json' \
--data-raw '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "chain_getBlockByHeight",
    "params": {
        "height": 2291
    }
}'

Lisk also supports invoking endpoints from within the blockchain client. For more information, check out the syncing and storing example for the HelloInfoPlugin. Specifically, the line of code shown in the following example:

private async _syncChainEvents(): Promise<void> {
    // 1. Get the latest block height from the blockchain
    const res = await this.apiClient.invoke<{ header: { height: number } }>("chain_getLastBlock", {});
    //[...]
}

Invoking via the CLI

Any endpoint within the Lisk ecosystem can be invoked via node CLI as well. For more information, check out the Client CLI page.

If you are running Lisk Core, you can use mostly the same CLI commands as in the general node CLI. Just replace ./bin/run with lisk-core in that case.

To invoke an endpoint via the CLI, simply use the endpoint:invoke command as shown in the following code snippet.

Invoking an endpoint via CLI
./bin/run endpoint:invoke chain_getLastBlock --pretty
Response
Example output
{
  "header": {
    "version": 2,
    "timestamp": 1662742534,
    "height": 110,
    "previousBlockID": "4ef1095d3560064dd4a66fb4543680efe65a64020c363571b107be9513628674",
    "stateRoot": "b2507620beb3be5cd7d0cbb7926e4365b5674b682673dc2423400a497636e13e",
    "assetRoot": "2aa695e23b36439b56130a490ef38feaaec57d82859ff64f5ca61cc49993afa3",
    "eventRoot": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
    "transactionRoot": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
    "validatorsHash": "84f3ed67cec1eb7bd6dc3ec01b0d0323021c1e86a3dc760b9b92041c28da31ac",
    "aggregateCommit": {
      "height": 0,
      "aggregationBits": "",
      "certificateSignature": ""
    },
    "generatorAddress": "lsk5y2q2tn35xrnpdc4oag8sa3ktdacmdcahvwqot",
    "maxHeightPrevoted": 0,
    "maxHeightGenerated": 110,
    "signature": "6ecd5c6f14d18f84a2125cca4186a6cc493dcd66338f9b13c580cc06be7a33267fe259a074d6f6dc9276aff700a985472fca15cbcf25b2fde1b621fe0810b507",
    "id": "334416bdc1f8a7ff842728ac4e591337a0e7b80f190934694cad7e2a9afdb416"
  },
  "transactions": [],
  "assets": [
    {
      "module": "random",
      "data": "0a10dde856a212ac5af46e26abb5f941cc8b"
    }
  ]
}

Connecting to Lisk Service

Invoking via WebSocket

Lisk Service WS-RPC endpoints are available to query under the /rpc-v3 namespace. The base URL of Lisk Service for WS-RPC is:

  • WS-RPC: wss://service.lisk.com/rpc-v3

For WS, the RPC endpoint name is passed in the method property after establishing a WebSocket connection using socket.io. An example of using the WS JSON-RPC API can be seen below.

Querying network status via WS JSON-RPC API
const io = require('socket.io-client');

const REQUEST_TIMEOUT = 10 * 1000;

const apiEndpoint = 'wss://service.lisk.com/rpc-v3';
const rpcEndpoint = 'get.network.status';
const rpcParams = {};

// Establishing socket.io connection
const socket = io(
	apiEndpoint,
	{
		forceNew: true,
		transports: ['websocket'],
	},
);

// Invoke "get.network.status" endpoint
socket.emit(
	'request', // channel on which Lisk Service handles the WS-RPC calls
	{
		method: rpcEndpoint,
		params: rpcParams,
	},
	answer => {
		console.log(JSON.stringify(answer, null, 2));
		process.exit(0);
	},
);

setTimeout(
	() => {
		console.log('Request timeout - could not get a response.');
		process.exit(1);
	},
	REQUEST_TIMEOUT,
);

For detailed information and examples, please visit the RPC API Lisk Service page.

Invoking the HTTP API

Lisk Service also offers the RESTful HTTP API with various additional endpoints, that for example, could be deployed to build user interfaces and wallets for blockchain applications that are compliant with the Lisk protocol.

There is a public Lisk Service HTTP API, which can be used to query the desired information from the Lisk Core mainchain network.

Lisk Mainnet
Lisk Testnet

The Lisk Service HTTP API can be accessed using request libraries such as Axios or a command-line tool such as cURL, as shown below.

  • HTTP Axios

  • HTTP cURL

An example of how to execute a GET request via axios in order to retrieve the network status is shown below:

const axios = require('axios');

const getEndpoint = 'https://service.lisk.com/api/v3/network/status';

axios.get(getEndpoint)
	.then((axiosResponse) => {
		const { data: apiResponse } = axiosResponse;
		console.log(JSON.stringify(apiResponse, null, 2));
	});

An example of how to execute a POST request via axios to validate a BLS key and Proof of Possession pair is shown below:

const axios = require('axios');

const postEndpoint = 'https://service.lisk.com/api/v3/validator/validate-bls-key';
const postEndpointParams = {
  blsKey: 'b301803f8b5ac4a1133581fc676dfedc60d891dd5fa99028805e5ea5b08d3491af75d0707adab3b70c6a6a580217bf81',
  proofOfPossession: '88bb31b27eae23038e14f9d9d1b628a39f5881b5278c3c6f0249f81ba0deb1f68aa5f8847854d6554051aa810fdf1cdb02df4af7a5647b1aa4afb60ec6d446ee17af24a8a50876ffdaf9bf475038ec5f8ebeda1c1c6a3220293e23b13a9a5d26',
};

axios.post(
	postEndpoint,
	postEndpointParams,
)
	.then((axiosResponse) => {
		const { data: apiResponse } = axiosResponse;
		console.log(JSON.stringify(apiResponse, null, 2));
	});

An example of how to execute a GET request via curl in order to retrieve the network status is shown below:

curl --location --request GET 'https://service.lisk.com/api/v3/network/status'

An example of how to execute a POST request via curl to validate a BLS key and Proof of Possession pair is shown below:

curl --location --request POST 'https://service.lisk.com/api/v3/validator/validate-bls-key' \
--header 'Content-Type: application/json' \
--data-raw '{
  "blsKey": "b301803f8b5ac4a1133581fc676dfedc60d891dd5fa99028805e5ea5b08d3491af75d0707adab3b70c6a6a580217bf81",
  "proofOfPossession": "88bb31b27eae23038e14f9d9d1b628a39f5881b5278c3c6f0249f81ba0deb1f68aa5f8847854d6554051aa810fdf1cdb02df4af7a5647b1aa4afb60ec6d446ee17af24a8a50876ffdaf9bf475038ec5f8ebeda1c1c6a3220293e23b13a9a5d26"
}'